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: ~/.positai/settings.json
  • Windows: %USERPROFILE%\.positai\settings.json

• Project config overrides global settings for a specific project. Place a .positai/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 ~/.positai/settings.json or a project-level .positai/settings.json. Project values take precedence over global values.

Model Settings

Permissions

Control which tools the assistant can use. Each key is a tool name (bash, read, edit, etc.) mapped to either an action string or an object of glob patterns:

{
	"permission": {
		"bash": {
			"git *": "allow",
			"rm *": "deny"
		},
		"read": "allow",
		"edit": "ask"
	}
}

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.

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.

Compaction

Control how Posit Assistant manages long conversations. See Context Management for details on how compaction works.

Global Settings

The following settings can only be set in the global ~/.positai/settings.json. They are not supported in project-level config files.

Provider Settings

Provider credentials and connection details are configured under the providers key. 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"
      }
    }
  }
}

Google Vertex AI

For Google Vertex AI on non-Positron platforms, configure your Google Cloud project and Vertex AI location, then authenticate with Application Default Credentials:

{
  "providers": {
    "google-vertex": {
      "googleCloud": {
        "project": "my-gcp-project",
        "location": "us-central1"
      }
    }
  }
}

In Positron, configure Google Vertex AI through the provider configuration dialog instead of editing ~/.positai/settings.json directly.

Storage Settings

Logging

Example Configuration

{
  "model": {
    "provider": "positai",
    "id": "claude-sonnet-4-6"
  },
  "permission": {
    "read": "allow",
    "bash": {
      "git *": "allow"
    }
  },
  "skills": {
    "paths": [
      "~/.agents/skills",
      "~/.positai/skills",
      ".agents/skills",
      ".positai/skills",
      "~/my-company/shared-skills"
    ]
  }
}

Environment Variables

Some settings can also be controlled via environment variables. Environment variables take precedence over file-based configuration.

Variable	Description

| GOOGLE_CLOUD_PROJECT | Google Cloud project for the Vertex AI provider | | GOOGLE_CLOUD_LOCATION | Google Cloud location for the Vertex AI provider | | POSITAI_BASE_URL | Custom base URL for the Posit AI provider |