Agent configuration files

Every agent lives in its own folder and is self-contained. Files resolve most-specific-first across <project>/.ziro/agents/<id>/, then ~/.ziro/agents/<id>/, then the bundled package, so an installed Ziro is configured under your home directory without editing the package. A missing file falls back to built-in defaults.

File	Controls	Default
`meta.yaml`	Name, description, `enabled` flag, pinned `model`, pinned `provider`	Required
`agent_config.yaml`	The persona and soul prompt	On
`tool_policy.yaml`	`core_tools`, deferred tiers, `max_active`	On
`permissions.yaml`	Per-tool allow / deny / ask gating	On
`guardrails_policy.yaml`	Input and output guard toggles and backends	Per agent
`compaction_policy.yaml`	Trigger percentage, strategy, tool-output caps	On
`mcp_servers.yaml`	External MCP servers and transports	Empty
`hooks.yaml`	Lifecycle hook specs by event and matcher	Empty
`memory_policy.yaml`	Fact extraction, reflection, project memory	On
`shell_policy.yaml`	`run_shell` mode, interpreter, denylist, timeouts	Off
`fs_policy.yaml`	Read tools, `allow_write`, confinement, scratch, `deny_paths`	On
`webfetch_policy.yaml`	`web_fetch`, SSRF guard, content caps	Per agent
`websearch_policy.yaml`	`web_search` provider and caps	Per agent
`subagent_policy.yaml`	Allowed children, depth, spawn caps, model defaults	On
`handoff_policy.yaml`	`request_handoff`, operator prompt, timeout	On
`clarify_policy.yaml`	`ask_user_question`, question and option limits	On
`queue_policy.yaml`	Background worker queue	Worker off
`voice_policy.yaml`	STT and TTS backends	Off
`attachment_policy.yaml`	Image size and type limits, notices	On
`agents_md_policy.yaml`	`AGENTS.md` ingestion and token cap	On
`plugin_config.yaml`	Which plugins may surface for this agent	Absent means none

This page will expand each row with its schema, the meaningful keys, and a worked example. Two rules are worth knowing now: a missing plugin_config.yaml means the agent surfaces zero plugins (absence is opt-out, unlike every other file), and a malformed one fails closed rather than falling back to permissive.

This page is in progress. See the configuration guide for how the layers resolve and how flavours overlay them.

Configuration

Layer resolution, flavour overlays, and project trust.

Permissions

permissions.yaml in depth.

Command line

Configuration

SDK

Agent configuration files

Configuration

Permissions