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

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.

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

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

MCP Servers

Connect external tool servers using the Model Context Protocol.

{
  "mcpServers": {
    "my-server": {
      "type": "local",
      "command": ["node", "server.js"],
      "environment": {
        "API_KEY": "..."
      }
    },
    "remote-server": {
      "type": "remote",
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer ..."
      }
    }
  }
}

Skills

Control where Posit Assistant discovers custom skills.

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

Runtime Settings

Control how Posit Assistant connects to R and Python.

Workspace Settings

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.

You can also toggle sandbox mode during a session with the /sandbox command.

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.

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

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

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

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.

Provider Settings

Provider connection details use a separate global file, ~/.posit/ai/providers.json — they do not go in ~/.posit/assistant/settings.json, the Assistant settings file documented above. In providers.json, configure providers under the providers key. For the full list of supported providers and setup instructions, see Providers.

Credentials are normally set through the application’s settings UI, but you can override the base URL or attach custom HTTP headers in the config file. This is useful for enterprise proxies or custom API gateways that require extra tenancy or routing markers (e.g. Databricks’ x-databricks-use-coding-agent-mode).

{
  "providers": {
    "positai": {
      "baseUrl": "https://my-proxy.example.com",
      "customHeaders": {
        "x-gateway-tenant": "team-42"
      }
    }
  }
}

Custom Providers

On Node-backed surfaces — Standalone, Desktop, RStudio, and the Terminal (TUI) — you can declare your own providers under the providers.custom key in ~/.posit/ai/providers.json. Each entry is keyed by a name of your choosing — the key is used as the provider’s display name — and declares its behavior with a type field. Positron does not currently expose custom providers; use its built-in provider configuration instead.

{
  "providers": {
    "custom": {
      "acme-ai": {
        "type": "openai-compatible",
        "baseUrl": "https://ai-gateway.acme.com"
      }
    }
  }
}

Supported type values: openai-compatible, aws, snowflake, google-vertex, ollama, lmstudio, deepseek, openrouter, and ms-foundry.

Storage Settings

Logging

Example Configuration

{
  "model": {
    "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"
    ]
  }
}

Developer Settings

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

Environment Variables

Some settings can also be controlled via environment variables. Environment variables take precedence over file-based configuration. See Providers for the full list of provider environment variables.