Cron jobs

Run a Hangar service on a cron schedule instead of keeping it up, for reports, cleanups and syncs, billed only while each run lasts.

Updated

Markdown

A cron job is a service that runs on a schedule instead of staying up: a report every morning, a cleanup every hour, a sync with another system every fifteen minutes. When the schedule is due, Hangar starts the service from its last deploy, runs its start command, and removes the container once the command exits.

It is the same model as Railway's cron schedules. The job is an ordinary service: it builds from your repository, has its own variables and reaches your databases on the private network.

Set up a job#

  1. Create a service for the job, from the repository that has its code. It can be the same repository as your app, with another start command.
  2. In the service's Settings → Runtime, set the start command to what the job runs, such as node scripts/report.js or python manage.py clearsessions.
  3. In Cron schedule, on the same page, write the schedule, such as 0 3 * * * for every day at 03:00, or pick one of the shortcuts. The card shows the next three runs in your time.
  4. Deploy the service once. From then on, every deploy builds the image the runs start from, and nothing stays up between runs.

To turn a job back into a service that stays up, clear the schedule and deploy again.

Schedules#

A schedule is a standard cron expression with five fields: minute, hour, day of the month, month and day of the week.

ScheduleRuns
*/15 * * * *Every 15 minutes
0 * * * *At the start of every hour
0 3 * * *Every day at 03:00
0 9 * * 1-5Weekdays at 09:00
0 0 1 * *On the first day of every month, at midnight

A job runs at most once every five minutes. Schedules are read in UTC; under Advanced, pick another time zone, such as America/Sao_Paulo, so 09:00 stays 09:00 for your team.

How a run works#

Each run starts a new container from the image of the service's last successful deploy, with the service's variables and private network, and runs its start command. The run succeeds when the command exits with code 0.

  • Time limit. A run has 60 minutes to finish, or what you set under Advanced, up to 12 hours. A run still going at the limit is stopped and shows as timed out.
  • No overlap. If the previous run is still going when the next one is due, the next one is skipped.
  • No address or volume. A job only runs when it is due, so it has no domain, and it cannot have a volume. Keep what it produces in a database or in object storage.
  • Paused projects. While a service is paused, for example by a spending limit, its scheduled runs are skipped.

Runs and logs#

The service's Runs tab lists every run with its status, how long it took, whether the schedule or a person started it, its exit code and the last 32 KB of what it printed. Run now starts a run right away, which is the quickest way to check a new job.

Billing#

A job is billed for the CPU and memory its runs use, while they run, at the same rates as any other service. A job that runs for two minutes a day costs two minutes a day.

From an AI agent or hangar.yaml#

An agent connected through MCP sets the schedule with configure_service (cronSchedule, cronTimezone and cronTimeoutMinutes), follows the runs with list_cron_runs and starts one with run_cron_now. In a hangar.yaml, give the service a cron key:

YAML
version: 1
services:
  report:
    start: node scripts/report.js
    cron: "0 3 * * *"

Frequently asked questions

Does a cron job on Hangar keep a container running?
No. When the schedule is due, Hangar starts a container from the service's last successful deploy, runs its start command and removes the container when the command exits. Nothing runs between runs, and you pay only for the time a run takes.
What happens if a run is still going when the next one is due?
The next one is skipped, and it shows in the history as skipped. Runs of the same service never overlap.
Can I run a cron job by hand to test it?
Yes. The Runs tab has a Run now button, and an AI agent can do the same with the run_cron_now tool.