Scheduled Tasks
A scheduled task is a saved prompt that runs an agent session on a recurring schedule. You provide the agent to run, the prompt to send it, and a recurrence rule (RRULE); the task then fires automatically on its schedule until you delete it.
Agents create and manage scheduled tasks through the built-in
sys_scheduled_task_create tool.
Required fields
Every scheduled task needs four things:
| Field | Description |
|---|---|
name | A human-readable name for the task. |
prompt | The instruction sent to the agent on each firing. |
rrule | The recurrence rule. It may fire no more often than once per hour. |
agent_id | The agent that runs on each firing. |
Choosing where the task runs
The host_id and workspace fields are both optional. How you set them
determines where each run lands:
- No host, no workspace — the task runs on the owner's live host at fire time, starting in that host's home directory. This is the right choice for tasks that touch no code directory, such as MCP-only, research, summary, or chat-only tasks. The owner must have an online host when the task fires; if none is online, the run is recorded as failed.
- Pinned host, no workspace — the task always runs on the host you pinned, starting in that host's home directory. The workspace defaults to the launch host's home whether the host was pinned or resolved at fire time.
- Pinned host and workspace — the task runs on the pinned host in the
workspace you specify.
workspacemust be an existing absolute path on that host.
A workspace without a host_id is rejected — a path with no machine to
run it on is meaningless.
When you pin a host_id, its existence and ownership are authorized at create
time, so a nonexistent or non-owned host is rejected immediately rather than
silently failing only when the task fires.
Example
An MCP-only task that runs every weekday morning, with no pinned host or workspace:
name: Morning digest
prompt: Summarize any new issues opened overnight and post the digest.
rrule: FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0
agent_id: ag_...
# host_id and workspace omitted — runs on your live host, in its home directory
To pin the task to a specific host and repository instead, add both fields:
host_id: <connected host id>
workspace: /absolute/path/to/repo