AgentOS markAgentOS

Scheduling


AgentOS scheduling lets you run recurring or one-time agent work from the gateway. Use it for reminders, periodic summaries, status checks, channel updates, and webhook-delivered automation.

Scheduling is managed with the agentos cron command group.

Requirements

Scheduled jobs run through the gateway:

agentos gateway run

For long-lived local use, start the managed gateway:

agentos gateway start --json
agentos gateway status

List Jobs

agentos cron list
agentos cron list --agent main
agentos cron list --json

Job visibility is scoped to the selected profile, not to the session that created each job. Calls from the Control UI, CLI, or a paired channel therefore see the same profile-wide schedule list. The creation session is retained as delivery metadata and shown as Created from when available.

Add an Interval Job

Run a prompt every hour:

agentos cron add \
  --every 1h \
  --job-kind agent_turn \
  --text "Summarize important project updates" \
  --name hourly-project-check

Intervals accept values such as 30s, 5m, and 1h.

Add a Cron Expression

Run on weekdays at 09:00 in a named timezone:

agentos cron add \
  --cron "0 9 * * 1-5" \
  --tz "America/Los_Angeles" \
  --job-kind agent_turn \
  --text "Prepare a short morning brief" \
  --name weekday-morning-brief

Use --exact when you do not want the default stagger.

Day-of-month and day-of-week follow the POSIX rule: when both fields are restricted (neither is a bare *), the job fires when either matches. So 0 0 1,15 * 5 runs on the 1st, the 15th, or any Friday. When one of the two is *, the fields are ANDed as usual — 0 0 1 * * is the 1st only, and 0 0 * * 5 is Fridays only.

Add a One-Time Job

agentos cron add \
  --at "2026-06-01T09:00:00+00:00" \
  --text "Remind me to review the launch checklist" \
  --name launch-checklist-reminder

Job Kinds

--job-kind decides what actually happens when a job fires. It defaults to auto, which resolves to reminder for normal targets, system_event for --session-target main, and script when you pass --script.

KindWhat firesSpends tokens
reminderYour --text is delivered verbatim. Nothing else runs.No
scriptA file in ~/.agentos/scripts/ runs; its stdout is delivered.No
agent_turnThe agent runs --text as a prompt and its reply is delivered.Yes
system_eventThe text is written into the main session and wakes the heartbeat.Yes

An agent_turn job can also carry a --script, which then runs before the turn as a data collector — see Pre-run scripts.

The default matters: agentos cron add --every 1h --text "Summarize updates" creates a reminder, so it repeats that sentence every hour rather than summarizing anything. Add --job-kind agent_turn when you want the agent to do the work.

Run a Script Instead of a Model

A script job is the watchdog shape — poll something on a timer, deliver a line when it matters, stay quiet otherwise — with no LLM in the loop:

mkdir -p ~/.agentos/scripts
cat > ~/.agentos/scripts/watch-memory.sh <<'EOF'
#!/usr/bin/env bash
used=$(ps -A -o %mem | awk '{s+=$1} END {printf "%d", s}')
[ "$used" -gt 90 ] && echo "⚠ memory at ${used}%"
EOF

agentos cron add --every 5m --script watch-memory.sh --name memory-watchdog
agentos cron update <job-id> --script watch-disk.sh

The script path is relative to ~/.agentos/scripts/. Absolute paths, ~, and .. are refused, and a symlink that leaves the directory is refused at run time — the directory is the trust boundary. .sh and .bash run under bash; every other extension runs under the same Python interpreter as the gateway. Pass --workdir to run somewhere other than the script's own directory; a relative value is resolved against the script's directory, not the gateway's, so --workdir data means ~/.agentos/scripts/data. A workdir that does not exist falls back to the script's directory with a warning in the gateway log.

Subdirectories under ~/.agentos/scripts/ are allowed, and {job_id} anywhere in the path is replaced with the created job's own id:

agentos cron add --every 10m --script 'lp-monitor/{job_id}/tick.sh' --name lp-ratchet

