Configuration File
Posit Assistant is configured through a JSON settings file. This file controls model selection, behavior preferences, runtime configuration, permissions, and more.
File Locations
In previous versions, the configuration directory was ~/.positai (global) and .positai/ (project-level).
These have been renamed to ~/.posit/assistant and .posit/assistant/. Existing files are migrated automatically
on first launch.
Posit Assistant uses two levels of configuration:
-
Global config applies to all projects. Located at:
- macOS / Linux:
~/.posit/assistant/settings.json - Windows:
%USERPROFILE%\.posit\assistant\settings.json
- macOS / Linux:
-
Project config overrides global settings for a specific project. Place a
.posit/assistant/settings.jsonfile in your project root.
Some settings (like providers, storage, and logging) are global-only. Others (like model, permissions, and MCP servers) can be set at either level, with project values taking precedence. The sections below indicate which level each setting supports.
Settings are resolved in this order (last wins): defaults → global config → project config → environment variables → CLI flags.
In a managed deployment your administrator can add two more layers, one below everything and one above everything. See Administrator-Managed Settings.
Editor Schema
A JSON Schema for the global settings file is hosted at a stable URL:
https://assistant.posit.co/schemas/settings.schema.json
Reference it from the $schema field of your global ~/.posit/assistant/settings.json to get hover documentation and validation in editors like VS Code and Positron:
{
"$schema": "https://assistant.posit.co/schemas/settings.schema.json"
}
The hosted schema validates the global file. Project-level .posit/assistant/settings.json
files allow keys the global schema forbids (such as tools.allowed and tools.blocked), so do
not reference this URL from a project file — your editor would flag valid configuration.
Per-Project Settings
The following settings can be set in either the global ~/.posit/assistant/settings.json or a project-level .posit/assistant/settings.json. Project values take precedence over global values.
Model Settings
Use modelTiers to prefer particular models for internal low, medium, and high work by subagents,
for project exploration, conversation summaries, and delegated web search. These tiers only affect
internal work — the model for your main conversation is the one in the model picker (or the fixed
defaultModel below). Each value
is an ordered list of case-insensitive substrings matched against model IDs on the current provider:
{
"modelTiers": {
"low": ["luna", "haiku"],
"medium": ["terra"],
"high": ["sol", "opus", "pro"]
}
}
The first substring with any matches wins; when it matches multiple versions, Posit Assistant uses the newest. Unmatched entries are skipped. All three keys are optional. Changes take effect on the next model resolution without restarting the assistant.
A preference that exactly names a model — its full ID or the part of the ID after the
last / — takes precedence over substring matching. This disambiguates models where
one ID is a prefix of another: Posit AI Pass lists both zai-org/GLM-5.3 and
zai-org/GLM-5.3-Flash, and "medium": ["glm-5.3"] selects the regular GLM-5.3
because it names that model exactly, while "glm-5.3-flash" selects the Flash
variant. Without exact matching, no substring of glm-5.3 could exclude the Flash
model.
Preferences that name only a version track the newest release: with GLM-5.2, GLM-5.3,
and GLM-5.3-Flash all available, "medium": ["glm-5"] selects GLM-5.3. When several
models tie on the newest version, the base model wins over suffixed variants like
Flash — name the variant in the preference if you want it.
Each tier also accepts an object form that sets a default thinking effort for subagents launched on that tier:
{
"modelTiers": {
"low": { "models": ["luna", "haiku"], "thinkingEffort": "low" },
"high": { "models": ["sol", "opus", "pro"], "thinkingEffort": "max" }
}
}
The thinking effort default applies to subagents launched on that tier; without one,
high subagents default to "high" and low and medium subagents to "medium". A default the resolved
model does not support maps to its nearest supported level (ties round down), falling back
to the provider’s own default behavior only when the model has no mappable level.
Project and global modelTiers settings merge per tier: a project high entry replaces
the global high entry wholesale (object form included) while omitted project low and
medium entries continue to use the global ones. Auto mode’s safety classifier ignores
these preferences; choose its model with the global-only
classifierModels setting instead.
Tier requests (low, medium, or high) check the same-named list before built-in
defaults. Subagents request a tier through the launchSubagent tool’s difficulty, which may be
higher than the tier of the model launching them. Concrete model names are server policy rather than tool request values. Built-in
fallbacks prefer the launching model’s family, then may select another family on the same
provider, and finally inherit the launching model. Model selection never changes providers.
When several models share the newest version, the built-in fallbacks choose the standard model
over variants such as Pro or batch versions (GPT-5.6 Terra over GPT-5.6 Terra Pro). A snapshot
date only chooses between snapshots of the same model, so a newer-dated variant does not win.
| Key | Description | Type | Default |
|---|---|---|---|
modelTiers. | Ordered model-ID substrings preferred for low-tier internal work, with an optional default thinking effort for subagents. The first substring with a match wins. | string[] | { models: string[], thinkingEffort?: string } | [] |
modelTiers. | Ordered model-ID substrings preferred for medium-tier internal work, with an optional default thinking effort for subagents. The first substring with a match wins. | string[] | { models: string[], thinkingEffort?: string } | [] |
modelTiers. | Ordered model-ID substrings preferred for high-tier internal work, with an optional default thinking effort for subagents. The first substring with a match wins. | string[] | { models: string[], thinkingEffort?: string } | [] |
defaultModel. | A fixed model for every new conversation. If it is unavailable, the model picker shows no selection until you choose one. Leave empty to follow the conversation you are looking at. | string | "" |
defaultModel. | The provider of the fixed model (for example "positai" for Posit AI Pass), for when the same model ID is available from more than one provider. | string | "" |
defaultModel. | A fixed thinking effort level for new conversations. During a conversation, thinking effort is adjusted in the UI and stored per conversation. | string | — |
defaultModel. | A fixed web search setting for new conversations. During a conversation, web search is toggled in the UI and stored per conversation. | boolean | — |
How a new conversation picks its model
defaultModel is a fixed choice that only you write: picking a model in the UI never changes it.
A new conversation (the New button, /new, /clear, a new tab) takes each of the model, thinking
effort, and web search settings from the first of these that sets it:
defaultModel, from any source: administrator settings, a project or globalsettings.json, Positron’sassistant.defaultModel.*settings, or the--modelflag andPA_MODELvariable.- The conversation you are looking at.
- The last model a conversation showed in this app, remembered across workspaces.
- The built-in default.
A model from steps 2 or 3 that is no longer available is skipped. A defaultModel.id that is not
available is not skipped: the model picker shows no selection, so you notice. Opening an existing
conversation always restores that conversation’s own model.
/clear swaps steps 1 and 2: it keeps the settings of the conversation you are looking at, and
defaultModel fills only what that conversation doesn’t set. Use /new to start from
defaultModel.
Earlier versions saved every model you picked to preferredModel in your global settings.json,
so it acted as a fixed choice you never made. Since version 1.9.0, preferredModel is ignored in
every global settings file. On the first start after upgrading, its value is copied into the
remembered model (step 3), and the file gets a comment field inside preferredModel saying it is
ignored. The key is never deleted, so older versions keep working with it (they log a harmless
notice about the unrecognized comment). To keep a fixed model, rename the key to defaultModel
and delete the comment. This includes a preferredModel you wrote by hand, for example by copying
an example file: it no longer pins anything until renamed.
Permissions
Control which capabilities the assistant can use. Each key is a permission key, usually a tool
name (bash, read, edit, etc.), mapped to either an action string or an object of patterns
for that capability’s match target. For example, bash patterns match commands, while task
patterns match the subagent type requested through launchSubagent:
{
"permission": {
"bash": {
"git *": "allow",
"rm *": "deny"
},
"read": "allow",
"edit": "ask",
"task": {
"explore": "deny",
"general": "ask"
}
}
}
The former permission.explore key is no longer supported. Move its "allow", "ask", or
"deny" value to permission.task.explore.
You can also set a single action for all tools as a shorthand:
{
"permission": "ask"
}
| Key | Description | Type | Default |
|---|---|---|---|
permission | Permission configuration. Set to "allow", "ask", or "deny" for all capabilities, or use per-key rules whose patterns match the relevant input, such as shell commands, file paths, or subagent types. | string | object | — |
When you grant or deny permissions through the UI, they are saved to your project-level
.posit/assistant/settings.json. If you want permissions to apply across all projects, copy the
permission block to your global ~/.posit/assistant/settings.json instead.
MCP Servers
Connect external tool servers using the Model Context Protocol.
{
"mcpServers": {
"my-server": {
"type": "local",
"command": ["node", "server.js"],
"env": {
"API_KEY": "..."
}
},
"remote-server": {
"type": "remote",
"url": "https://mcp.example.com",
"headers": {
"Authorization": "Bearer ..."
}
}
}
}
| Key | Description | Type | Default |
|---|---|---|---|
type | Server type. "local" for stdio subprocess, "remote" for HTTP/SSE. When omitted, a server with a `url` and no `command` is remote; otherwise it is local. | string | inferred |
command | Command and arguments to start a local MCP server. | string[] | — |
env | Environment variables for a local MCP server. `environment` is an alias for `env`. A server that sets both is not started. | object | — |
url | URL of a remote MCP server. | string | — |
enabled | Whether this server is active. | boolean | true |
timeout | Connection timeout in milliseconds. | number | 10000 |
MCP servers can be configured in either the project-level .posit/assistant/settings.json or the global
~/.posit/assistant/settings.json. Project-level servers are merged with global servers by server name,
with project values taking precedence. Project-level servers — and a project-level mcp admission
policy — apply only in a trusted workspace; they are dropped entirely while the workspace is
untrusted. Use project-level config for project-specific servers and global config for servers you
want available everywhere.
command, env, url, and headers values can contain {env:NAME} references to environment
variables. A server whose reference can’t be resolved does not start. See
Environment Variables.
The sibling mcp key controls which configured servers may run at all — see
Admission Policy.
Skills
Control where Posit Assistant discovers custom skills.
| Key | Description | Type | Default |
|---|---|---|---|
skills. | Directories to search for skills, processed in order. Paths starting with ~ or $HOME are expanded to the home directory. Relative paths are resolved against each workspace root. | string[] | ["~/.agents/skills", "~/.posit/assistant/skills", ".agents/skills", ".posit/assistant/skills"] |
When the same skill name exists in more than one directory, the version from the later directory is used.
When both global and project-level configs define skills.paths, the project value
completely replaces the global value — paths are not merged. To extend the defaults, repeat them
in your project config alongside any additions.
Plugins
Register plugin marketplaces and control which plugins are enabled. These keys are normally managed for you by the plugin manager, but you can also edit them directly. See Plugins & Marketplaces for the full feature guide.
{
"extraKnownMarketplaces": {
"acme": { "source": "acme/plugins" }
},
"enabledPlugins": {
"data-tools@acme": true
}
}
| Key | Description | Type | Default |
|---|---|---|---|
extraKnownMarketplaces | Declared plugin marketplaces, keyed by name. Each value gives the marketplace source (a GitHub owner/repo, a git URL, or a local path). Readable from a project config in a trusted workspace, where it merges with your global marketplaces. | object | {} |
enabledPlugins | Plugin enablement keyed by "<plugin>@<marketplace>". true = enabled, false = installed but disabled, absent = not installed. Readable from a project config in a trusted workspace, where it merges with your global entries. | object | {} |
plugins. | Restrict which component types a plugin may contribute (e.g. ["skills", "commands", "mcpServers"]). Unknown values are ignored. Omitted means no restriction. A project config can narrow this further but never widen it. | string[] | all types |
plugins. | Per-host git credential references for private marketplaces, as {env:VAR} environment-variable references only. Global scope only, so a project config cannot inject credentials. | object | {} |
plugins. | Marketplace allowlist. Omitted means open (any marketplace); [] means no marketplace is allowed; a non-empty list allows only matching marketplaces. Each entry is a matcher: {"source":"github","github":"owner/repo"}, {"source":"url","url":"..."}, {"source":"hostPattern","hostPattern":"..."} or {"source":"pathPattern","pathPattern":"..."} (the two pattern forms are regular expressions). Global scope only. | array | — |
plugins. | Marketplace denylist, using the same matcher entries as strictKnownMarketplaces. A match is blocked regardless of the allowlist. Global scope only. | array | — |
Unlike plugins.allowedComponents, which ignores values it doesn’t recognize, an unusable entry in
strictKnownMarketplaces or blockedMarketplaces — an unknown source, or a pattern that isn’t a
valid regular expression — is a validation error rather than being quietly skipped. A silently
dropped denylist entry would leave a marketplace reachable with nothing saying why.
extraKnownMarketplaces, enabledPlugins, and plugins.allowedComponents can each be set
globally or in a project config, and the plugin manager lets you choose which file it writes to.
Project entries are only read in a workspace you have trusted, and
they add to rather than replace your global entries. Downloaded plugin content always lives in
your per-user store (~/.posit/assistant/plugins/) regardless of which config declared it.
plugins.hostTokens is global-only and is never read from a project config, so a repository can
never supply git credentials.
Administrators can enforce a marketplace allowlist and denylist, a component ceiling, managed
marketplaces, and non-overridable plugin enablement on every platform, by delivering these keys
through POSIT_ASSISTANT_SETTINGS_ENFORCED, the only channel
for the plugin lockdown. If you have also written a lockdown in your own settings.json, the two
combine rather than replace, and neither can loosen the other. See
Plugins.
Runtime Settings
Control how Posit Assistant connects to R and Python.
| Key | Description | Type | Default |
|---|---|---|---|
runtime. | Enable R runtime integration. | boolean | true |
runtime. | Path to the Rscript executable. | string | "Rscript" |
runtime. | Timeout in milliseconds for R code execution. | number | 30000 |
runtime. | Enable Python runtime integration. | boolean | true |
runtime. | Path to the Python executable. | string | "python3" |
runtime. | Timeout in milliseconds for Python code execution. | number | 30000 |
Workspace Settings
| Key | Description | Type | Default |
|---|---|---|---|
workspace. | Working directory. Defaults to the current directory. | string | "" |
workspace. | Allowed root directories for workspace switching. Defaults to the user home directory. | string[] | — |
Sandbox
Control sandbox mode for shell tool execution. On macOS and Linux, bash commands run inside an OS-level sandbox (macOS Seatbelt / Linux bubblewrap) that restricts writes to the workspace and temp directories, blocks network access, and prevents reading sensitive paths like ~/.ssh and ~/.aws. On Windows, the same setting enables gated mode for the active shell: commands are checked against a built-in allowlist before they run. This is not an OS-level sandbox.
| Key | Description | Type | Default |
|---|---|---|---|
sandbox. | Enable sandboxing for shell tool execution. | boolean | false |
sandbox. | Which sandbox implementation to use when sandboxing is on. Project settings override global settings. | "legacy" | "cobox" | "legacy" |
sandbox. | Controls access to protected home credentials such as `~/.ssh` and `~/.aws`, and `.env`, `.Renviron` and `.aws` at writable directory roots, including the workspace and scratch directory. `"readOnly"` allows reads and blocks writes. `"deny"` blocks both and scans for existing secret files below those roots. Existing `.env` directories are exempt. Applies only to `cobox`. Legacy macOS and Linux block secret reads regardless of this setting. Project settings cannot set it. | "readOnly" | "deny" | "readOnly" |
sandbox.secretPaths applies only to sandboxed shell commands. The file-reading tool refuses .env and .Renviron files regardless of this setting. Administrators can require "deny" through POSIT_ASSISTANT_SETTINGS_ENFORCED, for example on a server shared by several users.
You can also toggle sandbox mode during a session with the /sandbox command.
sandbox.backend only selects the implementation. It never turns sandboxing on or off; sandbox.enabled and /sandbox do that.
cobox is a preview sandbox implementation, not a packaged feature. It runs on macOS only, and it
requires an explicit executable: set the PA_COBOX_EXECUTABLE environment variable to the absolute
path of an mcp-console executable, cobox’s current front end (for example
<bundle>/bin/mcp-console, not the mcp-console-sandbox runner beside it), before launching
Posit Assistant. The variable is read only from the launch environment, never
from .env files or settings. The desktop app ignores it, and so does the terminal app when run
directly from source with Bun. With sandboxing enabled and cobox selected but no usable cobox
executable, shell commands are refused rather than run without sandboxing. This includes Linux
and Windows, where cobox is never available. The shield icon’s tooltip explains why the
sandbox is unavailable. Turn sandboxing off, or switch back to legacy, to run them. Because of this, avoid setting sandbox.backend in
a project settings file that collaborators on other platforms share.
Tips
Control the helpful tips that appear above the input area. A tip always appears on startup; after each assistant turn, a tip appears with a small probability.
| Key | Description | Type | Default |
|---|---|---|---|
features. | Show tips above the input after assistant turns and on startup. | boolean | true |
In Positron, this setting is also available as assistant.showTips in the Settings UI.
See Positron Settings for how
values from both sources are merged.
Search
Control how the assistant searches file contents. When this setting is on, the grep tool uses ripgrep (rg) or the system grep if it finds one, and its built-in scanner otherwise. In Positron, it also replaces the older search tool with grep in local workspaces, backed by Positron’s bundled ripgrep. Changes take effect in new sessions: restart the TUI, or reload the window in Positron. This setting is temporary and will be removed once the new search is the only option.
| Key | Description | Type | Default |
|---|---|---|---|
features. | Let grep use ripgrep or system grep when available. In Positron, use grep instead of the search tool. | boolean | true |
In Positron, this setting is also available as assistant.fastSearch in the Settings UI.
Chat input
Control which key combination sends a message from the chat input.
| Key | Description | Type | Default |
|---|---|---|---|
features. | "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. | string | "enter" |
In Positron, this setting is also available as assistant.submitKey in the Settings UI.
See Positron Settings for how
values from both sources are merged.
Compaction
Control how Posit Assistant manages long conversations. See Context Management for details on how compaction works.
These settings go in the features block of your config file:
{
"features": {
"autoCompactTokenBuffer": 30000
}
}
| Key | Description | Type | Default |
|---|---|---|---|
features. | Tokens reserved for the compaction summary. Auto-compaction triggers once fewer than this many tokens remain in the context window. | number | 30000 |
Micro-compaction is controlled by the /microcompact command, not configuration. It runs only when you invoke it.
In Positron, compaction settings are read from the config file’s features block.
assistant.autoCompactTokenBuffer can also be set via Positron’s settings.json, though
it is not exposed in the Settings UI. See
Positron Settings for how values
from both sources are merged.
Cache Keepalive
Keep a supported model’s prompt cache warm while you read a response and step away. When enabled, Posit Assistant sends lightweight background “pings” after each turn so a follow-up message can reuse the cached conversation prefix. Cache lifetime and ping cadence depend on the selected model.
This is on by default. To turn it off or bound how long pings may be sent, set the features block in your settings file:
{
"features": {
"cacheKeepalive": false,
"cacheKeepaliveMinutes": 30
}
}
| Key | Description | Type | Default |
|---|---|---|---|
features. | Enable cache-keepalive pings after a turn completes for models with a supported cache policy. | boolean | true |
features. | Maximum wall-clock window after the last real model request during which automatic pings may be sent (0–60 minutes). This is a send deadline, not the cache-expiration time. | number | 30 |
Claude and supported GPT-5.6 routes use different cache lifetimes and ping cadences. A successful
final ping can keep the cache warm beyond the configured ping-send window. Changes to
cacheKeepalive and cacheKeepaliveMinutes take effect on your next turn — no restart needed.
In Positron, these settings are also available as assistant.cacheKeepalive
and assistant.cacheKeepaliveMinutes in Positron’s Settings UI.
When set in both places, Positron merges them — see
Positron Settings for priority order.
Global Settings
The following settings can only be set in the global ~/.posit/assistant/settings.json. They are not supported in project-level config files.
Conversation Navigation
Standalone, Desktop, RStudio, and the Positron sidebar can show conversation tabs across the top or in
a left-side rail. In Positron, Assistant editor panels ignore this setting and open each conversation
in its own editor tab. The preference defaults to top:
{
"features": {
"conversationTabs": "top"
}
}
| Key | Description | Type | Default |
|---|---|---|---|
features. | Choose no tab chrome, a horizontal top strip, or a vertical side rail on supported platforms. | "off" | "top" | "side" | "top" |
Changes apply live to running sessions — no reconnect or restart needed — and stay the same when you switch workspaces. Platforms without tab chrome keep their supported single-view presentation. The open-view limit is an internal safety policy, not a configurable setting. Turning tabs off does not stop background work or remove conversations from history.
Conversation History Order
Choose how the conversation history list is ordered. The sort control under the history search box writes this setting, and the same order is used by the history dropdown, the standalone sidebar, and the terminal interface’s conversation picker (press s there to switch).
| Key | Description | Type | Default |
|---|---|---|---|
ui. | "created" orders conversations by when they were started. "lastActivity" orders them by their most recent message. | "created" | "lastActivity" | "lastActivity" |
ui. | Overrides the reduced-motion preference of the chat interface, like VS Code's `workbench.reduceMotion`. "auto" follows your operating system setting. "on" always reduces motion. "off" always animates. In Positron, when this is unset, your `workbench.reduceMotion` user setting applies. | "auto" | "on" | "off" | "auto" |
Auto Mode Classifier Model
Choose which model auto mode’s safety classifier uses. Each
entry is a case-insensitive substring matched against tool-capable model IDs on your current
provider, using the same matching rules as modelTiers: the first entry with a
match wins, and an exact model ID beats a substring.
{
"classifierModels": ["haiku", "terra"]
}
When no entry matches, Posit Assistant uses its built-in choice, which prefers a fast model that
has been tested against its classifier evaluations. A model you choose here hasn’t necessarily been
tested that way, and a weaker model may allow tool calls it should block. The classifier never
switches providers. Edits to settings.json take effect on the next classified tool call.
This setting is global-only. Administrators can set or lock it with administrator-managed settings.
| Key | Description | Type | Default |
|---|---|---|---|
classifierModels | Ordered model-ID substrings preferred for auto mode's safety classifier. The first substring with a tool-capable match on the current provider wins; with no match, the built-in choice applies. | string[] | [] |
Color scheme
Choose light mode, dark mode, or the system preference. In Desktop and Standalone servers that allow shell commands, use Appearance… in the … menu. In Connect and other Standalone servers, use the Light/Dark mode submenu. In the TUI, use /theme. These controls write only their own app’s entry under platforms, so changing one app does not change the others. The following example sets a shared system preference, with separate choices for Desktop and the TUI.
{
"ui": { "colorScheme": "system" },
"platforms": {
"desktop": { "ui": { "colorScheme": "dark" } },
"tui": { "ui": { "colorScheme": "light" } }
}
}
An app’s platforms entry overrides the plain ui.colorScheme for that app. With neither set, Standalone, Desktop, and Connect follow the system, and the TUI uses dark. "system" follows the operating system or browser preference, or the terminal’s light or dark mode in the TUI. Positron and RStudio follow the editor’s theme and do not use this setting.
| Key | Description | Type | Default |
|---|---|---|---|
ui. | The color scheme for every app that uses it, unless the app's platforms entry sets its own. null uses the app's default. | "light" | "dark" | "system" | null | null |
platforms. | One app's color scheme. <app> is "standalone", "desktop", "connect", or "tui". | "light" | "dark" | "system" | null | null |
The older TUI ui.theme key is no longer read. Posit Assistant moves it to platforms.tui.ui.colorScheme at startup, unless ui.colorScheme is already set for the TUI.
Color theme
Use ui.colorTheme to choose separate light and dark themes for Desktop and Standalone. A mode without a theme uses the built-in colors. ui.colorScheme decides which mode is shown.
{
"ui": {
"colorTheme": {
"light": "positron:Default Positron Light",
"dark": "~/themes/my-theme.json"
}
}
}
Each mode accepts one of these values.
positron:<theme>, a color theme installed in Positron, named by its ID or its label as shown in Positron’s theme picker. It supplies the interface and code colors. Posit Assistant looks in Positron’s extensions folder (~/.positron/extensions) and, on macOS, in the Positron app.- A path to a VS Code color theme
.jsonfile. It supplies the interface colors (colors) and code colors (tokenColors). It may also carry acssfield with stylesheet text, applied after its colors (see below). - A path to a
.cssfile, which styles the interface over the built-in colors and keeps the built-in code colors.
Paths must be absolute or start with ~. A theme that cannot be found or read leaves that mode on the built-in colors and shows a warning. A theme meant for the other mode still applies, with a warning.
| Key | Description | Type | Default |
|---|---|---|---|
ui. | Theme for light mode: "positron:<theme ID or label>", or a path to a .json theme or a .css file. | string | unset |
ui. | Theme for dark mode, in the same forms. | string | unset |
To choose a theme, open Appearance… in the … menu. The dialog offers Light, Dark or System mode and a searchable theme list for each mode. Choose Bundled colors, a theme installed in Positron, or a Positron built-in theme. Theme entries show color previews when available. Choices apply immediately and are saved to the global settings file.
A file path set in settings appears as “Custom file”. The dialog can replace it but cannot choose a file. Administrator-enforced settings are read-only in the dialog.
ui.colorTheme is read from the global settings file only. Changes, including edits by hand and edits to the selected files, apply when the window regains focus or reloads, without a restart. If a file cannot be read at that point, for example in the middle of a save, the previous version stays in use when the selection is unchanged. A changed selection whose file cannot be read uses the bundled colors.
Positron and RStudio follow the editor’s theme, and the TUI and Connect ignore this setting. Standalone ignores it when its deployment disables shell commands, because reading a file a user names would otherwise give them access to it. When Connect or such a Standalone deployment ignores the setting, startup shows a warning.
A .css theme, or a css field in a JSON theme, is inserted into the page as written and applies
only in its mode. It can set Posit Assistant’s --ui-* color variables (for example
html.dark { --ui-primary: #7de486; }) and target elements by class, data-testid, or the
data-slot attributes on the chat composer (chat-composer) and tool confirmation cards
(tool-confirmation). These are not stable styling interfaces. They can change in any
release, so a stylesheet may need updating after an upgrade. Each mode’s CSS is limited to
256 KB. Larger CSS is ignored with a warning. Theme CSS comes after Posit Assistant’s own styles,
so a rule with the same specificity wins, except over styles loaded later, such as those of
components that load on demand.
Provider Settings
Provider connection details use a separate global file, ~/.posit/ai/providers.json, not the
~/.posit/assistant/settings.json documented above. That file has its own reference page covering
every key, including model discovery and filtering, per-protocol endpoints, the provider-specific
sections, and custom providers.
See providers.json for the full reference, and Providers for the list of supported providers and setup instructions.
Web Search
Bedrock Mantle models that support hosted web search (see Providers) restrict retrieval to AWS’s own web index and cache by default. This setting additionally allows a cache miss to fetch the live external page:
{
"webSearch": {
"bedrock": {
"externalWebAccess": true
}
}
}
| Key | Description | Type | Default |
|---|---|---|---|
webSearch. | Allow Bedrock Mantle hosted web search to fetch live external pages on a cache miss. Global-only; requires the bedrock-websearch:ExternalWebAccess IAM action when enabled. | boolean | false |
The same preference is available as the Allow live external website access for Bedrock checkbox
in the session HUD’s preferences on the browser and webview surfaces (Positron, Standalone,
Desktop, Connect, and RStudio). The checkbox appears only while a Bedrock model that supports web
search is available. The TUI and headless surfaces honor the configured value but expose
no control for it. When an administrator enforces the value through
POSIT_ASSISTANT_SETTINGS_ENFORCED, the checkbox renders disabled with a managed-setting note.
Every saved checkbox value — including an explicit false — is a sticky override written to the
global settings file, and there is no reset-to-default button. To resume following the
administrator or built-in default, delete the webSearch key from
~/.posit/assistant/settings.json.
Storage Settings
| Key | Description | Type | Default |
|---|---|---|---|
storage. | Directory for conversation storage. | string | "~/.posit/assistant" |
Logging
| Key | Description | Type | Default |
|---|---|---|---|
logging. | Log level. Options: "error", "warn", "info", "debug", "trace". | string | "info" |
logging. | Log file path. Defaults to ~/.posit/assistant/logs/{platform}.log. | string | "" |
logging. | Output logs to the console. | boolean | true |
Command Environment
Processes started by Posit Assistant can inherit variables from its environment, including credentials such as GITHUB_TOKEN or AWS_SECRET_ACCESS_KEY. Two settings in your global settings file control what they receive: env.filter withholds inherited values, while env.set supplies values explicitly. Neither setting changes Posit Assistant’s own environment.
| Process | env.filter | env.set |
|---|---|---|
| Shell commands (Bash and PowerShell) | Yes | Yes |
| Hooks | Yes | Yes |
| Local (stdio) MCP servers configured in settings | Yes | Yes |
| Local MCP servers from plugins | Yes, with additional restrictions on inheritance | No; use the server’s own env entries |
| Native R and Python processes started by Posit Assistant to run code | Yes | Yes |
Sessions started by the IDE are unchanged. RStudio’s R session and Positron’s R and Python consoles do not receive these settings because Posit Assistant does not start them.
Helpers and searches use separate environments. Posit Assistant’s internal helper commands use the host’s configuration, with Posit Assistant’s control variables removed. An apiKeyHelper does the same, with PA_PROVIDER added. This keeps authentication credentials such as VAULT_TOKEN, proxy settings, and certificate settings available even when you withhold them from other commands. File-content searches receive only LANG, LC_ALL, and LC_CTYPE, plus SystemRoot on Windows. None of these processes uses env.filter or env.set, so invalid environment settings do not disable them.
Filtering is not a ban on a variable name. It removes inherited values only, not explicit env.set assignments or credentials supplied by Posit Assistant for a configured connection. For example, this filter withholds inherited AWS variables except the region, names ending in _TOKEN, and OPENAI_API_KEY:
{
"env": {
"filter": ["-AWS_*", "+AWS_REGION", "-*_TOKEN", "-OPENAI_API_KEY"]
}
}
| Key | Description | Type | Default |
|---|---|---|---|
env. | Rules that filter inherited environment variables. Use -PATTERN to block names and +PATTERN to allow them. The last matching rule wins. Variables that match no rule are inherited. | string[] | [] |
Writing rules. Start each rule with - to block matching variable names or + to allow them.
Rules are applied in order, and the last matching rule wins. For example,
["-AWS_*", "+AWS_REGION"] blocks AWS variables except AWS_REGION. Variables that match no rule
are inherited.
To allow only selected variables, start with -*, then add + rules for the names you need.
Posit Assistant keeps a built-in list of essential variables, including PATH and HOME, that
always pass the filter. This example allows those essential variables plus Conda, R library and
HTTPS proxy settings:
{
"env": {
"filter": ["-*", "+CONDA_*", "+R_LIBS*", "+HTTPS_PROXY"]
}
}
Matching names. Each pattern is a variable name or a glob. * matches any number of characters and ?
matches exactly one. Patterns match the whole name, so *_TOKEN matches GITHUB_TOKEN but not
GITHUB_TOKEN_FILE. Matching ignores case on every platform. Invalid rules include a missing
prefix (AWS_*), a bare prefix (-), surrounding pattern whitespace, or $ or = in the pattern
(such as -$AWS_KEY or -NAME=value).
Posit Assistant warns when a later rule makes an earlier one redundant, such as a repeated pattern
with either sign or a later pattern made entirely of *. For example, ["-GITHUB_TOKEN", "+*"]
allows everything because the final +* cancels the restriction. Put +* first to keep the
-GITHUB_TOKEN restriction. These warnings check each settings source separately, so they do not
warn when your rules override administrator defaults. They also do not detect every overlap between
patterns. A warning does not make the filter invalid.
Built-in protections and essential variables. Whatever your filter rules say:
- Posit Assistant’s built-in list of essential variables always passes the filter. No
-rule removes these variables:PATH,HOME,USER,LOGNAME,SHELL,LANG,LC_*,TERM,TMPDIR,TMP, andTEMP. On Windows, alsoSystemRoot,windir,USERPROFILE,APPDATA,LOCALAPPDATA,PATHEXT,COMSPEC,PSModulePath,ProgramFiles,ProgramFiles(x86),ProgramW6432,CommonProgramFiles,ProgramData,SystemDrive,HOMEDRIVE,HOMEPATH,USERNAME,USERDOMAIN,COMPUTERNAME,NUMBER_OF_PROCESSORS,PROCESSOR_ARCHITECTURE, andOS. - Posit Assistant’s own control variables are always withheld, and
+rules cannot bring them back: names starting withPA_,POSIT_ASSISTANT_,POSIT_AI_PROVIDERS_, orDATABOT_, andRSTUDIO_CHAT_AUTH_TOKEN. They configure or authenticate Posit Assistant itself, including administrator settings. - The Posit Workbench session cookie
RS_SESSION_RPC_COOKIEis never inherited, even with a+rule. A process with this cookie could request Posit Connect credentials on your behalf. In RStudio on Workbench, Posit Assistant also removes the cookie from its own environment at startup, so that other processes started from Posit Assistant, such as those started by its libraries, don’t inherit it either. RStudio’s R console is unchanged. - Posit Assistant sets
NO_COLOR=1andPOSIT_ASSISTANT=1for the processes listed above. For shell commands with a conversation scratch directory, it also pointsPA_SCRATCH_DIR,TMPDIR,TMP, andTEMPat that directory. Filter rules do not remove these additions.
Limits. Filtering controls only the environment inherited by a process. Commands can still set
variables themselves, load them from shell startup files, or read secrets from files such as .env
or ~/.aws/credentials when file access is allowed. Use
sandbox restrictions to limit that access. The sandbox
blocks access to some credential files, including those under ~/.aws, but does not remove inherited
variables. Use filter rules to withhold those variables, whether the sandbox is on or off.
Your settings and administrator settings. Set env.filter in your global settings file, not
in project settings: Posit Assistant ignores a project’s env key. Administrators can also configure
it through administrator-managed settings.
An administrator’s default filter in POSIT_ASSISTANT_SETTINGS_DEFAULT is a starting point that
you can add to or replace. Default rules apply first, followed by the server operator’s rules on a
multi-user server, then your global rules. For example, you can:
- Add
-GITHUB_TOKENto block another variable without changing the other defaults. - Add
+AWS_REGIONto allow the region after a default-AWS_*rule. - Start with
+*to clear the default restrictions, then add your own rules.
An enforced filter in POSIT_ASSISTANT_SETTINGS_ENFORCED sets restrictions you cannot override.
Your + rules cannot allow a variable it blocks, though you can block additional variables.
Posit Assistant’s essential variables still pass the filter.
Setting env.filter to [] leaves default and enforced filters unchanged. The built-in protections
still apply.
When edits apply. Settings are read before each new process starts. Shell commands, hooks, and native Python execution pick up changes on their next run. Already-running R sessions and MCP servers keep their environment until restarted; editing the settings does not restart them.
Invalid filters stop new commands and servers. If a filter is invalid in any settings source, or a global settings file is unreadable or invalid, Posit Assistant refuses to start shell commands, new native R/Python processes for code execution, and local MCP servers until the problem is fixed. The error names the setting and where it came from. Existing processes keep running with their original environment.
Hooks are an exception: Posit Assistant logs a warning and still attempts to run them with only essential inherited variables, Posit Assistant’s own variables, and PA_PROJECT_DIR, without env.set. Interpreter availability checks also use this reduced environment, so Posit Assistant can still check whether R or Python works. Neither fallback restores full inheritance.
Setting variables for commands
Use env.set in your global settings to supply values to shell commands, hooks, local MCP servers configured in settings, and native R/Python processes started by Posit Assistant. Plugin MCP servers do not receive these assignments. The setting maps variable names to strings, for example a development database URL:
{
"env": {
"set": { "DATABASE_URL": "postgres://localhost/dev" },
"filter": ["-AWS_*", "-*_TOKEN"]
}
}
| Key | Description | Type | Default |
|---|---|---|---|
env. | Assign string values to environment variables for shell commands, hooks, local MCP servers configured in settings, and native R/Python processes. Plugin MCP servers do not receive these assignments. Use {env:NAME} to insert an environment variable's value. $VAR is not expanded. | object | {} |
Don’t store secrets as literals in settings. The file is plain text, and a command that prints
a value puts it in the conversation. Use permitted inheritance, {env:NAME} references or a
credential helper for command credentials, and provider settings for model API keys. A reference
keeps the secret out of settings, not out of the receiving process.
Using environment references. Use {env:NAME} to insert an environment variable’s value when a
process starts. For example, "PATH": "/opt/tools/bin:{env:PATH}" adds a directory to the existing
PATH. Posit Assistant does not expand shell syntax such as $VAR.
References read the environment Posit Assistant was launched with. env.filter controls which
variables processes inherit, not what you deliver explicitly, so a reference can read a variable
your own filter withholds. This lets an administrator block general inheritance with
"filter": ["-*"] while explicitly supplying "set": { "GITHUB_TOKEN": "{env:TEAM_GITHUB_TOKEN}" }.
References in your settings and a multi-user server operator’s settings can’t read variables
withheld by an enforced administrator filter (POSIT_ASSISTANT_SETTINGS_ENFORCED). If you replace
an administrator’s assignment in your settings, your replacement follows that rule too.
References do not read other env.set entries or values Posit Assistant adds later. No settings
source can reference Posit Assistant’s control variables or RS_SESSION_RPC_COOKIE. Variables
removed from its environment at startup, such as provider credentials on a multi-user server, are
also unavailable. To share such a value, the server operator must export it under a second name
and reference that name.
An unset or blocked variable prevents processes that need the assignment from starting, with the exceptions described below. The error names the entry and variable, never its value. Only the assignment selected for each name is expanded, so an unresolved reference in an overridden assignment does not block a launch.
Filtering and assignment order. Assignments are applied after filtering and replace inherited values with the same name. Even an enforced administrator filter cannot remove an assignment. Credentials supplied by Posit Assistant for configured connections come next and override assignments with the same name. Posit Assistant then sets NO_COLOR, POSIT_ASSISTANT and, for shell commands with a scratch directory, PA_SCRATCH_DIR, TMPDIR, TMP and TEMP. Assignments cannot override these additions. Color-forcing variables such as FORCE_COLOR are also removed after assignments.
A local MCP server’s own env entries are applied last and override env.set. Plugin MCP servers receive explicit values through their own env entries instead of receiving all env.set assignments. An approved {env:NAME} reference in a server’s configuration can read a resolved env.set value. See MCP Servers for details. The older name environment is still accepted as an alias for a server’s env setting.
Settings precedence. Assignments combine per variable name, in increasing priority:
administrator defaults, operator settings, your settings, then enforced administrator entries.
Each source replaces values for the names it sets, leaving other names alone. To control a
variable’s starting value, an administrator enforces an env.set entry rather than a filter rule.
Users cannot replace that entry in settings, but a command can still override it. There is no
setting that guarantees a variable remains absent; the closest option is an enforced empty string,
which is not the same as an absent variable.
Case sensitivity. On macOS and Linux, HTTP_PROXY and http_proxy are separate variables.
Setting or enforcing one does not affect the other. Set both if your tools need both; curl reads
only the lowercase http_proxy. On Windows, names are case-insensitive, and the higher-priority
source supplies both spelling and value. Two spellings of one name within a source are invalid on
Windows. Filter patterns, unlike assignment names, ignore case everywhere.
Configuring Posit Assistant itself. env.set only configures the processes listed above. Use provider settings for model API keys, ~/.posit/ai/providers.json for provider base URLs, and runtime.python.path or runtime.r.path for interpreter paths. Project settings cannot supply assignments.
Valid names and values. Names must be non-empty, have no surrounding whitespace, and contain none of $, =, *, ? or NUL. Posit Assistant’s control names are reserved: names starting with PA_, POSIT_ASSISTANT_, POSIT_AI_PROVIDERS_ or DATABOT_, and RSTUDIO_CHAT_AUTH_TOKEN. Values must be strings without NUL. References to control variables or RS_SESSION_RPC_COOKIE are invalid.
Invalid assignments stop new commands and servers. An invalid entry in any settings source blocks new shell commands, new native R/Python processes for code execution, and local MCP servers configured in settings until it is fixed, even if another source overrides that name. Silently dropping a bad entry could make a process use an inherited value or its own default instead of the intended value.
Unlike control-variable names, RS_SESSION_RPC_COOKIE is allowed as an assignment name in
env.set. It does not make the Workbench cookie available for reference expansion or inheritance.
Errors identify the setting, source and entry, never the value. If someone pastes NAME=value
as a key, the value part is elided in diagnostics. Invalid administrator assignments also produce
startup errors.
Hooks and interpreter availability checks use the reduced environment described above, without env.set. An assignment error affects a plugin MCP server only if an approved reference in its configuration reads the affected name.
Unknown keys directly under env do not block commands. Uppercase keys that look like variable
names, such as HTTP_PROXY, produce notices in command output when found in settings files. The
notice is visible to both you and the model and suggests moving the key under env.set. In
administrator payloads, these keys produce startup errors. Other unknown keys are only logged,
so hosts running older versions can share settings with newer hosts without adding notices or
errors.
Example Configuration
{
"defaultModel": {
"provider": "positai",
"id": "claude-sonnet-4-6"
},
"permission": {
"read": "allow",
"bash": {
"git *": "allow"
},
"task": {
"explore": "deny",
"general": "ask"
}
},
"skills": {
"paths": [
"~/.agents/skills",
"~/.posit/assistant/skills",
".agents/skills",
".posit/assistant/skills",
"~/my-company/shared-skills"
]
}
}
Some configuration changes require restarting the assistant or opening a new conversation to take effect.
Developer 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 go in the features block of your config file and can be set at either global or project level. For example:
{
"features": {
"experimentalFeatures": true,
"cacheKeepaliveWidget": true
}
}
| Key | Description | Type | Default |
|---|---|---|---|
features. | Enable experimental in-development features. Gates access to new capabilities that are still being refined. Also enables everything in features.previewFeatures. | boolean | false |
features. | Enable preview Assistant features, which may still change before general availability. | boolean | false |
features. | Enable developer debugging surfaces such as raw tool data display, conversation path copying, and dev-only commands. | boolean | false |
features. | Show the persona selector in the status bar, allowing you to switch between additional assistant personas. | boolean | false |
features. | Show a status-bar widget that displays cache warmth, 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 |
These settings also exist as Positron VS Code settings (assistant.experimentalFeatures,
assistant.devMode, assistant.enablePersonaSelector, and assistant.cacheKeepaliveWidget).
They are not exposed in the Settings UI — edit settings.json directly. The exception is
assistant.previewFeatures, which is declared in the Positron extension and appears in the
Settings UI with a Preview badge. When set in both places,
Positron merges them; see Positron Settings
for priority order.
Administrator-Managed Settings
In a managed deployment — Posit Workbench, Posit Connect, or any launcher that controls the session’s environment — an administrator can supply settings through two environment variables. These work on every platform: Positron, RStudio, Standalone, Desktop, and the terminal.
These controls are best-effort administrative policy, not a security boundary. A user who controls their own environment (or holds a valid API key) can reach a provider or an MCP server directly, whatever these variables say. The tamper-resistance of the delivery path — getting the environment into a session the user can’t edit — is the managed launcher’s job (for example Posit Workbench’s managed session environment), not Posit Assistant’s.
| Key | Description | Type | Default |
|---|---|---|---|
POSIT_ASSISTANT_SETTINGS_ENFORCED | A sealed top layer. It beats the global and project settings files, other environment variables, and CLI flags. Users cannot override it. | JSON | — |
POSIT_ASSISTANT_SETTINGS_DEFAULT | A bottom layer, just above the built-in defaults. It changes what Posit Assistant does out of the box; any value a user sets overrides it. | JSON | — |
Both variables carry a JSON object written in the same vocabulary as settings.json — there is no
separate policy format. Only the keys the object actually contains are affected; omitting a key leaves
it entirely to the layers below.
export POSIT_ASSISTANT_SETTINGS_ENFORCED='{
"approvalMode": "normal",
"permission": { "bash": { "curl *": "deny" } },
"plugins": {
"strictKnownMarketplaces": [{ "source": "github", "github": "acme/plugins" }]
}
}'
Resolution Order
With both variables set, settings resolve in this order (last wins):
- Built-in defaults
POSIT_ASSISTANT_SETTINGS_DEFAULT- Global
~/.posit/assistant/settings.json - Project
.posit/assistant/settings.json - Environment variables
- CLI flags
POSIT_ASSISTANT_SETTINGS_ENFORCED
Objects merge key by key, so an enforced "features": { "showTips": false } pins just that one
setting and leaves the rest of the features block to the layers below. Arrays and plain values
replace whatever is below them.
In Positron these two layers bracket Positron’s own settings rather than sitting above and below a single file. See Positron Settings.
Format Rules
- Strict JSON — no comments and no trailing commas, unlike the settings file itself.
- Read once, at startup. Changing either variable requires restarting the session.
- These keys are rejected, with an error naming the key:
serverandworkspace.path(owned by whatever launches the session),hooks(the hook event map is not supported through this channel — theuseHookstoggle is), and the legacyproviderskey. Everything else in the settings vocabulary is accepted, includingpermission,approvalMode,mcpServers,mcp,useHooks,env,skills,sandbox,storage,logging,workspace.allowedRoots, thefeaturesblock, and the plugin keys. - Problems are reported once at startup. An invalid value drops just that key; an unparseable payload, or one containing an unsafe object key, is ignored entirely. Both show an error message naming the environment variable. A key this version doesn’t recognize is only logged, so a payload written for a newer release doesn’t raise an error for users on an older one.
- Shell commands are the exception. Because a rejected payload might have carried an
env.filterorenv.set, an ignored payload disables shell commands until it is fixed, even if it has noenvkey. The same applies when theenvvalue, its filter or anenv.setentry is invalid. - Provider connection settings are not part of this payload: they live in
~/.posit/ai/providers.json(see Provider Settings) and have their own pair of administrator variables,POSIT_AI_PROVIDERS_ENFORCEDandPOSIT_AI_PROVIDERS_DEFAULT, which work the same way for that file.
Keys With Extra Meaning
Most keys simply win or lose by layer. Some behave in ways worth knowing:
-
defaultModel— fixes the model for every new conversation, whether the administrator supplies it as an enforced or a default setting, because a user’s own model choices are not saved there. A defaultdefaultModeltherefore behaves like a fixed choice the user can replace only by setting their owndefaultModel. Earlier versions called this keypreferredModel, and global files (including operator and per-user files on multi-user servers) now ignore that name; on a server with named users, an operator file containing it logs a one-time hint to rename it. For one release, an administrator payload that haspreferredModelbut nodefaultModelis read asdefaultModel, with adeprecated-keywarning; the same alias applies to project files. If both keys are present,defaultModelwins silently. During a mixed-version rollout, put both keys in the payload: versions 1.2.0–1.8.0 applypreferredModel(and only logdefaultModelas unrecognized), and 1.9.0 appliesdefaultModel:{ "defaultModel": { "provider": "positai", "id": "claude-sonnet-4-6" }, "preferredModel": { "provider": "positai", "id": "claude-sonnet-4-6" } } -
approvalMode— an enforced value is a maximum, not a fixed setting, orderedrestricted→normal→auto→yolo. Users can still choose a stricter mode, capped modes are disabled in the mode picker, and/auto//yoloare hidden above the cap. A user’s saved preference is never overwritten — raising the cap later restores it. A defaultapprovalModeonly sets the starting mode for someone who has never chosen one. -
permission— see Permissions & Trust for what enforceddenyandaskrules mean in practice. -
mcpServers— merged by server name, so an enforced entry pins one server (including"enabled": falseas a non-removable off switch) and leaves the rest configurable. Administrator-supplied servers start in every workspace, including untrusted ones, because they come from the launch environment rather than from project files. Pinning named servers cannot stop a user adding a new name — for that, usemcpbelow. -
mcp— the MCP admission policy (accessplusallow/denymatchers; see MCP Servers). Unlike ordinary keys it never merges across layers:denylists union,allowlists intersect, andaccessnarrows — an enforced value is a ceiling that can only restrict. A malformedmcpvalue in an administrator payload fails closed (the layer reads as"access": "none") with an error, instead of silently dropping the restriction. -
useHooks— which lifecycle hooks may run:"all","global"(global hooks only, never project hooks, on any workspace), or"none".true/falsework as aliases for"all"/"none". Same ceiling/narrowing semantics asmcp, and the same fail-closed behavior on a malformed value. See Hooks. -
env.filter: controls inheritance for shell commands, hooks, local MCP servers, and native R/Python processes started by Posit Assistant. Users can extend or replace a default filter. An enforced filter can only be narrowed: user rules cannot readmit variables it withholds. Essential variables, includingPATHandHOME, always pass. Invalid filters stop new commands and servers; hooks and interpreter availability checks instead attempt to run with a reduced environment. See command environment for scope, rules, and failure behavior. -
env.set: supplies values per variable name to the same processes, except plugin MCP servers. Users can replace defaults and add names, but cannot replace enforced assignments in settings. These are starting values, not a guarantee that a process cannot change them; credentials and server-specific values can also override them. Names are case-sensitive on macOS and Linux and case-insensitive on Windows, so enforce bothHTTP_PROXYandhttp_proxyif both need fixed starting values on macOS or Linux. Invalid administrator assignments produce startup errors and stop new commands and servers that receiveenv.set; hooks and interpreter availability checks use a reduced environment. An assignment error affects a plugin MCP server only if an approved reference reads the affected name. Uppercase variable-like keys placed directly underenvproduce startup errors explaining that they belong underenv.set, but do not block commands. Other unknown keys are only logged. Administrator{env:NAME}references can read variables anyenv.filterwithholds, allowing administrators to supply selected values even under a strict filter. Other settings’ references can’t read variables an enforced filter withholds. See setting variables for commands. -
Plugin keys — an enforced
enabledPluginsentry cannot be toggled back, and enforcedextraKnownMarketplacesentries appear as managed and cannot be removed.
Writing an enforced key into your own settings.json succeeds as a file edit but has no effect on
what Posit Assistant uses.
Checking What Applies
When a setting doesn’t behave as expected, run /settings-report in the chat. It reads the settings
files, the administrator variables (POSIT_ASSISTANT_SETTINGS_ENFORCED/_DEFAULT and
POSIT_AI_PROVIDERS_ENFORCED/_DEFAULT), CLI flags, and environment variables as they are now, and
shows which layer decided each value. It only reads: it never signs in, runs a helper command, or
changes a file. Its tabs show the layers each file reads, a table per file of the values each layer
sets, and a table of each provider’s credential sources. In Positron it opens in an editor tab with
Refresh, Open, and Copy; you can also run Posit Assistant: Show Settings Report from
the command palette. In RStudio, Standalone, and Desktop it opens in a dialog with Refresh,
Copy, and Save; the terminal app shows it in a modal. Refresh reads the files again,
so you can keep the report open while you edit them. Copy, Save, and Open export the whole
report as Markdown. /diagnostics includes the same report as settings-report.md and
settings-report.json.
Secret values are never shown. Fields that could hold a secret (MCP server commands, environment
variables and headers, hook commands, permission patterns, provider headers, an apiKeyHelper
command) appear as "<masked>" or "<configured>", and URLs lose any embedded credentials or query
string. Only keys that at least one layer sets appear.
In the Markdown export, the settings.json and providers.json sections are annotated JSONC. A legend lists each layer, highest precedence first, with where it is read from and whether it was found, empty, missing, or invalid:
// Layers, highest precedence first:
// enforced admin enforced POSIT_ASSISTANT_SETTINGS_ENFORCED 1 key
// cli CLI flags --model 1 key
// env env vars $PA_MODEL not set
// project project settings.json /work/app/.posit/assistant/settings.json not set
// global global settings.json ~/.posit/assistant/settings.json 2 keys
// default admin default POSIT_ASSISTANT_SETTINGS_DEFAULT not set
{
"approvalMode": "normal", // [global] (lowered to the admin limit)
// [enforced] limit: "normal"
}
Each value ends with a comment naming the layer it came from. Lines beneath it are the lower layers that set the same key. Reading the tags:
| Tag | Layer |
|---|---|
[enforced] | POSIT_ASSISTANT_SETTINGS_ENFORCED (settings) or POSIT_AI_PROVIDERS_ENFORCED (providers) |
[default] | POSIT_ASSISTANT_SETTINGS_DEFAULT or POSIT_AI_PROVIDERS_DEFAULT |
[global], [project] | The global and project settings.json |
[user] | ~/.posit/ai/providers.json |
[--model] | A CLI flag, named after the flag |
[$PA_MODEL] | An environment variable, named after the variable |
Labels in parentheses explain what happened to a value:
(no effect)— shadowed by an enforced value.(dropped)— removed because a higher layer replaced the whole object or list, or because its source is ignored (an invalid file, or a project file in an untrusted workspace).(combined: ...)— the key doesn’t have a single winner. Every layer takes part:hooksfrom every layer are combined, thenuseHooks("none", or"global"for project hooks) can drop groups, and the groups that remain run only for their event and matcher.mcp.denyblocks if any list blocks, andmcp.allowandplugins.allowedComponentsallow only what every list allows.permissionrules show only a count of rules per layer and tool, never the patterns.(applies on restart)— read once at startup, such asruntime.python.path. The value shown is what is configured now, not necessarily what the running session uses.
An invalid file is listed under Issues with what Posit Assistant does about it: for
settings.json, it keeps using the file’s previous contents until it is fixed; for permission and
hook rules, that file’s rules and hooks are not applied; for providers.json, the source is ignored.
The Credentials tab lists, for each provider, the sources Posit Assistant checks in order, and
marks the one that is used (in bold in the Markdown export): a managed source (Posit Workbench or an API key helper), the
stored credential, then environment variables, then connection settings such as an AWS profile. Only
variable names and whether they are set are shown. A managed source decides even when it has no
credential ready; Microsoft Foundry in Entra mode never uses a stored key; a selected Snowflake
connection is authoritative even when it is missing from connections.toml. Positron manages some
providers’ sign-ins itself, so for those the report names the owner and shows “not checked”.
Environment Variables
Some settings can also be controlled via environment variables. Environment variables take precedence over file-based configuration, but not over POSIT_ASSISTANT_SETTINGS_ENFORCED. See Providers for the full list of provider environment variables.