Configuring agents

agent.json

{
  "model": "claude-sonnet-4-5",
  "modelOverrides": [
    { "channel": "reflection", "model": "claude-haiku-4-5" }
  ],
  "containerNetwork": "sdk-only",
  "timezone": "America/New_York"
}

• model — default Claude model the agent runs on. Channels inherit unless overridden.
• modelOverrides — per-channel (optionally per-phase) model substitutions. Each entry is { channel, phase?, model }. Useful for pinning a cheaper model to a lightweight channel.
• containerNetwork — egress firewall mode. sdk-only (default) lets the agent reach the model provider and nothing else; full opens the container to the internet; none disables egress entirely. Pair with containerAllowedEndpoints to permit specific domains.
• timezone — IANA timezone for cron schedules and time-of-day prompts. Falls back to the server's TZ.

Other optional knobs: backup (snapshot interval and retention), fileWatch (preview limits), maxOutputBytes (cap on user-visible output), showSteps / showConsoleSteps (reasoning-stream visibility).

acl.json

{
  "owner": "operator",
  "allowed": {
    "research-agent": { "lookup": "q" },
    "u:sam@server": { "default": "io" }
  },
  "rejected": {},
  "reject_message": "Not authorized to reach this agent."
}

• owner — identity with full authorization. The default "operator" is an inert label — your CLI and admin sessions hold full access without it. Set a u: identity to give that user unconditional push reach; listing and summary reads stay scoped to the channels they are placed in.
• allowed — nested map: caller identity → channel name → bit string. The caller is a peer agent or a u: user. Channel "*" matches any user-defined channel (not the console-only __* channels).
• rejected — same shape as allowed, but a hard deny. A caller listed here is blocked outright, distinct from an ungranted caller, whose first contact is held for your approval.
• reject_message — what a blocked caller sees.

Permission bits, all from this agent's view of the edge:

Bits describe what this agent does on the edge, not what the peer does. A cross-agent edge needs two entries, one in each agent's acl.json, with complementary bits: sender writes q (or r), receiver writes a, which covers both q and r. For a handover, the sender writes p, and the handed-over user needs free-text access (i) on the receiver, since the pushed-in turn lands as an inbound message. Without both sides, nothing crosses.

provisions.json

{
  "resources": {
    "notes_dir": "/Users/alex/notes",
    "scratch":   { "path": "/Users/alex/scratch", "access": "rw" }
  },
  "pip": { "extra_packages": ["pandas"] },
  "additional_disabled_tools": ["bash"]
}

• resources — host paths bound to resource slots the blueprint declared. Each key matches a slot name; the value is either a bare path string (read-only) or an object with explicit access: "ro" | "rw". Paths are mounted into the agent container at runtime.
• pip.extra_packages — extra Python packages to install. Only honored if the blueprint marked pip.extra_packages unlocked.
• additional_disabled_tools — tools to disable on top of what the blueprint already disabled. Only honored if the blueprint marked the field unlocked.

Slots the blueprint marked required: true must be bound here before the agent will start. Optional slots can be left unbound.

config/ext/email/config.json

{
  "send_mode": "enabled",
  "read_window_days": 14
}

config/ext/email/secrets.json

{
  "imap_user": "alex@example.com",
  "imap_password": "..."
}

mcp-servers.json

{
  "github":   { "GITHUB_TOKEN": "ghp_..." },
  "postgres": { "DB_URL": "postgresql://..." }
}

Top-level key is the MCP server's name from capabilities.json; the inner map is env-var name → value. Only unlocked env slots can be written here — locked slots are vendor-hardcoded and rejected at write time. Required unlocked slots must be filled before the agent will start.