Run a command on a schedule

Add a scheduled job that runs a command in the app's image, with its whole environment, on one of its machines.

Last updated 18 November 2026View as Markdown

The job runs /bin/sh -c "<command>" in the app's image, with its whole environment (variables, secrets and database bindings) on one of the app's machines. Replace app-id with the app's id and job-id with the job's id.

Prerequisites

  • An image that contains /bin/sh. You can add a job before the app is deployed; it starts running once the app is deployed and its machine reports in.
  • Permission for deploy:CreateJob on the app; deploy:RunJob to run it now, deploy:DescribeJobs to read its runs, deploy:UpdateJob to change, enable or disable it, deploy:DeleteJob to delete it.
  • In the console, also deploy:DescribeApp to open the app's page (without it the page is not found).

Add the job

  1. Open the app's Scheduled jobs tab, then choose Add job.
  2. For Name, enter nightly-cleanup.
  3. For Schedule, enter 0 3 * * *, or choose a preset. The schedule is stated in words with its next run times.
  4. For Command, enter node bin/cleanup.js.
  5. (Optional) For a compose app, for Service, choose the service whose image and environment the job runs with.
  6. (Optional) For Timeout (minutes), enter a value. The default is 60.
  7. (Optional) Turn on Start even if the previous run is still going (concurrency allow).
  8. Choose Add job. The job is listed with its next run and a switch that enables or disables it.

A second job with the same name is refused with 409 "This app already has a job named "nightly-cleanup"", and a job over the app's job quota with 409 "Quota exceeded: …".

Run now starts a job outside its schedule; the machine picks it up on its next poll. Before any machine of the app has reported in, it is refused with 409 "The app has no machine that has reported in yet. Deploy it first". Every run, with its exit code and the last lines it printed, is listed under the job's runs (View runs), and is a line in the app's activity.

Job settings

Field Rule Default
name lowercase letters, digits and hyphens, at most 63 characters; unique within the app required
schedule five-field cron in UTC: minute hour day-of-month month day-of-week; *, a-b, */n, lists, jan–dec, sun–sat; or @hourly … @yearly required
command run with /bin/sh -c; the image needs a shell required
service compose apps: whose image and environment the job runs with the published service
timeoutSec 10–86400; the run is stopped and recorded as timed_out after this long 3600
concurrency skip: a run due while the previous one is still going is recorded as skipped; allow: it starts anyway skip
enabled a disabled job is not run on schedule; Run now still works true

When day-of-month and day-of-week are both set, a day matching either fires, as in cron: 0 0 1 * 1 runs on the 1st and on every Monday. Only UTC is supported.

What a run sees

The image of the deployment that is live, and the environment as of that deployment: a variable saved without redeploying reaches jobs when it reaches the app. For a compose app the job joins the app's network, so db resolves as it does for the services. A run that is due while the machine is down is not run late. Where the job runs is in What runs on your machines.

Run outcomes

Each run is succeeded (exit 0), failed, timed_out, skipped, or lost (the machine stopped reporting on it, or no machine picked up a run-now within ten minutes). The last 100 lines of output are kept with the run; the newest 500 runs of each job are kept. A failed, timed-out or lost run emails the organization's owners and admins, at most once a day per job while it keeps failing; the first failure after a success is emailed at once.

Result

The job runs on its schedule on one of the app's machines. How many jobs an app may have is a quota; see Quotas.

Did this page help you?