That gives a job a directory named after itself in a single add — the id does not exist until the job does, so the alternative is to create the job against a staging path and repoint it afterwards, leaving a live job pointing at a path it will not keep. The job it prints back carries the resolved path in its script field; write the file there. A job whose stored path somehow still holds {job_id} refuses to run rather than creating a directory by that name.

Arguments go through --script-arg, repeated once per argument:

agentos cron add --every 15m --script watch_rss.py --name hn-watch \
  --script-arg --name --script-arg hn \
  --script-arg --url --script-arg https://news.ycombinator.com/rss

They are passed to the script as argv with no shell in between, so a value containing spaces or ; stays one argument and cannot start a second command. The Web UI takes them as one line and splits it the way a shell would.

The bundled cron-watchers skill ships ready-made scripts for the common sources (RSS/Atom, a JSON endpoint, a GitHub repo) that already follow this contract — ask the agent for it, or see agentos skills view cron-watchers.

What the job does with the result:

  • stdout → delivered verbatim, exactly as printed (capped at 16k characters).
  • no stdout → silent run. Nothing is delivered and the run counts as a success, so a watchdog that prints only on trouble stays quiet.
  • a final line of {"wakeAgent": false} → also treated as silence, so watchdog scripts written for other runtimes work unchanged. Nothing is delivered, but what the script printed stays on the run record, where agentos cron output <job-id> shows it.
  • non-zero exit or timeout → the error is delivered and the job fails, so a broken watchdog cannot be mistaken for a quiet one. --timeout bounds the run (default 600s).

Secrets are masked in both stdout and stderr before delivery, and AgentOS's own controls (AGENTOS_GATEWAY_TOKEN and the redaction/sensitive-path switches) are withheld from the child process. Provider credentials are not — a script inherits OPENAI_API_KEY and friends exactly like every other AgentOS child process, which is what lets a watcher call a model API of its own. Set AGENTOS_STRIP_PROVIDER_ENV=1 to withhold those too.

What you are accepting. The script runs on this host as you, on schedule, with nobody watching and no approval prompt — there is no LLM deciding what to run, but also nothing reviewing it. Treat ~/.agentos/scripts/ as trusted as your shell profile, and remember that anything with write access to that directory can schedule itself. For that reason a script job can only be created by an interactive CLI or Web caller: the in-agent cron tool refuses job_kind='script' from a channel, which keeps a chat message from scheduling unattended execution.

Script jobs never take --elevated — elevation only means something for a job that runs an agent turn.

Pre-run Scripts

The other half of the same idea: keep the script, but let an agent read what it found instead of the user. Add --script to an agent_turn job and it runs first, as a data collector:

agentos cron add --every 10m --name repo-triage \
  --job-kind agent_turn \
  --script watch_github.py \
  --script-arg --repo --script-arg owner/name \
  --script-arg --scope --script-arg issues \
  --text "Summarize anything here that looks urgent. Stay brief."

Per tick:

  • stdout → prepended to the prompt as ## Script output, then the turn runs with your --text after it.
  • no stdout (or a {"wakeAgent": false} final line) → the turn is skipped entirely. No LLM call, no session, no transcript line, no delivery. This is what makes the pattern cheap: the agent only wakes on ticks with news.
  • non-zero exit → the error is prepended as ## Script error and the turn runs anyway, so the agent can tell the user the collector broke.

Same directory rule, same argv handling, and the same operator gate as a script job. The script's stdout is untrusted input arriving inside a prompt — the header says so to the model, but the turn still runs elevated by default (cron_default_mode="bypass"), so that output can drive real shell-based skill calls with no approval prompt. Pass --no-elevated to drop a job back to a read-only tool surface, and prefer that whenever a pre-run script reads the open internet.

Choose the Session Target

The default target is an isolated session. For most scheduled work, that is the least surprising option.

Useful targets:

TargetUse when
isolatedEach scheduled run should stand alone.
sessionYou want to deliver into a specific session configured by the runtime surface.
currentThe job should continue in the session that created it (requires a bound session).
mainYou want a system event for the main session.

Example:

agentos cron add \
  --every 30m \
  --session-target isolated \
  --text "Check for urgent channel updates" \
  --name urgent-update-check

