Scheduled jobs

A scheduled job is code that starts on a timer, completes a defined piece of work, and exits. Tokay handles the schedule, keeps the output of each run, and emails you when it keeps failing.

Last updated

AI agent? Start with llms.txt.

A normal script is enough. Code that runs with node report.js or python sync.py can run as a scheduled job without a scheduling library.

Set the schedule in ordinary language

Enter a schedule such as “Every day at 9am,” “Every 15 minutes,” or “The first of the month.” Choose the timezone, then check the next three run times shown by Tokay.

The schedule can be changed from the Service page or Settings. The Events tab records schedule changes so an unexpected run time can be traced later.

Test the deployed job with Run now

Run now starts the job immediately without changing the schedule. Output streams into the page while the command runs, which lets you verify code, credentials, and database access before waiting for the next scheduled time.

Each run has its own record

The Logs tab lists scheduled and manual runs with their start time, duration, output, and result.

  • Success means the command exited cleanly.
  • Your script encountered an error means it exited with a failure and the output contains the application error.
  • Ran out of memory means the process exceeded the memory available on the Workspace server.
  • Killed / Timed out means the run ended without an exit code, such as when it ran past its one hour limit.
  • Stopped for a pause or maintenance, Stopped to restart the workspace and Stopped with the workspace mean Tokay stopped the run before it finished: the job was paused or deleted, a database it uses was restored, or the Workspace server restarted, moved, changed size or stopped.

A run's output, up to its last 1 MB, stays on your Workspace server with the job's data, so it counts toward your disk and is part of your backups. Tokay keeps the full output of the latest 500 runs for each job. While the server is stopped, the list shows a short preview of each run, and the full output returns when it runs again. See Logs and debugging.

Alerts tell you when a job keeps failing

When a job has been failing for five minutes, each Owner of the Workspace gets an email that links to the job. A job that runs less often than every five minutes alerts on its first failed run, and one that runs more often gets the chance to succeed first. A run fails when it exits with any code other than 0, can't start, or ends without an exit code. A run Tokay stopped on purpose doesn't count. A failed Run now doesn't count, so testing never sends an alert. A successful one does count. Once you've proven a fix by hand, you hear the job works again without waiting for its next scheduled run.

A recovery email follows about ten minutes after a run succeeds, as long as the next runs keep succeeding. It says when the job started and stopped failing. Tokay doesn't repeat the alert while the job keeps failing. See Logs and debugging for the full timing.

To hear about something only your code can check, such as a stale import or an API that stopped answering, write the check as a scheduled job that exits with an error when it finds the problem. Give its network calls a short timeout. A run that hangs keeps going until its one hour limit, and Tokay skips the runs due meanwhile, so a check that hangs takes about an hour to reach your inbox. With a timeout, a failing check emails you within about 10 minutes.

A scheduled job should finish

A process that should wait forever for more work is a background worker, not a scheduled job. A job that writes state needed by the next run should use /tokay/data or another persistent directory. See Files and persistent storage.

A deploy never interrupts a run

Deploying new code, changing a Config or Secret value, or editing the schedule applies from the next run. A run already in progress finishes on the version it started with. Each run starts fresh in its own container, so nothing is left over from the run before.

When a run is due while the previous one is still going, Tokay skips it, so two scheduled runs of the same job never overlap. Run now starts even while a scheduled run is going.

Pausing or deleting the job stops a run in progress, and so does restoring a database it uses or stopping, restarting, moving or resizing the Workspace server. Its process receives SIGTERM and has 30 seconds to finish or save its work before it is killed.