`castellan.toml` reference

Layered configuration for governance, shell policy, hooks, and MCP permissions. Schema source: crates/castellan-governance/src/config.rs.

File locations (merge order)

Layer	Path	Precedence
User	`~/.castellan/config.toml`	lowest
Project	`castellan.toml` (walk up from cwd)	middle
Local	`.castellan/local.toml` (same repo as project `castellan.toml`)	highest

Later layers override earlier ones. CLI flags and environment variables override all files.

Example

[governance]
session_spend_cap_usd = 12.5
max_risk_score = 0.85
denied_paths = ["/secret", "~/.ssh"]

[shell]
allowed_commands = ["echo", "cargo", "git"]
denied_commands = ["rm", "curl"]
denied_patterns = ["sudo .*"]
max_output_bytes = 65536

[permissions]
default_mode = "ask"
[permissions.tools]
castellan_propose_mutation = "deny"
castellan_deposit_signal = "allow"

[[hooks.hooks]]
event = "PreToolUse"
command = "./scripts/hooks/pre-tool.sh"

Sections

`[memory]`

Key	Type	Description
`backend`	`json` \| `sqlite`	Durable store backend (default: `json`)
`path`	string	SQLite database path when `backend = "sqlite"` (default: `.castellan/castellan.db`)
`mirror_json`	bool	Also write `.castellan/episodes/*.json` alongside SQL (default: `true`)
`auto_import`	bool	Import existing JSON corpus on first SQLite open (default: `true`)
`checkpoint_interval_ticks`	integer	Persist mid-episode checkpoints every N scheduler ticks (default: `0` = episode-end only)

See Memory architecture.

`[governance]`

Key	Type	Description
`session_spend_cap_usd`	float	Session spend ceiling
`max_risk_score`	float	Risk score threshold
`denied_paths`	string[]	Paths blocked for tool/file access
`[governance.plan_verify]`	table	Opt-in Guardians-shaped prove-before-execute (default off)

`[governance.plan_verify]`

Key	Type	Description
`enabled`	bool	Require verified `workflow_plan` for high-risk tools (default `false`)
`high_risk_tools`	string[]	Tools that need a certificate (default `shell`, `exec`)
`allowlisted_tools`	string[]	Tools permitted inside a workflow plan
`taint_edges`	array	Optional `{ source_ref_prefix, forbidden_sink_tools }` constraints
`policy_path`	string	Optional TOML file overriding allowlists / taint

See Agent hooks — prove-before-execute.

`[shell]`

Key	Type	Description
`allowed_commands`	string[]	Allowlist for shell plugin
`denied_commands`	string[]	Blocked command names
`denied_patterns`	string[]	Regex patterns to block
`max_output_bytes`	integer	Cap captured stdout/stderr

`[permissions]`

Key	Type	Description
`preset`	`cautious` \| `balanced` \| `permissive`	Approval preset expanded into a base policy
`default_mode`	`allow` \| `ask` \| `deny`	Default MCP tool policy (overrides preset base)
`[permissions.tools]`	map	Per-tool overrides

Permission modes filter tools/list before exposure to MCP clients. castellan doctor reports the active preset.

`[coevolution]`

Fast-slow co-evolution flywheel. See Evolution.

Key	Type	Description
`fast_remediation`	bool	Deposit pheromone hints from failed episodes after each run (default: `true`)
`slow_evolve_every`	integer	Run in-tree `castellan evolve` every N episodes (`0` = off, default)
`slow_evolve_generations`	integer	Generations per slow evolve pass (default: `2`)

`[models]`

Key	Type	Description
`provider`	string	Optional LLM provider: `openrouter`, `openai`, `ollama`, or `openai_compatible`
`base_url`	string	OpenAI-compatible API root; defaults by provider (`openrouter` → `https://openrouter.ai/api/v1`)
`http_referer`	string	Optional `HTTP-Referer` header (OpenRouter attribution; Castellan default when `provider = "openrouter"`)
`x_title`	string	Optional `X-Title` header (OpenRouter attribution; default `Castellan`)
`default`	string	Fallback model id for all roles (default: `mock`)
`verify`	string	Model for the verify client
`act`	string	Model for the act client
`plan`	string	Model for the plan client

Per-role tiers resolve through one OpenAI-compatible client factory (scheduler never routes through an LLM). Auth is env-only — never put API keys in TOML:

Provider	API key env (first wins)
`openrouter`	`OPENROUTER_API_KEY`, then `CASTELLAN_LLM_API_KEY`, then `OPENAI_API_KEY`
`openai` / `openai_compatible`	`OPENAI_API_KEY` or `CASTELLAN_LLM_API_KEY`
`ollama`	optional (`CASTELLAN_LLM_API_KEY` / `OPENAI_API_KEY`); local default URL from `OLLAMA_URL` + `/v1`

[models]
provider = "openrouter"
default = "openai/gpt-4o-mini"
verify = "anthropic/claude-sonnet-4"
act = "openai/gpt-4o"
# optional overrides:
# base_url = "https://openrouter.ai/api/v1"
# http_referer = "https://github.com/Alphabetsoup16/Flock"
# x_title = "Castellan"

--model / --model-tier on castellan run still override; rebuild CLI with --features llm-http for live HTTP providers.

`[[recipes]]`

Key	Type	Description
`name`	string	Recipe identifier for `castellan recipes run <name>`
`description`	string	Shown by `castellan recipes list`
`command`	string	Shell command executed via `sh -c`
`cwd`	string	Optional working directory

Recipes inherit [shell] denied_commands / denied_patterns — they are not a policy bypass. Later config layers override recipes by name.

[[recipes]]
name = "gridworld-smoke"
description = "Run gridworld reach-target and write an episode JSON"
command = "castellan run --goal 'reach target' --plugin gridworld --json"

`[[hooks.hooks]]`

Key	Type	Description
`event`	string	Hook event name
`command`	string	Shell command to invoke

See Agent hooks.

Environment overrides

Variable	Maps to
`CASTELLAN_SESSION_SPEND_CAP_USD`	`governance.session_spend_cap_usd`
`CASTELLAN_MAX_RISK_SCORE`	`governance.max_risk_score`
`CASTELLAN_SHELL_ALLOWED`	CSV → `shell.allowed_commands`
`CASTELLAN_SHELL_DENIED`	CSV → `shell.denied_commands`
`CASTELLAN_DENIED_PATHS`	CSV → `governance.denied_paths`
`CASTELLAN_PERMISSION_MODE`	`permissions.default_mode`
`CASTELLAN_PERMISSION_PROMPT`	Headless Prompt resolution: `allow` \| `deny` (default deny when non-TTY). Legacy shim: `FLOCK_PERMISSION_PROMPT`
`CASTELLAN_MEMORY_BACKEND`	`memory.backend`
`CASTELLAN_MEMORY_DB`	`memory.path`
`CASTELLAN_MEMORY_MIRROR_JSON`	`memory.mirror_json`

Full list: Environment variables.

Keyboard shortcuts

Castellan