Projects and config
The config lives at ~/.config/agent-mailbox/config.json. It holds no secret. Restart an idle runner after you change it.
Projects
Only project aliases in the config can be picked. The subject Codex/website: fix the build runs in the project named website. Without a project, tasks run in default_project.
"projects": {
"main": "/absolute/path/to/project",
"website": {
"path": "/absolute/path/to/another/project",
"sandbox": "read-only",
"agents": {
"codex": {"approval_policy": "on-request", "approvals": "email"}
}
}
},
"default_project": "main"Agent names ignore case. Project aliases are case sensitive.
Several tasks at once
Set max_workers to run tasks side by side. The default is 1 and the maximum is 32. Each project folder runs one task at a time. Set "concurrent": true on a project to let separate tasks share its folder. Turns in one thread always run in order.
Codex permissions
With approvals off, Codex uses workspace-write and does not wait for approval prompts. Set codex_sandbox to read-only for a stricter baseline. Sandboxes are read-only, workspace-write or danger-full-access. Approval policies are never, on-request, untrusted or on-failure.
Settings resolve in this order: project and agent, project, agent, global, then the defaults.
Claude Code permissions
With approvals off, Claude runs in dontAsk mode. It may read, edit, write, search, run Bash and fetch the web. It denies anything that needs an approval prompt, and the turn ends as needs_review with the denied calls listed.
bypassPermissions removes every denial.
"claude_permission_mode": "bypassPermissions" runs Claude with --dangerously-skip-permissions. Every tool call runs without review. Scope it to one trusted project. It cannot be combined with approval emails.
Models
You can set an agent's default model or restore the agent's own default:
For one task, put the model in square brackets: Claude [opus]: review the auth flow. Replies in that thread keep the model.
Headless or Terminal
@gent runs tasks headless by default and emails the result. Terminal mode opens each task in a new Terminal window with an interactive session.
A subject can choose for one task: Claude [opus, terminal]: your task. For Claude terminal tasks, atgent remote-control on starts the session with Remote Control.
Limits
The defaults are 20 MiB per raw message, 5 MiB per attachment, 10 MiB of attachments in total, 10 attachments and 32,000 characters of task text. Lower them with max_message_bytes, max_attachment_bytes, max_attachments_bytes and max_attachments.
Agent accounts
The runner reuses your existing CLI sign-ins. It removes inherited provider API keys before it starts an agent. An explicit env entry on the agent can add one back. To use a separate Claude account, set CLAUDE_CONFIG_DIR in agents.claude.env.