From b350e4dee2412e450b3844061f5c1bc2ec995923 Mon Sep 17 00:00:00 2001 From: t Date: Mon, 6 Jul 2026 15:00:37 -0600 Subject: catch up with latest panto cli developments --- configuration.html | 53 ++++++++++++++--------------------------------------- 1 file changed, 14 insertions(+), 39 deletions(-) (limited to 'configuration.html') diff --git a/configuration.html b/configuration.html index 1823478..48f5ee5 100644 --- a/configuration.html +++ b/configuration.html @@ -20,59 +20,34 @@
Source
- +
-

Reference

Configuration

TOML

panto is configured by layered config.toml files, plus a separate models.toml for model aliases and pricing. Define providers, pick a default model, and gate tools and extensions — everything you specify, nothing you don’t.

Files & layers

Four files are read and merged, lowest precedence first. Missing files are skipped silently.

LayerPathRole
base$PANTO_HOME/config.toml · else $XDG_DATA_HOME/panto/config.tomlAuto-generated by bootstrap. Lowest precedence.
user$XDG_CONFIG_HOME/panto/config.toml · else ~/.config/panto/config.tomlYour personal, machine-wide settings.
project./.panto/config.tomlChecked-in, per-project settings.
local./.panto/config.local.tomlPersonal per-project overrides — git-ignore this. Highest precedence.

Merge semantics: tables merge recursively, but scalars and arrays from a higher layer overwrite wholesale. A project file that sets tools.deny replaces the array entirely — it doesn’t append to a user-level list. Tables accumulate, so a provider defined only at the base layer survives even when a higher layer adds another.

config.tomltoml
# ~/.config/panto/config.toml  (user layer)
+
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.
LayerPathRole
base$XDG_DATA_HOME/panto/config.toml  ·  else  ~/.local/share/panto/config.tomlAuto-generated defaults.
user$XDG_CONFIG_HOME/panto/config.toml  ·  else  ~/.config/panto/config.tomlMachine-wide personal settings.
project./.panto/config.tomlChecked-in project defaults.
local./.panto/config.local.tomlPersonal 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"
 
-[defaults]
-model = "anthropic:sonnet"          # <provider>:<alias>
+[tui]
+editor = "code -w"
+tools_collapsed = false
 
 [providers.anthropic]
 style    = "anthropic_messages"
 base_url = "https://api.anthropic.com"
-auth     = "anthropic_api"          # draws its key from [auth.anthropic_api]
+auth     = "anthropic_api"
 
 [auth.anthropic_api]
