Configuration

This section is the reference shelf: exact option names, defaults and commands. If you want to learn how to set something up, the guides walk you through it in the Web UI, and almost every option here has a switch in Settings.

Where the config file lives

Pando reads the first file it finds, in this order:

./.pando.toml or ./.pando.json in the folder where you start it
The same file in any folder above it, walking up and stopping at your home folder
$XDG_CONFIG_HOME/pando/.pando.toml (usually ~/.config/pando/)
$HOME/.pando.toml or $HOME/.pando.json

Both TOML and JSON work; Pando tells them apart by the file extension. Any value can be overridden for one run with an environment variable prefixed with PANDO_, for example PANDO_DEBUG=true. More in Configuration File Discovery.

Reference pages

Topic	Page
Web UI, remote access, project workspaces	Web UI
AI accounts and models	Providers
Automatic model choice	Auto mode
Working modes (reasoning, caveman, learning…)	Modes
Goal mode	Goal
Memory, knowledge base, code index	Remembrances
Models for code search	Embedding models for code
Subagents and orchestration	Delegation
Learning from past sessions	Self-improvement
MCP servers	MCP
Web search, browser, desktop control	Tools
Language servers	LSP
Editors (ACP)	ACP advanced
Sandbox and command permissions	Sandbox
Docker and Podman	Containers
Skills, Lua, extensions	Skills and extensions
Spending fewer tokens	Token optimization
Updates, diagnostics, database, HTTPS	Diagnostics and maintenance
Encrypting keys	Config security · AGE encryption

Basic configuration

TOML

[data]
directory = ".pando"

[providers.anthropic]
apiKey = "your-api-key"
disabled = false

[agents.coder]
model = "claude-3.7-sonnet"
maxTokens = 5000

[shell]
path = "/bin/bash"
args = ["-l"]

debug = false
autoCompact = true

JSON

{
  "data": {
    "directory": ".pando"
  },
  "providers": {
    "anthropic": {
      "apiKey": "your-api-key",
      "disabled": false
    }
  },
  "agents": {
    "coder": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 5000
    }
  },
  "shell": {
    "path": "/bin/bash",
    "args": ["-l"]
  },
  "debug": false,
  "autoCompact": true
}

Environment variables

Environment Variable	Purpose
`ANTHROPIC_API_KEY`	For Anthropic Claude models
`OPENAI_API_KEY`	For OpenAI models
`GEMINI_API_KEY`	For Google Gemini
`GITHUB_TOKEN`	For Github Copilot
`GROQ_API_KEY`	For Groq models
`AWS_ACCESS_KEY_ID`	For AWS Bedrock (Claude)
`AWS_SECRET_ACCESS_KEY`	For AWS Bedrock (Claude)
`AWS_REGION`	For AWS Bedrock (Claude)
`AZURE_OPENAI_ENDPOINT`	For Azure OpenAI models
`AZURE_OPENAI_API_KEY`	For Azure OpenAI
`AZURE_OPENAI_API_VERSION`	For Azure OpenAI
`VERTEXAI_PROJECT`	For Google Cloud VertexAI (Gemini)
`VERTEXAI_LOCATION`	For Google Cloud VertexAI (Gemini)
`LOCAL_ENDPOINT`	For self-hosted models
`PANDO_DEV_DEBUG`	Enable dev debug mode (`true`)
`SHELL`	Default shell (if not specified in config)

AI Providers

Pando works with Anthropic, OpenAI, Google Gemini, AWS Bedrock, Groq, Azure OpenAI, GitHub Copilot, OpenRouter and local models through a custom endpoint. Accounts and keys are covered in Providers.

Advanced configuration

Below are the advanced options recognized by Pando, with examples in TOML and JSON. Not all fields are required; Pando will use sensible defaults when fields are missing.

Full example (TOML)

[data]
directory = ".pando"           # Directory where Pando stores data (history, commands, caches)

[providers]
[providers.anthropic]
apiKey = "your-api-key"
disabled = false

[providers.openai]
apiKey = "your-openai-key"
model = "gpt-4o"
disabled = false

[providers.gemini]
apiKey = "your-gemini-key"
disabled = true

[agents]
[agents.coder]
model = "claude-3.7-sonnet"
maxTokens = 5000
temperature = 0.2

[agents.chat]
model = "gpt-4o"
maxTokens = 3000
temperature = 0.7

[shell]
path = "/bin/bash"
args = ["-l"]

debug = false                  # Enable detailed logs
autoCompact = true            # Automatically compact long histories

[acp]
enabled = true
max_sessions = 10
idle_timeout = "30m"
log_level = "info"           # info|debug|warn|error
auto_permission = false       # true for CI or trusted environments

[mcpServers]
[mcpServers.my-server]
command = "my-mcp-server"
args = ["--flag"]
env = { MY_VAR = "value" }

[hooks]
# Path to hooks in Lua or other scripts to customize behavior
path = ".pando/hooks"

[storage]
type = "sqlite"               # sqlite|filesystem|custom
path = ".pando/pando.db"

[ui]
theme = "dark"               # UI theme for web-ui if applicable
editor = "nvim"              # default external editor

[telemetry]
enabled = false
endpoint = "https://telemetry.example.com/collect"

[logging]
level = "info"
file = ".pando/pando.log"

Full example (JSON)

{
  "data": { "directory": ".pando" },
  "providers": {
    "anthropic": { "apiKey": "your-api-key", "disabled": false },
    "openai": { "apiKey": "your-openai-key", "model": "gpt-4o", "disabled": false }
  },
  "agents": {
    "coder": { "model": "claude-3.7-sonnet", "maxTokens": 5000, "temperature": 0.2 },
    "chat": { "model": "gpt-4o", "maxTokens": 3000, "temperature": 0.7 }
  },
  "shell": { "path": "/bin/bash", "args": ["-l"] },
  "debug": false,
  "autoCompact": true,
  "acp": { "enabled": true, "max_sessions": 10, "idle_timeout": "30m", "log_level": "info", "auto_permission": false },
  "mcpServers": { "my-server": { "command": "my-mcp-server", "args": ["--flag"], "env": { "MY_VAR": "value" } } },
  "hooks": { "path": ".pando/hooks" },
  "storage": { "type": "sqlite", "path": ".pando/pando.db" },
  "ui": { "theme": "dark", "editor": "nvim" },
  "telemetry": { "enabled": false, "endpoint": "https://telemetry.example.com/collect" },
  "logging": { "level": "info", "file": ".pando/pando.log" }
}

Main options description

data.directory: Base directory for Pando data (commands, history, caches).
providers.: Provider-specific config (apiKey, model, disabled, custom endpoint).
agents.: Agent/role config (model, maxTokens, temperature, optional systemPrompt).
shell.path / shell.args: Default shell and arguments used to launch it.
debug: Enable debug output.
autoCompact: Enable automatic history compaction to save tokens.
acp.*: Agent Client Protocol options (enable, max sessions, timeouts, auto permissions).
mcpServers.*: Define external MCP servers Pando can consume (command, args, env).
hooks.path: Path for custom hooks (Lua, scripts) executed on events.
storage.type/path: Storage type and path (SQLite recommended for persistence).
ui.theme/editor: Preferences for UI/web-ui and external editor.
telemetry.*: Remote diagnostics (disabled by default). See Diagnostics and maintenance.
logging.*: Log level and file.

First-time setup

When Pando finds no configuration it offers to create one: the setup assistant in the Web UI and desktop app, or the configuration panel in the terminal interface. Accounts and tools are also saved in your user profile, so a new project folder starts with what you already set up.