Delivery

Disable delivery:

agentos cron add \
  --every 1h \
  --text "Create a private summary" \
  --no-deliver \
  --name private-hourly-summary

Deliver through a webhook:

agentos cron add \
  --every 1h \
  --text "Post a compact status summary" \
  --webhook-url https://example.com/hooks/agentos \
  --webhook-token-env AGENTOS_WEBHOOK_TOKEN \
  --name webhook-status-summary

Prefer --webhook-token-env or --webhook-token-file over inline tokens so secrets do not land in shell history.

Naming a channel recipient

Channel delivery is configured from the Web UI, the RPC API, or the in-agent cron tool (below), and its Recipient is the id the provider uses — a Telegram chat id (1245463966, negative for a group) or @username, a Slack channel id. It is not an AgentOS session key: agent:main:telegram:direct:1245463966 names a conversation inside AgentOS, and Telegram answers chat not found for it.

Both are visible in the UI and the two are easy to confuse, so a save that carries a session key is rejected outright, and the gateway asks the channel whether the chat exists before storing it. Where the recipients are known — Telegram, whose pairing store lists every chat the bot may talk to — the Web UI offers them as a dropdown, with an Enter manually… escape hatch for a group chat that is not in group_chat_ids.

Asking the agent for a specific destination

The in-agent cron tool takes an optional delivery object, so a job created in conversation can announce somewhere other than the chat it was asked for:

{
  "mode": "channel",
  "channel_name": "telegram",
  "channel_id": "-1001234567890",
  "best_effort": false
}

delivery is accepted on add and on update, so an existing job can be moved without being re-created. mode is origin (the calling conversation — identical to omitting delivery on add), channel, or none. channel_id follows the same recipient rules as above and is validated when the job is saved, so a session key or a non-numeric Telegram target fails immediately rather than at the next fire; an empty channel_id uses the channel's configured default chat. channel_name is checked against the configured channels, so a typo cannot be saved — note that it is the entry's name, which is the adapter type unless the operator renamed it. A destination field paired with mode='origin' or mode='none' is rejected rather than quietly falling back to the caller. best_effort applies to any mode.

Unlike the Web UI, the tool does not probe the adapter to confirm the chat exists, and account_id is accepted and binds the job to a specific account instance in multi-account setups. Webhook delivery and failure destinations are refused outright here — they stay CLI/Web/RPC-only, so an agent cannot be talked into POSTing job output at an arbitrary URL.

mode='channel' needs an interactive CLI or Web caller and a sessionTarget other than main. Asked from a chat channel it is refused and the job keeps delivering to that same conversation, so a participant in one room cannot aim scheduled output at another. Note that this gate is the same strength as the one on --elevated and script jobs: callerKind says the request entered through the gateway, not that a human approved it. Inside a Web or CLI session the agent can set it without a confirmation step, so untrusted content the agent reads can in principle steer the destination — the delivery block echoed in the add response is there to be checked.

Inspect and Run Jobs

agentos cron status <job-id>
agentos cron runs <job-id>
agentos cron runs <job-id> --limit 50

Run a job immediately:

agentos cron run <job-id> --yes

cron runs shows each run's Output (the reply, or a script job's stdout) and Delivery (where that output went). Use --json for untruncated output.

Asking the agent what a job did

The in-agent cron tool reads the same history through action="runs", so you can ask in chat — "what did the memory watchdog report today?" — and the model answers from the recorded runs instead of guessing what the schedule produced:

{"action": "runs", "job_id": "<job-id>", "limit": 5}

It returns each run's started_at, success, output, and delivery, plus error on a failure. limit defaults to 5 and is clamped to 20, and output longer than 2000 characters comes back with output_truncated: true — the full text is always available from agentos cron runs <job-id> --json. The action is scoped to the caller's own profile, the same boundary remove and run use.

A script job's stdout can contain whatever the script fetched (an RSS item, an API response), and action="runs" puts that text in the model's context. That is the same content a delivered job already mirrors into the chat, but a job that reports nowhere is now readable too, so treat script output as untrusted input the same way you would any fetched content.