-key = "${env:ANTHROPIC_API_KEY}"    # resolved at load
-
-[tools]
-deny = ["std.bash"]                 # allow every tool except the shell
The local layer
./.panto/config.local.toml is meant to be git-ignored: apply your own overrides on top of the checked-in project layer without committing them.
[providers.<name>]
A provider is pure transport: an API shape and a base URL, plus the name of the auth session that supplies its credential. The chosen name is what you reference on the left of a provider:alias model.
stylestringrequired
The wire protocol: anthropic_messages, openai_chat, or openai_responses.
dialect"codex"
A sub-dialect for styles that share a protocol family. Only style = "openai_responses" accepts it today, with the single value "codex" (the Codex Responses variant).
base_urlstringrequired
The API base URL requests are sent to.
authstringrequired
Names the [auth.<name>] session that supplies this provider’s credential. (Provider-level api_key is no longer accepted — auth lives in one place.)
prompt_cachebooldefault true
anthropic_messages only. Place one advancing cache_control breakpoint on each request. Ignored for other styles.
extra_headerstable
A table of static string headers merged onto every model request (see below).
model_catalog_namestring
Maps this provider onto a models.dev catalog key (e.g. "github-copilot") for panto models sync. Defaults to the provider name.
config.tomltoml
[providers.copilot]
+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"
Unresolved providers vanish
If a provider’s api_key auth session resolves to empty (its env var isn’t set), the provider is dropped — export the key to bring it back. OAuth providers always survive and resolve at turn time.
[auth.<name>]
A named auth session supplies a credential. Its type is inferred when omitted: a key implies api_key; a client_id implies oauth_device.
Substitution
Every auth value supports ${…} substitution. ${env:VAR} reads the environment; ${name} reads another key in the same section (handy for a shared domain). An unresolved reference becomes the empty string.
API-key sessions
keystringrequired
The API key — usually "${env:VAR}", but a literal works too. Resolved eagerly at load; an empty result leaves the session unresolved.
type"api_key"
Optional; inferred from the presence of key.
OAuth device sessions
client_idstringrequired
The OAuth client id.
device_code_urlstringrequired
Endpoint that issues the device + user codes.
token_urlstringrequired
Endpoint polled for the access token.
dialect"token" | "codex"default token
Flow dialect. codex additionally requires device_poll_url.
scopestring
Requested OAuth scopes.
verification_urlstring
Override the URL shown to the user.
device_poll_urlstring
Distinct poll endpoint (required for codex).
token_request_format"form" | "json"default form
How the token request body is encoded.
redirect_uri / account_id_jwt_claimstring
Optional flow details.
exchange_urlstring
Enables an optional secondary token exchange. Companions: exchange_method (default GET), exchange_token_path (default token), exchange_expires_path, exchange_base_url_path — JSON paths into the exchange response.
config.tomltoml
[auth.github_copilot]
-client_id       = "Iv1.b507a08c87ecfe98"
-domain          = "github.com"          # an ordinary sibling key…
-device_code_url = "https://${domain}/login/device/code"   # …reused here
-token_url       = "https://${domain}/login/oauth/access_token"
-scope           = "read:user"
-
-# optional secondary token exchange
-exchange_url           = "https://api.${domain}/copilot_internal/v2/token"
-exchange_expires_path  = "expires_at"
-exchange_base_url_path = "endpoints.api"
[defaults]
modelstring
The default model, as "<provider>:<alias>" (exactly one colon, both halves non-empty). The provider must resolve.
Model selection falls through in order: an explicit override (a future --model), then defaults.model, then — if exactly one provider resolved and it has exactly one alias in models.toml — that one. Otherwise panto asks you to set a default.
Tools & extensions
[tools] and [extensions] share the same shape: allow- and deny-lists of glob patterns over dotted names (the standard tools live under the std. namespace — std.read, std.write, std.edit, std.bash).
allowstring[]
Glob patterns. Empty means allow-all (still subject to deny).
denystring[]
Glob patterns. A name is denied if it matches any deny pattern.
A name is permitted when it matches at least one allow pattern (or allow is empty) and matches no deny pattern.
config.tomltoml
[tools]
-allow = ["std.*"]          # only the standard tools
-deny  = ["std.bash"]       # …but never the shell
Conflicts are fatal
The same pattern in both allow and deny for one kind is a hard error — panto refuses to start rather than guess.
[compaction]
panto compacts long conversations automatically; this section tunes it. The manual /compact command uses the same settings.
keep_verbatimintdefault 20000
Token budget for the recent tail kept verbatim when compacting.
modelstring
Optional provider:alias override for the model that writes the summary. Defaults to the active chat model.
models.toml
Model aliases live in $XDG_CONFIG_HOME/panto/models.toml, separate from config.toml. Each entry is keyed [<provider>.<alias>] — the provider matches a [providers.<name>], the alias is the short name you reference. A referenced alias with no entry isn’t an error: it’s used verbatim as the wire name with default knobs.
models.toml is layered exactly like config.toml (base → user → project → local). The base layer is auto-generated — panto models sync fetches the catalog and writes it — so your user and project entries always layer on top and win.
Common keys
modelstring
Wire model id sent to the API. Defaults to the alias.
context_windowint
Total input context window, used for the footer’s context-usage display. Optional.
max_tokensint
Per-request output token cap.
input / output / cache_read / cache_writefloat
Pricing in USD per million tokens. All optional; omitted means unknown.
openai_chat only
reasoningstringdefault default
One of default, off, minimal, low, medium, high.
anthropic_messages only
thinkingstringdefault disabled
disabled, enabled, or adaptive.
effortstringdefault medium
low · medium · high · xhigh · max. Used when thinking = "adaptive".
thinking_budget_tokensintdefault 32000
Reasoning-token budget when thinking = "enabled".
thinking_interleavedbooldefault false
Send the interleaved-thinking beta header (honoured when thinking = "enabled").
api_versionstringdefault 2023-06-01
The anthropic-version header.
models.tomltoml
# ~/.config/panto/models.toml
-
-[anthropic.sonnet]
-model      = "claude-sonnet-4-20250514"   # wire name; defaults to the alias
-max_tokens = 8192
-thinking   = "enabled"
-thinking_budget_tokens = 16000
-input  = 3.0        # USD per million tokens
-output = 15.0
-cache_read  = 0.30
-cache_write = 3.75
-
-[openai.gpt]
-model     = "gpt-4o"
-reasoning = "medium"
-input  = 2.5
-output = 10.0
System prompt
The agent’s system prompt is sourced by convention from Markdown files across the same base → user → project layers (base is $PANTO_HOME/agent, where bootstrap stages the bundled default):
SYSTEM.md
Replaces the system prompt for that layer.
APPEND_SYSTEM.md
Appends to it — for small, additive house rules.
COMPACTION.md
Overrides the summary prompt used during compaction (last layer wins; a built-in default applies otherwise).
On resume, prompt changes are reconciled without rewriting the existing conversation.

-
+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.

+
-- cgit v1.3