Repository policy

Agent Zero reads its per-repository policy from .agent-zero.yml at the repository root. Create one with:

zero init

Repository policy is deliberately limited: it can restrict what Agent Zero does, but it can never name endpoints or credentials — those come only from the environment, so untrusted repository configuration cannot redirect a secret.

The annotated template lives at .agent-zero.example.yml. packages/config parses and validates it.

Mode

version: 1
mode: observe

observe and suggest can never write. fix and autonomous also require autofix.enabled below. See the Safety model for the full authorization chain.

Proactive review

proactive:
  enabled: false

When enabled, authenticated pull_request webhooks trigger a diff inspection. The configured mode controls whether the run reports only or requests autofix authority.

Issues

issues:
  enabled: false
  requireLabel: agent-zero
  branchPrefix: agent-zero/
  validationComment: true

Turn scoped GitHub issues into verified pull requests. Opt-in twice: enable it here and label the issue with requireLabel. See Issue-to-PR workflow.

Checks

checks: []

Commands used to verify a change. Leave empty to discover the repository's own lint, typecheck, test, and build scripts. Commands run without a shell, so operators such as &&, |, ;, and $() are rejected.

Autofix

autofix:
  enabled: false
  minConfidence: 0.85
  allowedChangeRisks:
    - mechanical
  requireIsolated: true

• minConfidence — confidence required before Agent Zero may change files.
• allowedChangeRisks — mechanical is the conservative default. behavioral may be added explicitly; high-impact changes always require human approval and cannot be enabled here.
• requireIsolated — proactive and autonomous writes require a runner that can prove isolation.

Validation

validation:
  minConfidence: 0.6
  requireEvidence: true
  requireKnownFiles: true
  verifyQuotedEvidence: true

How a reviewer's claim is checked against the repository before it is acted on. Below minConfidence, a supported claim is reported as inconclusive — never fixed.

Agent limits

agent:
  maxAttempts: 3
  timeoutMs: 1800000
  maxChangedFiles: 10

maxAttempts bounds repair loops before a run stops and asks for a human. maxChangedFiles is the upper bound on files a single narrow fix may touch.

Permissions and runner

permissions:
  network: restricted # none, restricted, or full

runner:
  isolation: local # local for trusted development; container for production
  engine: docker
  # image: node:22-bookworm-slim
  workdir: /workspace
  # cpus: '2'
  # memory: 4g
  # network: agent-zero
  maxOutputBytes: 200000

local runs commands on the host and is for trusted development only. container is required for production; set an image to enable it. permissions.network is enforced by the container runner.

Model

model:
  provider: openai-compatible # ai-gateway, anthropic, google, openai, or openai-compatible
  name: gpt-5
  # inputCostPerMillionTokens: 1.25
  # outputCostPerMillionTokens: 10

Credentials are read only from the provider's documented environment variable; they are never accepted from repository configuration or persisted with task evidence. Configure explicit pricing to record cost — Agent Zero never guesses provider pricing. See Model providers.