Positron Settings

When running inside Positron, Posit Assistant is configured through 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	Type	Default	Description
`assistant.enabled`	`boolean`	`false`	Enable Posit Assistant chat and AI features. When disabled, the sidebar is still visible but chat functionality is unavailable.
`assistant.sidebarView`	`boolean`	`true`	Show the Posit Assistant sidebar view in the activity bar.
`assistant.preferredModel.id`	`string`	`""`	The preferred language model ID to use by default. If specified and available, this model is selected automatically when Posit Assistant starts.
`assistant.preferredModel.provider`	`string`	`""`	The preferred model provider. Used with preferredModel.id to disambiguate when the same model ID is available from multiple providers.
`assistant.preferredModel.thinkingEffort`	`string`	`""`	Default thinking effort level for models that support adaptive thinking (e.g., 'low', 'medium', 'high').
`assistant.preferredModel.webSearch`	`boolean`	`false`	Whether web search is enabled by default.
`assistant.mcpServers`	`object`	`{}`	MCP server configuration. Same format as the mcpServers key in the config file.
`assistant.aiExcludes`	`string[]`	`[]`	Glob patterns for files excluded from AI access. For example, [".env", "secrets/*"] blocks matching files from being read, written, or edited. Patterns without a `/` match filenames in any directory. Admin policies can enforce non-overridable patterns.

MCP Servers in Positron

MCP servers can be configured either in the 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.

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

📝 Ignored header names

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

Advanced Settings

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

Key	Type	Default	Description
`assistant.modelRouting`	`string`	`"prefer-direct"`	Controls how Posit Assistant accesses language models. See Model Routing below for the available options.
`assistant.enableCopilotSdk`	`boolean`	`false`	Experimental. When enabled, Copilot models can be accessed through the direct Copilot SDK provider and participate in the modelRouting preference. When disabled (default), Copilot is only available through Positron's built-in language model API — Copilot models will not appear when modelRouting is set to direct.
`assistant.experimentalFeatures`	`boolean`	`false`	Enable experimental in-development features, such as additional assistant personas. Behavior may change between releases. Not exposed in the Settings UI — edit settings.json directly.

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.

💡 When to change model routing

Most users should leave this at the default (prefer-direct).

Relationship to Config File

Positron reads settings from both VS Code settings and the shared config file (~/.positai/settings.json). VS Code settings handle Positron-specific behavior like model routing and sidebar visibility. The config file handles shared settings like runtime paths, permissions, and storage — these apply across all platforms.

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.