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

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.

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"
      }
    }
  }
}

Advanced Settings

These settings cover lower-level routing controls and feature toggles. Most users don’t need to change them.

Experimental Settings

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.

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.

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.preferredModel — 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.
• 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.

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, and modelTiers 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.