Positron Settings
When running inside Positron, Posit Assistant is configured through Positron / VS Code settings in addition to the shared config file. These settings are accessed via Settings (Cmd+, / Ctrl+,) and use the assistant.* prefix.
Settings Reference
| Key | Description | Type | Default |
|---|---|---|---|
ai. | Positron 2026.07+ only. Positron's main switch for all AI features. When off, Posit Assistant is unavailable regardless of assistant.enabled. To use the assistant, both ai.enabled and assistant.enabled must be on. Not consulted on older Positron versions. | boolean | true |
assistant. | Enable Posit Assistant chat and AI features. When disabled, the sidebar icon remains visible and opens an explanation, while editor panel commands are unavailable. Has no effect when ai.enabled is off (Positron 2026.07+). On older Positron versions (< 2026.07), explicit assistant.enabled overrides the legacy positron.assistant.enable setting. | boolean | true |
positron. | Legacy (Positron < 2026.07 only). Enables Posit Assistant on older Positron versions where ai.enabled does not exist. Overridden by explicit assistant.enabled workspace or user settings. Not present on Positron 2026.07+. | boolean | false |
assistant. | A fixed model for every new conversation. If it is unavailable, the model picker shows no selection until you choose one. Leave blank to have new conversations start with the model of the conversation you are looking at. Picking a model in the UI never changes this setting. The old name, assistant.preferredModel.id, still works for one release; rename it. | string | "" |
assistant. | The provider of the fixed model. Used with defaultModel.id to disambiguate when the same model ID is available from multiple providers. | string | "" |
assistant. | A fixed thinking effort level for every new conversation, for models that support it (e.g., 'low', 'medium', 'high'). Leave blank to follow the conversation you are looking at. | string | "" |
assistant. | Whether web search is on when a new conversation starts. When not set, new conversations follow the conversation you are looking at. | boolean | false |
assistant. | MCP server configuration. Same format as the mcpServers key in the config file. | object | {} |
positron. | A Positron setting: glob patterns for files that Positron AI features leave out, including next edit suggestions, notebook ghost cells, and Posit Assistant. For example, ["*.env", "secrets/**"]. Patterns without a `/` match filenames in any directory. Left at the default, Posit Assistant asks before its read and edit tools open a matching file. Once you change the setting, those tools are blocked. Shell commands and running code are not covered. See Excluding Files from AI below. | string[] | Sensitive files and version-control folders |
assistant. | Controls how Posit Assistant accesses language models. See Model Routing below for the available options. | string | "prefer-direct" |
assistant. | Show helpful tips above the input after assistant turns and on startup. Disabling hides tips immediately without restarting. | boolean | true |
assistant. | Search file contents with the grep tool, backed by Positron's bundled ripgrep, in local workspaces. When off, the assistant uses the older search tool. Takes effect after a window reload. Temporary; will be removed once grep is the only option. | boolean | true |
assistant. | Enable preview Assistant features, which may still change before general availability. Shown with a Preview badge in the Settings UI. | boolean | false |
assistant. | Let the assistant run Positron commands, such as reading and using apps in the Viewer pane, and use the skills Positron provides. | boolean | true |
assistant. | Keep supported model prompt caches warm while idle by sending lightweight pings after each turn. | boolean | true |
assistant. | Maximum number of minutes after a real model request during which automatic cache-keepalive pings may be sent (0–60). Cadence and projected-cold time depend on the selected model. | integer | 30 |
assistant. | Key that submits the chat input. "enter" sends the message on Enter (Shift+Enter inserts a newline). "modEnter" inserts a newline on Enter and sends with ⌘Enter on macOS or Ctrl+Enter on Windows/Linux. "default" (the default) follows the chat-input preference in Posit Assistant's settings; choosing either key here pins it and takes precedence over that preference. | string | "default" |
ai.enabled is a Positron setting (not an assistant.* setting) that gates
all of Positron’s AI features. It takes precedence over assistant.enabled:
when ai.enabled is off, Posit Assistant is disabled even if
assistant.enabled is on (including when an admin policy enforces
assistant.enabled to true). When ai.enabled is on (the default), the
assistant follows its own assistant.enabled setting.
ai.enabled is available starting in Positron 2026.07. On older versions
(< 2026.07), enablement is governed by the positron.assistant.enable
setting instead, and ai.enabled is not consulted.
MCP Servers in Positron
MCP servers can be configured either in the Positron / VS Code settings (assistant.mcpServers) or in the shared config file (mcpServers key). The format is the same in both locations. See the MCP Servers guide for configuration details.
Plugins in Positron
Plugins have no Positron / VS Code settings. Registrations, enablement, host credentials, and administrator lockdown all live in the shared config file and behave the same here as on RStudio, Standalone, Desktop, and the terminal — including which file each key may come from and how an administrator lockdown composes with your own. Most users never edit those keys by hand; the plugin manager writes them.
See Plugins & Marketplaces for the feature guide, global vs. project scope for where a declaration is recorded, and enterprise administration for the policy tier.
Subagent Model Tiers
Positron supports the shared config file’s modelTiers
setting for choosing preferred low, medium, and high models for internal work. This setting is
config-file-only; put it in global ~/.posit/assistant/settings.json or project
.posit/assistant/settings.json, not under the assistant.* VS Code settings namespace.
Global and project values merge per tier, so a project can override high while inheriting
the global low and medium entries. Positron reads the preference when each subagent, exploration,
summary, or delegated web search resolves its model — your main conversation model is unaffected.
File edits therefore take effect on the next resolution without a restart. See the config-file
reference for matching, object-form thinking-effort defaults, and provider-local fallback rules.
Custom Base URLs and Headers
Posit Assistant reads custom base URLs and custom HTTP headers from the shared provider config
file, ~/.posit/ai/providers.json, the same as on every other platform. See
Route a provider through an enterprise proxy or gateway
for the providers.<id>.baseUrl and providers.<id>.customHeaders keys. These are useful for enterprise proxies, custom API
gateways, or local development servers — including gateways like Databricks that require extra
tenancy or routing markers on every request.
On Positron builds before 2026.08.0-249, Posit Assistant also falls back to Positron’s own
legacy authentication.* settings (authentication.anthropic.baseUrl,
authentication.snowflake.customHeaders, and so on) if providers.json doesn’t set a value.
This fallback is being phased out as Positron migrates users onto providers.json, so set new
base URLs and headers there instead.
customHeaders is an object mapping header name to value, attached to model-discovery and chat requests for providers whose transport supports it — see the providers.json reference for which providers forward it and which ignore it:
{
"providers": {
"openai": {
"customHeaders": {
"x-gateway-tenant": "team-42"
}
}
}
}
The following SDK-managed header names are ignored if set in customHeaders:
Accept, anthropic-version, Authorization, Content-Type, x-api-key.
Experimental Settings
The settings in this section are experimental or developer-facing. They may change, break, or be removed between releases without notice. Use them at your own risk. Documentation here may lag behind the actual behavior.
These settings are not exposed in the Positron Settings UI — edit settings.json directly. They can also be set in the shared config file via the features block, and values from both locations are merged. See How Feature Settings Are Merged for priority order.
| Key | Description | Type | Default |
|---|---|---|---|
assistant. | Enable experimental in-development features that are still being refined. Experimental is the broader tier: enabling this also turns on everything in `assistant.previewFeatures`. | boolean | false |
assistant. | Enable developer debugging surfaces such as raw tool data display, conversation path copying, and dev-only commands. | boolean | false |
assistant. | Show the persona selector in the status bar, allowing you to switch between additional assistant personas. | boolean | false |
assistant. | Show a status-bar widget with cache warmth state, a countdown to the next ping, and controls to extend, reduce, or stop the idle ping chain. Requires cache keepalive to be enabled. | boolean | false |
Model Routing
The assistant.modelRouting setting controls how the assistant connects to language models:
| Value | Description |
|---|---|
prefer-direct | (Default) Use direct API access when available, fill in remaining providers from Positron’s language model API. |
direct | Only use direct API access via configured credentials. |
vscode-lm | Only use Positron’s built-in language model API. |
prefer-vscode-lm | Prefer Positron’s language model API, fill in remaining providers from direct access. |
Most users should leave this at the default (prefer-direct).
Administrator-Managed Settings
Posit Assistant reads two environment variables that let an administrator supply — or lock — any
setting in the shared config file vocabulary:
POSIT_ASSISTANT_SETTINGS_ENFORCED and POSIT_ASSISTANT_SETTINGS_DEFAULT. The payload format,
rejected keys, and error reporting are the same on every platform and are documented in
Administrator-Managed Settings.
What is specific to Positron is where the two layers sit relative to Positron’s own settings. They bracket every user tier: the enforced layer is consulted first everywhere, and the default layer last, just above whatever Positron declares as its built-in default.
- Feature settings — the 7-tier order in How Feature Settings Are Merged.
assistant.defaultModel— the same order minus the declared default (Positron declares no built-in model), still resolved key by key, so an enforcedidwith noproviderpins the model and leaves the provider free. The oldassistant.preferredModel.*names still work for one release, as a fallback per level (workspace, user): at each level theassistant.defaultModel.*settings apply if that level sets any of them, otherwise the old names do, never mixed within a level. Values are not moved automatically, so rename them. Reload open windows after upgrading.assistant.mcpServers— merged by server name across the same layers, with the default layer applied first and the enforced layer last. An enforced entry pins that one server (including"enabled": false) and leaves every other server configurable.- Everything else (for example
sandbox.enabled) resolves: enforced administrator settings →settings.jsonfiles (project over global) → any Positron setting you have set → default administrator settings → Positron’s declared default. The existing rule that thesettings.jsonfiles outrank Positron settings for these keys is unchanged.
Both layers are read once when the extension host starts, so they survive editing or reloading your settings files. Writes from the Settings UI and from Posit Assistant itself always target your own files and settings — an enforced value is never copied into them, and a write to an enforced key simply has no effect.
Positron has its own enforced-settings mechanism, POSITRON_ENFORCED_SETTINGS, which covers IDE
settings generally. Route Posit Assistant settings through POSIT_ASSISTANT_SETTINGS_ENFORCED and
leave POSITRON_ENFORCED_SETTINGS for IDE settings. Where a key is set in both, the Posit
Assistant channel wins.
The exception is positron.assistant.aiExcludes. Set it in POSITRON_ENFORCED_SETTINGS so every
Positron AI feature that reads the setting uses it. Posit Assistant treats those patterns as a
deny for its read and edit tools. See Excluding files from AI.
Excluding Files from AI
There are two ways to keep Posit Assistant’s read and edit tools away from files that match a pattern.
| Option | Read by | How it blocks |
|---|---|---|
positron.assistant.aiExcludes in Positron settings | Positron’s AI features, including Posit Assistant | Prompts while it’s at Positron’s default list. Once you change it, the read and edit tools are blocked for matching files. |
A deny rule in your config file, for example "permission": { "read": { "secrets/**": "deny" } } | Posit Assistant only, in every host | The tool you name is blocked for matching files. Use read and edit keys to cover both. |
Your own blocks stop a read or edit without a prompt. An approval you give for this conversation can still cover a matching file, so for a guarantee, ask your administrator to set the pattern.
Administrators have the same two options. Both block the tools they cover, and users can’t approve a matching file or override the pattern in their own settings.
positron.assistant.aiExcludesinPOSITRON_ENFORCED_SETTINGSapplies to every Positron AI feature that reads the setting. In Posit Assistant, that’s the read and edit tools.denyrules inPOSIT_ASSISTANT_SETTINGS_ENFORCEDcover Posit Assistant only, in every host, and can also setaskorallowper pattern. See Administrator Policy.
These patterns block Posit Assistant’s read and edit tools. They don’t stop a shell command
(such as cat secrets.env) or code run in a console or notebook from opening the same file. If
files must stay out of reach, also restrict shell commands and code execution, for example with
deny rules for bash in POSIT_ASSISTANT_SETTINGS_ENFORCED.
Relationship to Posit Assistant Config File
Positron reads settings from both Positron / VS Code settings and the shared config file (~/.posit/assistant/settings.json and project-level .posit/assistant/settings.json). Some settings live in only one place, while others can be set in either:
- Positron-only — Model routing and sidebar visibility are Positron / VS Code settings with no config-file equivalent.
- Config-file-only — Runtime paths, permissions, storage, logging,
modelTiers, andclassifierModelsare shared across all platforms and have no VS Code setting. - Both — Feature settings like tips, cache keepalive, auto-compaction, and experimental features can be set in either location and are merged together.
How Feature Settings Are Merged
When a feature setting (tips, cache keepalive, auto-compaction, experimental features) exists in both Positron / VS Code settings and the config file, Positron resolves them using a 7-tier priority — the first defined value wins:
- Enforced administrator settings —
features.<key>inPOSIT_ASSISTANT_SETTINGS_ENFORCED - Positron workspace setting —
assistant.<key>set at the workspace level in Positron - Project config file —
features.<key>in.posit/assistant/settings.jsonin your project - Positron user setting —
assistant.<key>set at the user level in Positron - Global config file —
features.<key>in~/.posit/assistant/settings.json - Default administrator settings —
features.<key>inPOSIT_ASSISTANT_SETTINGS_DEFAULT - Declared default — the built-in default value
This means a project-level config file overrides your Positron user settings, and a Positron workspace setting overrides everything except an administrator’s enforced value. An administrator default (tier 6) is used only when nobody has set the key, and it beats the built-in default. Settings that aren’t declared in Positron’s Settings UI, such as assistant.autoCompactTokenBuffer, are effectively read from settings.json or the config file only.
Tiers 1 and 6 are absent unless your administrator has set them — see Administrator-Managed Settings.
Model preferences like thinking effort and web search are set as defaults in the config file (model.thinkingEffort, model.webSearch) and applied when starting new conversations. During a conversation, these preferences are adjusted via the UI and stored per-conversation — they are not written back to the config file.