Docs navigation
Docs / Scheduling

Scheduling

OpenSquilla 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 opensquilla cron command group.

Heartbeat Configuration Compatibility

The configuration-driven heartbeat loop and the main-session cron wake modes now and next-heartbeat remain available. Dream scheduling and connection keepalives are unchanged.

HEARTBEAT.md no longer supplies instructions or scheduling configuration. Its frontmatter, quiet hours, and empty-file suppression are ignored. heartbeat.config_path (also configPath and its environment-variable spellings) remains accepted for configuration round-tripping, but is deprecated and ignored: the referenced path is never read.

Before upgrading, check the effective heartbeat.enabled configuration. If it is true and the old file previously disabled or limited runs, retiring those restrictions can increase execution or change its hours. If only the file enabled heartbeat, it stops running when the configuration is false. The upgrade does not change enabled settings or migrate any tasks into cron. A startup warning is emitted when heartbeat is enabled or the old path setting is supplied. Review the configuration explicitly instead of relying on the old file to suppress execution.

Requirements

Scheduled jobs run through the gateway:

opensquilla gateway run

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

opensquilla gateway start --json
opensquilla gateway status

List Jobs

opensquilla cron list
opensquilla cron list --agent main
opensquilla cron list --json

Add an Interval Job

Run a prompt every hour:

opensquilla 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:

opensquilla 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

opensquilla 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.
mainYou want a system event for the main session.

Example:

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

Delivery

Disable delivery:

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

Deliver through a webhook:

opensquilla cron add \
  --every 1h \
  --text "Post a compact status summary" \
  --webhook-url https://example.com/hooks/opensquilla \
  --webhook-token-env OPENSQUILLA_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

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

Run a job immediately:

opensquilla cron run <job-id> --yes

Update or Remove Jobs

opensquilla cron update <job-id> --enabled
opensquilla cron update <job-id> --disabled
opensquilla cron update <job-id> --every 2h
opensquilla 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:

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

If a job posts to a channel, also check:

opensquilla channels status

Read next:


Docs index · Product guide · Improve this page · Report a docs issue

Edit this page on GitHub OpenSquilla docs · synced from main