---
title: "Scheduled job (cron): the while.sh docs"
url: https://while.sh/en/docs/building-blocks/scheduled-jobs/
updated: 2026-11-09
---

# Scheduled jobs

A command run at a set time: an import every night, a cleanup, a report. Every run is tracked, and your agent is notified of a failure.

> You, to your agent: Run the sales import every day at 6 am.

## What your agent writes

Your agent writes it in while.yaml, at the root of your app:

```yaml titre="while.yaml"
crons:
  - name: cleanup
    title: Nightly cleanup
    schedule: "0 3 * * *"
    command: [node, cleanup.js]
    timezone: Europe/Paris
    timeout_seconds: 600
    retries: 1
    concurrency: forbid
```

## What your app receives

Your app receives these environment variables at every deployment:

| Variable | What it holds |
|---|---|
| `WHILE_CRON` | The job's name. |
| `WHILE_TRIGGER` | How this run was started: scheduled, manual or catch_up. |
| `WHILE_CATCH_UP_START` | The start of the period to catch up. |
| `WHILE_CATCH_UP_END` | Its end. |

## When to use it

For what starts at a fixed time: loading an external API every night, cleaning up, writing a report. Nothing is reserved between two runs, and a run lasts 6 hours at most.

## How it works

A scheduled job runs a command at a fixed time, with a service's image and variables, or with an image built for it. Each run is tracked, and a failure or a missed run wakes the agent.

## What to know

The schedule follows cron syntax, in Paris time by default (timezone). A task succeeds when it exits with code 0, and any other code is a failure. Each run keeps its duration, its exit code, the last lines of its log and the summarized error.

A run that exceeds `timeout_seconds` (600 by default, 6 hours at most) is stopped, and retries restarts it within the same run (0 by default). concurrency decides overlaps: `forbid`, the default, refuses that a run overlaps another, allow permits it, and replace stops the running one. A run started by hand at the moment a scheduled run starts can still overlap it.

Each run knows how it was started: `WHILE_TRIGGER` is scheduled, manual or `catch_up`. A catch-up receives its period in `WHILE_CATCH_UP_START` and `WHILE_CATCH_UP_END`, and the command only processes it. Your agent reruns a task, or catches up a period, with the `run_task` tool.

## Pricing

These prices are the same on every plan, excluding VAT:

| Resource | Price | Details |
|---|---|---|
| CPU and memory | €17 per vCPU·month and €8.50 per GiB·month | apps by usage, caches by reservation |

## Your agent's MCP tools

Your agent handles it with the `list_tasks` and `run_task` tools.

## Guides

- [Run a script on a schedule from your AI agent, with no server](/en/guides/run-cron-job/)