The fleet file reference

A complete example

version: 1
goal: Grow this SaaS to 50 paying customers

defaults:
  provider: claude          # or codex
  sandbox: workspace        # readonly | workspace | full
  timeout: 20m
  max_turns: 40

limits:
  tokens_per_day: 2000000
  max_repair_attempts: 2
  catch_up_limit: 3
  wall_clock_per_cycle: 2h

policy:
  never:
    - commit secrets or credentials
    - force push to the main branch
    - email the same person twice
  require_review:
    - pricing changes
    - increase ad spend

roles:
  engineer:
    cadence: "0 2 * * *"
    prompt: Implement the highest-value unfinished task.
    gates:
      - run: npm test
      - run: npm run lint

  content:
    cadence: "0 */2 * * *"
    mode: draft
    prompt: Write one piece of content that serves the goal.
    gates:
      - run: test -n "$(ls -A .nightshift/content)"

  reviewer:
    cadence: "0 4 * * *"
    provider: codex          # a different model reviews the work
    mode: read_only
    prompt: Review last night's changes and report problems.

  finance:
    cadence: "20 */6 * * *"
    mode: read_only
    needs_mcp: [stripe]
    prompt: Write a short revenue report to .nightshift/reports/.

Role fields

• cadence: a five-field cron expression, or @hourly, @daily, @weekly, @monthly. Required.
• prompt: the standing instruction, describing what the role does every time it wakes up.
• mode: read_only, draft or autopublish. Defaults to draft.
• provider: claude or codex. Defaults to the fleet default.
• model: passed through to the provider, so cheap work need not use an expensive model.
• sandbox: readonly, workspace or full. Defaults to the fleet default of workspace.
• timeout: how long a single attempt may take.
• max_turns: a runaway guard. Honoured by Claude Code; Codex has no equivalent.
• gates: commands that must pass before the work is accepted.
• needs_mcp: connector capabilities this role cannot work without.
• add_dirs and allowed_tools: extra directories and per-task tool permissions, on Claude.
• enabled: set to false to keep a role in the file without running it.

Modes decide how far a role can reach

• read_only inspects and reports, and is forced into a read-only sandbox whatever else the file says.
• draft writes files for you to review, and never publishes, posts or sends. This is the default.
• autopublish acts on the outside world. It is always opt-in and is never produced by generation.

Limits are hard ceilings

• tokens_per_day stops the fleet when the day's budget is used, rather than failing halfway through the night.
• max_repair_attempts bounds gate-failure repair, so a permanently broken gate cannot loop until morning.
• catch_up_limit caps how many missed windows are considered after downtime.
• wall_clock_per_cycle bounds a single cycle, so one wedged role cannot consume the night.

The policy layer

Policy rules are injected into the agent's own instructions, which is the only tier that understands intent. A coarse pre-execution screen also catches a task whose description obviously restates a forbidden action, and deterministic caps elsewhere (draft mode, budgets, secret scanning) are what actually stop runaway behaviour.

• never: actions that must not happen at all. The agent is told to refuse the task rather than find a way around the rule.
• require_review: actions allowed only after a human looks at them. The agent stops and writes what it would have done.

Cover the non-code risks too: contacting people, publishing claims, changing prices and spending money.

Sandbox levels

• readonly maps to a plan-only permission mode on Claude and read-only on Codex.
• workspace allows edits inside the working directory. This is the default everywhere.
• full removes isolation and requires allow_full_sandbox: true at the top level, so an escalation cannot hide inside one role's block.