Agent configuration

An agent is configured by one agents/<id>/settings.yaml with an optional section per concern. Sections resolve across <project>/.ziro/, then ~/.ziro/, then the bundled package, deep-merged most-specific-last. A missing section falls back to built-in defaults. Legacy split files (shell_policy.yaml, …) still resolve at each layer as an alternative to the matching section; see the configuration guide.

Per-agent sections

The section key is the old file name minus its _policy / _servers / _config suffix.

Section	Legacy file	Controls	Default
`meta`	`meta.yaml`	Name, description, `enabled`, pinned `model` / `provider`, transport `retry`	Required
`persona`	`agent_config.yaml`	The persona and soul prompt	On
`tools`	`tool_policy.yaml`	`core_tools`, deferred tiers, `max_active`	On
`permissions`	`permissions.yaml`	Per-tool allow / deny / ask gating	On
`guardrails`	`guardrails_policy.yaml`	Input and output guard toggles and backends	Per agent
`compaction`	`compaction_policy.yaml`	Trigger percentage, strategy, tool-output caps	On
`mcp`	`mcp_servers.yaml`	Selector over the shared MCP catalog + inline servers	Empty
`hooks`	`hooks.yaml`	Lifecycle hook specs by event and matcher	Empty
`memory`	`memory_policy.yaml`	Fact extraction, reflection, project memory	On
`shell`	`shell_policy.yaml`	`run_shell` mode, interpreter, denylist, timeouts	Off
`fs`	`fs_policy.yaml`	Read tools, `allow_write`, confinement, scratch, `deny_paths`	On
`webfetch`	`webfetch_policy.yaml`	`web_fetch`, SSRF guard, content caps	Per agent
`websearch`	`websearch_policy.yaml`	`web_search` provider and caps	Per agent
`subagents`	`subagent_policy.yaml`	Allowed children, depth, spawn caps, model defaults	On
`handoff`	`handoff_policy.yaml`	`request_handoff`, operator prompt, timeout	On
`clarify`	`clarify_policy.yaml`	`ask_user_question`, question and option limits	On
`queue`	`queue_policy.yaml`	Background worker queue (per-agent knobs)	Worker off
`voice`	`voice_policy.yaml`	STT and TTS backends	Off
`attachments`	`attachment_policy.yaml`	Image size and type limits, notices	On
`agents_md`	`agents_md_policy.yaml`	`AGENTS.md` ingestion and token cap	On
`plugins`	`plugin_config.yaml`	Which plugins may surface for this agent	Absent means none

Two rules worth knowing: an agent no layer supplies a plugins section for surfaces zero plugins (absence is opt-out, unlike every other section), and a malformed plugins section fails closed rather than falling back to permissive.

Top-level (app / instance) tier

Host-resource knobs live in a layer-root settings.yaml, not on an agent, because a thread can switch agents mid-conversation. Where a knob is unset here it falls back to the matching per-agent section.

Section	Key	Controls
`resources.subagents`	`max_parallel`, `max_background`	Subagent fan-out ceilings
`resources.jobs`	`workers`, `max_depth`, `inflight_max_depth`, `job_recursion_limit`, `result_ttl_days`	Background job pool
`resources.scratch`	`ttl_days`, `clear_on_resume`, `max_scratch_bytes`	Scratchpad GC / quota
`resources.background_shells`	`ttl_hours`, `persist_default`	Durable background-shell GC
`security.fs_deny_paths`	list of globs	Floor: added to the shipped secret denials, never subtractable

resources are ceilings (a project may lower, never raise, and an untrusted project is ignored). security.fs_deny_paths is the symmetric floor: it only ever tightens what the filesystem tools refuse.

Shared MCP catalog

Server definitions are a workspace resource, so they live once in the mcp.servers map of a layer-root settings.yaml (merged across layers, tokens interpolated). The per-agent mcp section is a selector over that catalog:

# <layer>/settings.yaml (the catalog)
mcp:
  servers:
    github: { transport: stdio, command: ..., env: { GITHUB_PAT: ${GITHUB_PAT} } }
    searxng: { transport: streamable_http, url: ... }

# agents/<id>/settings.yaml (the per-agent selector)
mcp:
  enable: [github, "team-*"]   # globs over catalog ids; no enable → nothing
  deny: []
  servers: {}                  # optional inline private servers (win an id clash)

An untrusted project’s catalog is ignored wholesale. See MCP.

Worked example

# agents/default/settings.yaml
meta:
  name: Generalist
  description: Autonomous goal-driven generalist.
  enabled: true
  model: minimax/minimax-m3
  provider: openrouter
  retry: { enabled: true, max_attempts: 3, base_delay: 1.0, max_delay: 20.0 }
permissions:
  default_action: allow
  dangerous_default_deny: ["shell:*"]
  ask: ["fs_write:*", "shell:run_shell"]   # HITL every write and every command
  allow: ["rag:*", "memory:*", "shell:run_shell"]
shell:
  enabled: true
  interpreter: bash
fs:
  allow_write: true
  # The shipped secret denials are a non-removable floor; this only ADDS to them.
  deny_paths: ["build_secrets/*"]

Configuration

Layer resolution, the resource tier, flavour overlays, and migrate-config.

Permissions

The permissions section in depth.

Command line

Configuration

SDK

Agent configuration

Per-agent sections

Top-level (app / instance) tier

Shared MCP catalog

Worked example

Configuration

Permissions

​Per-agent sections

​Top-level (app / instance) tier

​Shared MCP catalog

​Worked example

Configuration

Permissions

Per-agent sections

Top-level (app / instance) tier

Shared MCP catalog

Worked example