Update or Remove Jobs

agentos cron update <job-id> --enabled
agentos cron update <job-id> --disabled
agentos cron update <job-id> --every 2h
agentos cron remove <job-id> --yes

Primary delivery destinations are not patched in place from the CLI. Remove and re-add a job when the primary channel or webhook destination needs to change.

Editing and cloning a job from chat

The in-agent cron tool edits jobs the same way, so "change that reminder to 7:30" does not have to become a delete-and-recreate — which would reset the job's kind, timezone, tool policy, and delivery target to defaults:

{"action": "get",    "job_id": "<job-id>"}
{"action": "update", "job_id": "<job-id>", "task": "Summarize yesterday's PRs"}
{"action": "update", "job_id": "<job-id>", "schedule": {"kind": "cron", "expr": "30 7 * * 1-5"}}
{"action": "update", "job_id": "<job-id>", "enabled": false}

action="get" returns the full record — kind, timezone, schedule, session target, delivery, tool policy, wake mode, timeout, script fields — which action="list" does not. action="update" patches only the keys it is given and keeps the job's id and everything else.

Deriving a second job from an existing one is clone_from on add. The clone inherits every setting of the source and overrides only what is passed alongside; the source keeps running:

{"action": "add", "clone_from": "<job-id>", "task": "Summarize yesterday's incidents"}

Delivery is one of the settings a clone inherits, so a clone announces wherever its source did unless it is given a delivery of its own — passing one redirects the clone and leaves the source alone. To move the existing job rather than derive a second one, pass delivery to update:

{"action": "update", "job_id": "<job-id>",
 "delivery": {"mode": "channel", "channel_name": "telegram", "channel_id": "-1001234567890"}}

A repoint keeps the job's id, its run history, and its websocket topic, so subscribers watching the job stay attached. The gates are the same ones add applies: mode='channel' needs an interactive CLI or Web caller and a session target other than main, the recipient is validated at save time, and a chat caller cannot repoint a job that already answers somewhere that chat cannot address. Webhook destinations and failure destinations remain CLI/Web/RPC-only.

Both paths keep the operator gates. A job carrying a script or tool_policy.elevated can only be cloned or updated by an interactive CLI or Web caller. So can a job whose delivery points somewhere the calling session cannot post — another channel, or a webhook — because rewriting its text or cloning it would put the caller's words on somebody else's destination. A webhook's URL and token are never disclosed by action="get": it reports the host plus webhook_url_set / webhook_token_set. Cloning a one-shot at job requires an explicit new schedule, and a clone always starts enabled.

Overlapping Runs

A job's next run can come due while its previous run is still going — a long agent turn on a short interval, or a run that hangs until its timeout. --concurrency decides what happens then:

PolicyWhen the next run comes due during a run
forbid (default)Skip it. The next run is scheduled from when the running one finishes.
replaceCancel the running run and start the new one. The cancelled run is kept in cron runs as replaced by a newer run; it is not counted as a failure.
allowStart the new run alongside. The newest run owns the job's schedule and counters; the earlier one is kept in run history only. Runs still count against the scheduler's concurrent-run limit.
agentos cron add --every 5m --job-kind agent_turn \
  --text "Check the deploy queue" --concurrency replace
agentos cron update <job-id> --concurrency allow

replace can only cancel a run the scheduler itself started; a run started by agentos cron run is left to finish, but its result no longer updates the job. One-shot --at jobs have no next run, so the policy never applies to them.

Job Health

agentos cron list --json (the cron.list RPC) and cron status report each job's concurrency and a health block:

"health": {"consecutive_failures": 3, "last_error": "Timeout after 600.0s", "degraded": true}

consecutive_failures is the job's current failure streak; one successful run resets it to 0. last_error is the error of the most recent finished run and is null after a success — a run in progress does not clear it, so a degraded job keeps showing why. degraded turns on at 3 consecutive failures. A recurring job is marked failed and stops after 5, and an authentication-class error (401/403, invalid key) disables it on the first failure.

