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

📝 Directory change

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
  • Project config overrides global settings for a specific project. Place a .posit/assistant/settings.json file 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"
}
⚠️ Global config only

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. The safety classifier deliberately ignores these preferences.

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.

KeyDescriptionTypeDefault
modelTiers.lowOrdered 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.mediumOrdered 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.highOrdered 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.idA 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.providerThe 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.thinkingEffortA fixed thinking effort level for new conversations. During a conversation, thinking effort is adjusted in the UI and stored per conversation.string—
defaultModel.webSearchA 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:

  1. defaultModel, from any source: administrator settings, a project or global settings.json, Positron’s assistant.defaultModel.* settings, or the --model flag and PA_MODEL variable.
  2. The conversation you are looking at.
  3. The last model a conversation showed in this app, remembered across workspaces.
  4. 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 wrote preferredModel for you

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"
}
KeyDescriptionTypeDefault
permissionPermission 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—
📝 Project vs. global permissions

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 ..."
      }
    }
  }
}
KeyDescriptionTypeDefault
typeServer 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.stringinferred
commandCommand and arguments to start a local MCP server.string[]—
envEnvironment variables for a local MCP server. `environment` is an alias for `env`. A server that sets both is not started.object—
urlURL of a remote MCP server.string—
enabledWhether this server is active.booleantrue
timeoutConnection timeout in milliseconds.number10000
📝 Project vs. global MCP servers

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.

KeyDescriptionTypeDefault
skills.pathsDirectories 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"]
📝 Skill name conflicts

When the same skill name exists in more than one directory, the version from the later directory is used.

📝 Project vs. global skill paths

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
  }
}
KeyDescriptionTypeDefault
extraKnownMarketplacesDeclared 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{}
enabledPluginsPlugin 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.allowedComponentsRestrict 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.hostTokensPer-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.strictKnownMarketplacesMarketplace 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.blockedMarketplacesMarketplace denylist, using the same matcher entries as strictKnownMarketplaces. A match is blocked regardless of the allowlist. Global scope only.array—
📝 Marketplace lists are strict

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.

📝 Project vs. global plugin keys

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.

💡 Enterprise administration

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.

KeyDescriptionTypeDefault
runtime.r.enabledEnable R runtime integration.booleantrue
runtime.r.pathPath to the Rscript executable.string"Rscript"
runtime.r.timeoutTimeout in milliseconds for R code execution.number30000
runtime.python.enabledEnable Python runtime integration.booleantrue
runtime.python.pathPath to the Python executable.string"python3"
runtime.python.timeoutTimeout in milliseconds for Python code execution.number30000

Workspace Settings

KeyDescriptionTypeDefault
workspace.pathWorking directory. Defaults to the current directory.string""
workspace.allowedRootsAllowed 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.

KeyDescriptionTypeDefault
sandbox.enabledEnable sandboxing for shell tool execution.booleanfalse
sandbox.backendWhich sandbox implementation to use when sandboxing is on. Project settings override global settings."legacy" | "cobox""legacy"
sandbox.secretPathsControls 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 an opt-in preview

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.

KeyDescriptionTypeDefault
features.showTipsShow tips above the input after assistant turns and on startup.booleantrue
💡 Positron users

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.

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.

KeyDescriptionTypeDefault
features.fastSearchLet grep use ripgrep or system grep when available. In Positron, use grep instead of the search tool.booleantrue
💡 Positron users

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.

KeyDescriptionTypeDefault
features.submitKey"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"
💡 Positron users

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
  }
}
KeyDescriptionTypeDefault
features.autoCompactTokenBufferTokens reserved for the compaction summary. Auto-compaction triggers once fewer than this many tokens remain in the context window.number30000

Micro-compaction is controlled by the /microcompact command, not configuration. It runs only when you invoke it.

💡 Positron users

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
  }
}
KeyDescriptionTypeDefault
features.cacheKeepaliveEnable cache-keepalive pings after a turn completes for models with a supported cache policy.booleantrue
features.cacheKeepaliveMinutesMaximum 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.number30
📝 Model-dependent timing

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.

💡 Positron users

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"
  }
}
KeyDescriptionTypeDefault
features.conversationTabsChoose no tab chrome, a horizontal top strip, or a vertical side rail on supported platforms."off" | "top" | "side""top"
📝 Live-applied preference

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).

KeyDescriptionTypeDefault
ui.conversationHistorySort"created" orders conversations by when they were started. "lastActivity" orders them by their most recent message."created" | "lastActivity""lastActivity"
ui.reduceMotionOverrides 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"

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.

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
    }
  }
}
KeyDescriptionTypeDefault
webSearch.bedrock.externalWebAccessAllow 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.booleanfalse

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

KeyDescriptionTypeDefault
storage.pathDirectory for conversation storage.string"~/.posit/assistant"

Logging

KeyDescriptionTypeDefault
logging.levelLog level. Options: "error", "warn", "info", "debug", "trace".string"info"
logging.fileLog file path. Defaults to ~/.posit/assistant/logs/{platform}.log.string""
logging.consoleOutput logs to the console.booleantrue

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.

