Scheduled Tasks

A scheduled task is a saved prompt that fires an agent session on a recurring schedule. Point it at an agent, a prompt, a recurrence rule, and a place to run, and Omnigent launches that agent automatically on every occurrence — no one has to be at the keyboard.

Scheduled tasks are managed through four built-in tools that every agent has automatically. They are framework-owned and auto-registered, so an agent can create, list, update, and delete its own recurring runs at runtime without the agent YAML opting in. Under the hood the runner dispatches each tool to the Omnigent server's /v1/scheduled-tasks REST endpoints.

The built-in tools

Tasks are scoped to the calling user (or the single local user when auth is disabled). You only see and manage your own tasks; a task owned by someone else is not enumerable.

Approval for create and update

Because a scheduled task persists work that will later run unattended, an agent cannot save or change one silently. Every call to sys_scheduled_task_create or sys_scheduled_task_update pauses for your interactive approval before the task is written:

Approve these scheduled task settings for future unattended runs?

Review the agent, prompt, host, and permission settings in that request before accepting. The gate fires even when the call omits optional fields — inherited defaults (for example, the host resolved at fire time or the agent's own model and permission mode) are persisted too, so they also need your consent. Declining denies the call and nothing is saved.

This check is an always-on guard, not something you configure: it is appended to every session's policy set — including sub-agent sessions — even when no policies are declared anywhere, and it cannot be removed. See Always-on approval guards.

sys_scheduled_task_list and sys_scheduled_task_delete do not trigger this prompt. Tasks you create or edit directly in the web UI or through the /v1/scheduled-tasks REST API keep their existing authorization rules.

Creating a task

sys_scheduled_task_create takes these fields:

• name (required) — a human-readable task name, e.g. nightly triage.
• prompt (required) — the instruction dispatched to the agent on each firing.
• rrule (required) — the recurrence rule (see Recurrence rules).
• agent_id (required) — the agent to run, e.g. ag_abc123 (from sys_agent_list or sys_agent_get).
• execution_target (optional) — where each firing runs: connected_host (default) or managed_sandbox. See Where a task runs.
• host_id (optional, connected_host only) — pin the run to a specific connected host, from the current workspace's host list. Omit to run on your online host at fire time; a failed run is recorded if none is online. An existing managed sandbox host cannot be pinned.
• workspace (optional, connected_host only) — an existing absolute path on the host where the fired session's runner starts. Requires host_id; omit it to start in the host's home directory.
• timezone (optional) — the IANA timezone the rule is evaluated in, e.g. America/Los_Angeles. Defaults to UTC.
• model_override (optional) — a per-run model override. Omit for the agent default.
• reasoning_effort (optional) — a per-run reasoning-effort hint, e.g. high. Omit for the agent default (the spec's executor.reasoning_effort, or the harness default when the spec sets none).

Once created, the task fires automatically on its schedule until you delete it.

Recurrence rules

The schedule is an RFC 5545 RRULE string, evaluated in the task's timezone. Examples:

FREQ=DAILY;BYHOUR=9;BYMINUTE=0                       # daily at 9am
FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0 # weekday mornings

Rules are validated when you create or update a task. A rule is rejected (HTTP 400) if it has bad syntax, never fires, fires only once, or fires more often than the minimum interval. A task must fire at least twice and no more often than once per hour — the minimum gap between any two consecutive fires is 60 minutes.

Pausing, updating, and deleting

sys_scheduled_task_update changes only the fields you pass; the rest are left untouched. You can update name, prompt, rrule, timezone, model_override, reasoning_effort, workspace, host_id, execution_target, and state.

Passing execution_target=managed_sandbox switches the task to a fresh sandbox per run and clears any pinned host_id and workspace; don't set either field in the same update. Switching back to connected_host leaves the task unpinned until you set a host again.

The state field accepts active or paused:

• Pass state=paused to stop a task firing without deleting it.
• Pass state=active to resume it.

To remove a task permanently, use sys_scheduled_task_delete — deletion is not done through update.

Where a task runs

execution_target picks the machine each firing runs on.

connected_host (default)

The task runs on one of your own connected hosts. Pin a specific host with host_id (and optionally a workspace on it), or leave both unset and Omnigent resolves your most-recently-active online host when the task fires, starting in that host's home directory. Server-managed sandbox hosts are never picked by this resolution, and pinning one as host_id is rejected — a warm sandbox from an interactive session would leak its state into the run and break once it is gone. If no live host can be resolved (or the pinned host is offline), the occurrence is recorded as a failed run.

managed_sandbox

Each firing provisions a fresh server-managed sandbox — the same launch path as choosing New Sandbox for a chat (see Cloud Sandbox Host). The session starts in the sandbox's clean server-created workspace, so host_id and workspace must not be set; a create or update that combines them with managed_sandbox is rejected. The server must have managed sandboxes configured — an unconfigured server rejects the task at create time rather than failing every fire.

A sandbox created by an automation follows the server's normal sandbox lifecycle, exactly like one created for a chat: the automation does not override timeouts or terminate the sandbox when the run finishes. Server operators should choose provider lifetime, idle, and cleanup settings that fit their automation frequency and resource budget; enabling managed sandboxes alone does not guarantee a short shutdown time.

How a firing runs

When a task is due, Omnigent:

1. Re-reads the task row — a task that was deleted or paused since the timer was armed is skipped. Under built-in accounts auth, the run also confirms the task's owner is still the same registered account and that the target host_id belongs to that owner; a task whose owner account has been removed is marked deleted and the run is recorded with error code owner_deleted.
2. Resolves the launch target for this fire only. A connected_host task fills in an unpinned host and workspace as described above; a managed_sandbox task starts hostless and binds a new sandbox in step 4. Resolved values are never written back to the task.
3. Creates a session bound to the task's agent, carrying the stored model_override and reasoning_effort, and grants the task's owner ownership of the new session so the run is visible.
4. Launches the runner — on the resolved host, or in a freshly provisioned sandbox — and dispatches the prompt so the agent actually runs.
5. Records the run — stamping the task's last-run time and the run's conversation id.

A few scheduling guarantees:

• The database is the source of truth. On server start, every active task is re-armed from the store.
• Missed fires are not replayed. If the server was down when a task was due, only the next future occurrence is armed — Omnigent does not backfill.
• Overlapping fires are skipped. If a task's previous run is still in flight when the next occurrence arrives, that occurrence is dropped.
• Removed accounts stop firing. When an admin removes a member, all of that user's tasks are marked deleted. A username that is later re-registered does not see or inherit the old account's tasks.