A WebSocket client subscribed to a job (cron:<id>, or cron:*) gets cron.run.finished once the run is on record: the run's history entry and the job's new health are already saved, so a re-read agrees with it. The event carries runId, status (ok/error), error, durationMs, the job's health, lastStatus, nextRun, and the job as cron.list renders it (job), so no re-read is needed. For a one-shot job its run deleted, jobDeleted is true and health is null.

Sleep, Restarts, and Clock Changes

The scheduler plans its next wake against both the wall clock and the system's monotonic clock and wakes at whichever says the time has come first, re-checking at least once a minute. Whether a job is due is always decided by the wall clock, because schedules are wall-clock times.

  • Laptop sleep. The monotonic clock stops while the machine sleeps. On the first wake after the lid opens the scheduler sees that the wall clock moved on and runs every job that came due in the meantime — once each, however many runs were missed (a five-minute job asleep for an hour runs once, not twelve times). The gateway also notices the thaw on its own maintenance tick and wakes the scheduler at once.
  • Clock set back (an NTP correction, a manual change). Nothing fires early and nothing fires twice: a run's next slot is always computed after the moment that run started, so a job never repeats the slot it just ran.
  • Gateway restart. Jobs missed while the gateway was down are caught up at boot: at most 5, staggered over 10 seconds; any further missed recurring jobs skip ahead to their next slot. Missed agent jobs (an agent turn, or a main session system event) wait 2 minutes after boot so they do not compete with channel start-up for the model; reminders and script jobs run straight away. The wait shows as the job's next run time, so agentos cron list is accurate meanwhile, and a crash during the wait does not lose the job.

Change the post-boot wait for agent jobs (seconds; 0 runs them at boot like every other job), then restart the gateway:

agentos config set scheduler.startup_agent_delay_seconds 300
[scheduler]
startup_agent_delay_seconds = 300

The gateway log records scheduler_wake_gap (a sleep or a clock moved forward), scheduler_clock_back, and scheduler_late_wake (the scheduler woke more than twice as late as planned) when they happen.

  • Safe mode. A gateway that crashed three times in five minutes boots in safe mode and does not start the scheduler: no job runs on its own until safe mode clears (after five quiet minutes, or agentos channels start --yes), and the startup catch-up runs then. agentos cron run <id> still works meanwhile, except for a job the crash left marked running. See Gateway.

Automation From Outside

Something outside AgentOS — CI, a repository webhook, a no-code workflow — can start agent work without a chat channel through the inbound webhooks:

curl -X POST -H "Authorization: Bearer $AGENTOS_HOOKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Nightly build failed: summarize the log", "idempotency_key": "build-4211"}' \
  http://127.0.0.1:18791/api/v1/hooks/agent
  • /api/v1/hooks/agent enqueues the message into agent:main:hook:agent (or another agent:<agent>:hook:... key you pass as session_key).
  • /api/v1/hooks/wake asks the heartbeat loop to run its next tick now (a disabled heartbeat or quiet hours still skip it).
  • /api/v1/hooks/<name> maps any JSON body to an agent, a session and a message template set in [hooks.routes.<name>] — point a repository's webhook straight at it.

They use their own [hooks] token, never the gateway token. Retried deliveries are deduplicated by idempotency_key (or the Idempotency-Key header) for five minutes; each hook is limited to rate_limit_per_minute calls and max_sessions_per_hook sessions per hour; reusing an idempotency key for a different body is 409. Setup: Configuration → Inbound webhooks; responses: HTTP API → Inbound webhooks.

Troubleshooting

Check the gateway and job state:

agentos gateway status
agentos cron list
agentos cron status <job-id>
agentos cron runs <job-id>

If a job posts to a channel, also check:

agentos channels status

A script job that appears to do nothing is usually working as designed: empty stdout, or a final {"wakeAgent": false} line, means silence. agentos cron runs <job-id> distinguishes the two — a silent run is recorded with a silent: … summary (followed by whatever the script printed above its gate, which agentos cron output <job-id> shows in full), while a broken script is recorded as a failure with the exit code and stderr.

Read next: