Reference

Configuration

TOML

panto reads layered config.toml files for providers, auth, defaults, TUI settings, and extension policy. Model aliases and pricing live beside them in a separate layered models.toml.

Files & layers

Four config.toml layers are merged, lowest precedence first. Missing files are skipped.

Layer	Path	Role
base	$XDG_DATA_HOME/panto/config.toml · else ~/.local/share/panto/config.toml	Auto-generated defaults.
user	$XDG_CONFIG_HOME/panto/config.toml · else ~/.config/panto/config.toml	Machine-wide personal settings.
project	./.panto/config.toml	Checked-in project defaults.
local	./.panto/config.local.toml	Personal per-project overrides.

Merge rule of thumb: tables merge recursively; scalars and arrays from a higher layer replace lower-layer values. One important exception is [extensions]: its allow/deny rules and source lists accumulate across layers so policy and extra extension sources can be refined instead of erased.

config.tomltoml

[defaults]
model = "anthropic:sonnet"
reasoning = "high"

[tui]
editor = "code -w"
tools_collapsed = false

[providers.anthropic]
style    = "anthropic_messages"
base_url = "https://api.anthropic.com"
auth     = "anthropic_api"

[auth.anthropic_api]
key = "${env:ANTHROPIC_API_KEY}"

[providers.<name>]

A provider describes transport only: API shape, base URL, auth session, and a few request-level knobs. The provider name is the left half of a provider:alias model reference.

stylestringrequired

One of anthropic_messages, openai_chat, or openai_responses.

dialectstring

For openai_responses, the only current dialect is "codex".

base_urlstringrequired

API base URL.

authstringrequired

Names the [auth.<name>] session used for this provider.

prompt_cachebool

Anthropic only. Controls the advancing cache_control breakpoint.

extra_headerstable

Static request headers merged onto every request.

model_catalog_namestring

Optional models.dev provider key for panto models sync.

config.tomltoml

[providers.copilot]
style    = "openai_chat"
base_url = "https://api.individual.githubcopilot.com"
auth     = "github_copilot"

[providers.copilot.extra_headers]
Copilot-Integration-Id = "vscode-chat"
X-Initiator            = "user"

[auth.<name>]

Auth sessions are named, reusable credential sources. If type is omitted, panto infers it from the fields present: key implies api_key; client_id implies oauth_device.

Substitution

Every auth value supports ${...} substitution. ${env:VAR} reads the environment; ${name} reads another key in the same auth block. Unresolved substitutions become the empty string.

API-key sessions

keystringrequired

Usually "${env:VAR}". Resolved eagerly at load time.

OAuth device sessions

client_id / device_code_url / token_urlstringrequired

Core device-flow endpoints.

dialecttoken | codex

codex additionally requires device_poll_url.

scope / verification_url / redirect_uristring

Optional flow details.

exchange_…string

Optional secondary token exchange after device login.

[defaults]

modelstring

Default model as "<provider>:<alias>".

reasoningstring

Session-default reasoning label — the same names the Ctrl+R picker shows.

Model selection falls through in this order: --model, then [defaults] model, then the single-provider/single-alias convenience case. Reasoning falls through similarly: --effort beats a per-alias setting in models.toml, which beats [defaults] reasoning.

[tui]

editorstring

Overrides $VISUAL / $EDITOR for Ctrl+G.

tools_collapsedbool

Initial state of the global tool-output collapse toggle.

Extensions policy & sources

[extensions] governs every Lua-authored capability, including the shipped standard tools. The names you match are extension entry names such as std.read, std.write, std.edit, and std.shell.

allow / denystring[]

Glob rules over entry names. The default is allow; later, more specific rules win, and deny wins an exact tie.

pathsstring[]

Extra directories to scan for extension sources.

rocksstring[]

Installed rock specs to load as extension sources. panto update installs or refreshes them.

config.tomltoml

[extensions]
deny  = ["std.shell"]
paths = ["./dev/panto-ext"]
rocks = ["panto-agent 1.4.2-1"]

[compaction]

keep_verbatimint

Token budget for the recent tail kept verbatim during compaction.

modelstring

Optional provider:alias override for the compaction model.

models.toml

models.toml is layered just like config.toml: base at $XDG_DATA_HOME/panto/models.toml, then user, project, and ./.panto/models.local.toml. Each entry is keyed [<provider>.<alias>]. If an alias is missing entirely, panto simply uses the alias itself as the wire model name.

Common keys

modelstring

Wire model id sent to the provider API. Defaults to the alias.

context_window / max_tokensint

Context metadata for the UI and a per-request output cap.

input / output / cache_read / cache_writefloat

Pricing in USD per million tokens.

OpenAI-style knobs

reasoningstring

Applies to openai_chat and openai_responses: default, off, minimal, low, medium, or high.

Anthropic-style knobs

thinkingstring

disabled, enabled, or adaptive.

effortstring

low, medium, high, xhigh, or max.

thinking_budget_tokens / thinking_interleaved / api_versionint | bool | string

Manual-thinking budget, interleaved-thinking beta header, and Anthropic API version.

System prompt

Prompt files are layered beside the extension tree: base under $XDG_DATA_HOME/panto/agent/, then user, then project. The conventional files are SYSTEM.md, APPEND_SYSTEM.md, and COMPACTION.md.