Settings Schema

This page is a typed, structured listing of every key in the caliban settings file. For a narrative explanation of how scopes interact, how to locate each file, and how to edit settings interactively, see Settings Reference and Settings Layering.

Settings files are TOML by primary convention (settings.toml / settings.local.toml); JSON is accepted on import only. Unknown top-level keys are tolerated for forward-compat.

Model / Agent

Permissions

Nested under the [permissions] table.

RuleSpec fields (used in permissions.rules entries):

[permissions]
# v2 ordered rules (preferred)
[[permissions.rules]]
pattern = "Bash:git *"
action  = "allow"
comment = "git commands OK"

[[permissions.rules]]
pattern = "Bash:rm *"
action  = "deny"
reason  = "use git revert"

[[permissions.rules]]
pattern = "*"
action  = "ask"

Sandbox

Nested under the [sandbox] table. OS-sandbox posture for Bash commands run under --workspace / --restrict-paths (#406, ADR 0054).

[sandbox]
network = "allow"   # opt out of the default egress fence for this workspace

Hooks

MCP Servers

Under [mcp_servers.<name>]. Each entry configures one MCP server.

[mcp_servers.linear]
command = "npx"
args    = ["-y", "@linear/mcp-server"]

The gonzalo code-graph server is a stdio server consumed the same way — point command at the gonzalo-mcp binary and pass the store root (populated with gonzalo index) via env. Its tools then surface as mcp__gonzalo__{search,node,callers,callees,impact,explore}:

[mcp_servers.gonzalo]
command = "gonzalo-mcp"
[mcp_servers.gonzalo.env]
GONZALO_ROOT = "/path/to/graph-store"

Router

Router config resolves through the settings layer: the router value flows through the normal settings precedence and shows up in caliban config print with its source scope like any other key. The one exception is an explicit --config <PATH> / CALIBAN_ROUTER_CONFIG file, which is the highest-precedence source and overrides the settings [router] section when set. If neither is present, caliban uses the single-provider fallback.

Per-provider overrides (api_key_env / base_url — e.g. for a proxy or a keyless local endpoint) go under [router.provider.X]:

[router]
default_purpose = "main_loop"

[[router.route]]
purpose = "main_loop"
provider = "openai"
model = "local-model"

[router.provider.openai]
base_url = "http://localhost:8080/v1"

Memory

Nested under [memory].

Plugins

UI

Auth

Observability

Context-Window Management

Stream Watchdog

The streaming idle watchdog aborts a run when a response goes silent for too long. It distinguishes two phases: prefill (before the first output token — where a slow local model with a large context may legitimately pause) and mid-content (after the first token, where a long gap signals a genuine stall).

Agent-Loop Policy

The [agent_loop] group gathers agent-loop policy — the turn budget and the spiral-containment guards — under one surface, distinct from the model-inference knobs (effort, thinking) that govern a single call (ADR 0058). Every key is optional and defaults to the value the loop has always used, so an absent group changes nothing.

[agent_loop]
max_turns = 80              # or pass --max-turns (CLI wins)
no_edit_nudge_threshold = 8

Profiles. Each profile sets a coherent verification posture (the lever eval sub-project A proved load-bearing, whose sign flips with model strength: +8pt on a strong cloud model, −16pt on a weak local one). Budgets (max_turns / time_budget_secs / cost_budget_usd) stay opt-in — a profile never imposes a surprising hard cap.

Precedence: an explicit knob (e.g. verification_guidance) > the named profile > the context-adaptive default.

max_turns and the three guards were the existing loop knobs; time_budget_secs (B2, #662), cost_budget_usd (B3, #663), verification_guidance (B5, #665), and profile + adaptive defaults (B6, #666) are the additions. The remaining child — the eval-gated wrong-path/divergence guard (B4, #664) — will complete the local-guarded pairing when it lands.

Enterprise (Managed Scope)

Miscellaneous

Environment overrides

A subset of settings can be overridden by CALIBAN_* environment variables that are read into the settings layer. The environment wins over the settings file, and each override is attributed in caliban config print under _env_overrides (a list of { key, env }) so you can see exactly which key an environment variable set — the environment is a real, visible source, not a silent side channel (#538).

A blank (empty / whitespace-only) value is ignored — the file setting stands.