You're viewing documentation for unreleased changes. View the latest release.

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

KeyDescriptionTypeDefault
ai.enabledPositron 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.booleantrue
assistant.enabledEnable 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.booleantrue
positron.assistant.enableLegacy (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+.booleanfalse
assistant.defaultModel.idA 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.defaultModel.providerThe provider of the fixed model. Used with defaultModel.id to disambiguate when the same model ID is available from multiple providers.string""
assistant.defaultModel.thinkingEffortA 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.defaultModel.webSearchWhether web search is on when a new conversation starts. When not set, new conversations follow the conversation you are looking at.booleanfalse
assistant.mcpServersMCP server configuration. Same format as the mcpServers key in the config file.object{}
positron.assistant.aiExcludesA 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.modelRoutingControls how Posit Assistant accesses language models. See Model Routing below for the available options.string"prefer-direct"
assistant.showTipsShow helpful tips above the input after assistant turns and on startup. Disabling hides tips immediately without restarting.booleantrue
assistant.fastSearchSearch 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.booleantrue
assistant.previewFeaturesEnable preview Assistant features, which may still change before general availability. Shown with a Preview badge in the Settings UI.booleanfalse
assistant.advancedPositronIntegrationLet the assistant run Positron commands, such as reading and using apps in the Viewer pane, and use the skills Positron provides.booleantrue
assistant.cacheKeepaliveKeep supported model prompt caches warm while idle by sending lightweight pings after each turn.booleantrue
assistant.cacheKeepaliveMinutesMaximum 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.integer30
assistant.submitKeyKey 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 the main switch (Positron 2026.07+)

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.

📝 Older Positron builds

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"
      }
    }
  }
}
📝 Ignored header names

The following SDK-managed header names are ignored if set in customHeaders: Accept, anthropic-version, Authorization, Content-Type, x-api-key.

Experimental Settings

No stability guarantees

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.

KeyDescriptionTypeDefault
assistant.experimentalFeaturesEnable experimental in-development features that are still being refined. Experimental is the broader tier: enabling this also turns on everything in `assistant.previewFeatures`.booleanfalse
assistant.devModeEnable developer debugging surfaces such as raw tool data display, conversation path copying, and dev-only commands.booleanfalse
assistant.enablePersonaSelectorShow the persona selector in the status bar, allowing you to switch between additional assistant personas.booleanfalse
assistant.cacheKeepaliveWidgetShow 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.booleanfalse

Model Routing

The assistant.modelRouting setting controls how the assistant connects to language models:

ValueDescription
prefer-direct(Default) Use direct API access when available, fill in remaining providers from Positron’s language model API.
directOnly use direct API access via configured credentials.
vscode-lmOnly use Positron’s built-in language model API.
prefer-vscode-lmPrefer Positron’s language model API, fill in remaining providers from direct access.
💡 When to change model routing

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 enforced id with no provider pins the model and leaves the provider free. The old assistant.preferredModel.* names still work for one release, as a fallback per level (workspace, user): at each level the assistant.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.json files (project over global) → any Positron setting you have set → default administrator settings → Positron’s declared default. The existing rule that the settings.json files 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.

📝 Using both enforced-settings channels

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.

OptionRead byHow it blocks
positron.assistant.aiExcludes in Positron settingsPositron’s AI features, including Posit AssistantPrompts 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 hostThe 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.aiExcludes in POSITRON_ENFORCED_SETTINGS applies to every Positron AI feature that reads the setting. In Posit Assistant, that’s the read and edit tools.
  • deny rules in POSIT_ASSISTANT_SETTINGS_ENFORCED cover Posit Assistant only, in every host, and can also set ask or allow per pattern. See Administrator Policy.
⚠️ Not a sandbox

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, and classifierModels are 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:

  1. Enforced administrator settings — features.<key> in POSIT_ASSISTANT_SETTINGS_ENFORCED
  2. Positron workspace setting — assistant.<key> set at the workspace level in Positron
  3. Project config file — features.<key> in .posit/assistant/settings.json in your project
  4. Positron user setting — assistant.<key> set at the user level in Positron
  5. Global config file — features.<key> in ~/.posit/assistant/settings.json
  6. Default administrator settings — features.<key> in POSIT_ASSISTANT_SETTINGS_DEFAULT
  7. 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.