Processenv.filterenv.set
Shell commands (Bash and PowerShell)YesYes
HooksYesYes
Local (stdio) MCP servers configured in settingsYesYes
Local MCP servers from pluginsYes, with additional restrictions on inheritanceNo; use the server’s own env entries
Native R and Python processes started by Posit Assistant to run codeYesYes

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"]
  }
}
KeyDescriptionTypeDefault
env.filterRules 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, and TEMP. On Windows, also SystemRoot, windir, USERPROFILE, APPDATA, LOCALAPPDATA, PATHEXT, COMSPEC, PSModulePath, ProgramFiles, ProgramFiles(x86), ProgramW6432, CommonProgramFiles, ProgramData, SystemDrive, HOMEDRIVE, HOMEPATH, USERNAME, USERDOMAIN, COMPUTERNAME, NUMBER_OF_PROCESSORS, PROCESSOR_ARCHITECTURE, and OS.
  • Posit Assistant’s own control variables are always withheld, and + rules cannot bring them back: names starting with PA_, POSIT_ASSISTANT_, POSIT_AI_PROVIDERS_, or DATABOT_, and RSTUDIO_CHAT_AUTH_TOKEN. They configure or authenticate Posit Assistant itself, including administrator settings.
  • The Posit Workbench session cookie RS_SESSION_RPC_COOKIE is 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=1 and POSIT_ASSISTANT=1 for the processes listed above. For shell commands with a conversation scratch directory, it also points PA_SCRATCH_DIR, TMPDIR, TMP, and TEMP at 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_TOKEN to block another variable without changing the other defaults.
  • Add +AWS_REGION to 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"]
  }
}
KeyDescriptionTypeDefault
env.setAssign 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"
    ]
  }
}
📝 Changes take effect on restart

Some configuration changes require restarting the assistant or opening a new conversation to take effect.

Developer 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 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
  }
}
KeyDescriptionTypeDefault
features.experimentalFeaturesEnable experimental in-development features. Gates access to new capabilities that are still being refined. Also enables everything in features.previewFeatures.booleanfalse
features.previewFeaturesEnable preview Assistant features, which may still change before general availability.booleanfalse
features.devModeEnable developer debugging surfaces such as raw tool data display, conversation path copying, and dev-only commands.booleanfalse
features.enablePersonaSelectorShow the persona selector in the status bar, allowing you to switch between additional assistant personas.booleanfalse
features.cacheKeepaliveWidgetShow 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.booleanfalse
💡 Positron users

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.

📝 Policy, not a security boundary

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.

KeyDescriptionTypeDefault
POSIT_ASSISTANT_SETTINGS_ENFORCEDA 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_DEFAULTA 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):

  1. Built-in defaults
  2. POSIT_ASSISTANT_SETTINGS_DEFAULT
  3. Global ~/.posit/assistant/settings.json
  4. Project .posit/assistant/settings.json
  5. Environment variables
  6. CLI flags
  7. 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.

📝 Positron interleaves differently

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: server and workspace.path (owned by whatever launches the session), hooks (the hook event map is not supported through this channel — the useHooks toggle is), and the legacy providers key. Everything else in the settings vocabulary is accepted, including permission, approvalMode, mcpServers, mcp, useHooks, env, skills, sandbox, storage, logging, workspace.allowedRoots, the features block, 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.filter or env.set, an ignored payload disables shell commands until it is fixed, even if it has no env key. The same applies when the env value, its filter or an env.set entry 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_ENFORCED and POSIT_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 default defaultModel therefore behaves like a fixed choice the user can replace only by setting their own defaultModel. Earlier versions called this key preferredModel, 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 has preferredModel but no defaultModel is read as defaultModel, with a deprecated-key warning; the same alias applies to project files. If both keys are present, defaultModel wins silently. During a mixed-version rollout, put both keys in the payload: versions 1.2.0–1.8.0 apply preferredModel (and only log defaultModel as unrecognized), and 1.9.0 applies defaultModel:

    {
      "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, ordered restricted → normal → auto → yolo. Users can still choose a stricter mode, capped modes are disabled in the mode picker, and /auto / /yolo are hidden above the cap. A user’s saved preference is never overwritten — raising the cap later restores it. A default approvalMode only sets the starting mode for someone who has never chosen one.

  • permission — see Permissions & Trust for what enforced deny and ask rules mean in practice.

  • mcpServers — merged by server name, so an enforced entry pins one server (including "enabled": false as 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, use mcp below.

  • mcp — the MCP admission policy (access plus allow/deny matchers; see MCP Servers). Unlike ordinary keys it never merges across layers: deny lists union, allow lists intersect, and access narrows — an enforced value is a ceiling that can only restrict. A malformed mcp value 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/false work as aliases for "all"/"none". Same ceiling/narrowing semantics as mcp, 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, including PATH and HOME, 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 both HTTP_PROXY and http_proxy if both need fixed starting values on macOS or Linux. Invalid administrator assignments produce startup errors and stop new commands and servers that receive env.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 under env produce startup errors explaining that they belong under env.set, but do not block commands. Other unknown keys are only logged. Administrator {env:NAME} references can read variables any env.filter withholds, 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 enabledPlugins entry cannot be toggled back, and enforced extraKnownMarketplaces entries 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:

TagLayer
[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: hooks from every layer are combined, then useHooks ("none", or "global" for project hooks) can drop groups, and the groups that remain run only for their event and matcher. mcp.deny blocks if any list blocks, and mcp.allow and plugins.allowedComponents allow only what every list allows. permission rules show only a count of rules per layer and tool, never the patterns.
  • (applies on restart) — read once at startup, such as runtime.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.