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 filesystem and network isolation for bash tool execution. When enabled, shell commands run inside a platform-specific 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.

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 for a provider’s API in the config file. This is useful for enterprise proxies or custom API gateways.

{
  "providers": {
    "positai": {
      "baseUrl": "https://my-proxy.example.com"
    }
  }
}

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

| POSITAI_BASE_URL | Custom base URL for the Posit AI provider |