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

Plugin registrations and enablement are managed through the plugin manager and stored under assistant.* settings. Most users don’t set these by hand.

These keys are scope: application (user scope), so a .vscode/settings.json in a repository can never declare a marketplace or enable a plugin. When you install with Project scope in the manager, the declaration goes into the workspace’s .posit/assistant/settings.json instead, which is only read in a trusted workspace.

Plugin Enforcement (Admins)

Administrators on Posit Workbench can lock down plugin usage by delivering the keys below through Workbench’s enforced-settings channel. These are loaded into Positron’s non-overridable policy tier, so a user cannot grant themselves access the admin hasn’t allowed. Enforcement is applied at activation, so a blocklist added after a plugin was installed deactivates it.

Deliver these as a JSON settings object in an /etc/rstudio/positron-enforced-settings/*.json file registered per-scope in /etc/rstudio/profiles. See the enforced-settings admin docs for the delivery mechanism.

Custom Base URLs and Headers

Posit Assistant respects custom base URLs and custom HTTP headers configured in Positron’s language model provider settings. 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.

These are Positron authentication settings (authentication.*), not assistant.* settings — they live in the same namespace as the provider’s credentials and apply to all extensions that use the provider. The base URL can be set through the model provider configuration UI; customHeaders is set directly in settings.json.

The supported settings are:

Provider	Base URL	Custom Headers
Anthropic	authentication.anthropic.baseUrl	authentication.anthropic.customHeaders
OpenAI	authentication.openai-api.baseUrl	authentication.openai-api.customHeaders
OpenAI Compatible	authentication.openai-compatible.baseUrl	authentication.openai-compatible.customHeaders
Microsoft Foundry	authentication.foundry.baseUrl	authentication.foundry.customHeaders
Snowflake	derived from authentication.snowflake.credentials	authentication.snowflake.customHeaders

customHeaders is an object mapping header name to value, attached to every model-discovery and chat request for the provider:

{
  "authentication.openai-api.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.

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, and logging 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 5-tier priority — the first defined value wins:

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

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.