Scheduling

A schedule runs an agent task without anyone starting it: overnight reports, periodic scans, a follow-up that fires hours after a customer signs up. The schedule lives on the board item, not the agent — so the same agent can serve scheduled and ad-hoc work side by side.

Two kinds, set via schedule_kind (values are lowercase and case-sensitive):

• once — runs at next_run_at, then stops.
• interval — runs at next_run_at, then repeats every interval_seconds. The minimum interval is 600 seconds (10 minutes); a smaller value is rejected.

API flow

Each scheduled task is a board item under an actor project. If you don't have a project for the agent yet, create one first — see the agent runtime reference.

wacht api call createProjectTaskBoardItem \
  --param project_id=<project_id> \
  --body @task.json

task.json:

{
  "title": "<short label>",
  "description": "<the prompt the agent runs on each fire>",
  "schedule_kind": "interval",
  "next_run_at": "2026-07-01T09:00:00Z",
  "interval_seconds": 86400
}

description is the prompt the agent reads on every run — the agent has no other memory of why it was scheduled, so make it self-contained. next_run_at is required when scheduling (RFC 3339), and is the first fire time; subsequent interval runs are queued at last_run + interval_seconds. A once task must omit interval_seconds.

Run wacht api describe createProjectTaskBoardItem for the full payload, including the optional mounts array that attaches sandbox-storage files into the thread filesystem on each run.

Persisting state across runs

An interval task gets a fresh thread filesystem each fire, so anything a run wrote is gone by the next one. To carry state forward — a high-water mark, a seen-IDs list, a running tally — write it under the schedule's implicit shared mount at /shared/. It is backed by persistent storage and re-mounted read-write on every run. Read it at the start of each run, write what you want to keep before you finish.

Stopping a schedule

wacht api call archiveProjectTaskBoardItem \
  --param project_id=<project_id> --param item_id=<item_id>

In-flight runs finish; no further runs are queued.