AgentOS markAgentOS
Install AgentOS

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

Add an Interval Job

Run a prompt every hour:

agentos cron add \
  --every 1h \
  --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" \
  --text "Prepare a short morning brief" \
  --name weekday-morning-brief

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

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

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.

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

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.

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

Read next: