> ## Documentation Index
> Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cron Jobs

> Schedule recurring tasks inside your app's containers.

Cron jobs run shell commands on a schedule inside your service's container image. Declare them in `floo.app.toml` and they are synced on every deploy.

## Declare in config

Add `[cron.<name>]` sections to `floo.app.toml`:

```toml theme={null}
[app]
name = "my-app"

[cron.daily-report]
schedule = "0 9 * * *"                  # 9am UTC daily
command = "python scripts/daily_report.py"
service = "web"                          # which service's image to run in

[cron.cleanup]
schedule = "*/5 * * * *"                 # every 5 minutes
command = "node scripts/cleanup.js"
service = "worker"
timeout = 600                            # max seconds (default 300)

[services.web]
type = "web"
path = "."
port = 3000
ingress = "public"

[services.worker]
type = "worker"
path = "./worker"
ingress = "internal"
```

## Fields

| Field      | Required | Description                                                                                      |
| ---------- | -------- | ------------------------------------------------------------------------------------------------ |
| `schedule` | yes      | Standard cron expression (e.g. `"0 9 * * *"` for 9am daily, `"*/5 * * * *"` for every 5 minutes) |
| `command`  | yes      | Shell command to execute inside the container                                                    |
| `service`  | yes      | Name of the service whose image to run the command in — must match a `[services.*]` entry        |
| `timeout`  | no       | Max execution time in seconds (default: 300)                                                     |

## Deploy and verify

Push to GitHub or run `floo redeploy`. Cron jobs are synced on every deploy — new jobs are created, changed jobs are updated, removed jobs are deleted.

```bash theme={null}
git push origin main && floo deploys watch --app my-app
```

After deploy, verify your jobs:

```bash theme={null}
floo cron list --app my-app
```

## Manually trigger a job

Test a job without waiting for its schedule:

```bash theme={null}
floo cron run daily-report --app my-app
```

## Common schedule expressions

| Expression    | Meaning                            |
| ------------- | ---------------------------------- |
| `* * * * *`   | Every minute                       |
| `*/5 * * * *` | Every 5 minutes                    |
| `0 * * * *`   | Every hour                         |
| `0 9 * * *`   | Daily at 9am UTC                   |
| `0 9 * * 1-5` | Weekdays at 9am UTC                |
| `0 0 * * 0`   | Weekly on Sunday at midnight UTC   |
| `0 0 1 * *`   | Monthly on the 1st at midnight UTC |

## How it works

1. You declare `[cron.<name>]` in `floo.app.toml`
2. The CLI sends cron definitions to the API during deploy
3. The API's `_sync_cron_jobs()` creates, updates, or deletes CronJob records
4. Jobs run inside the specified service's container image with the same environment variables

Cron jobs have access to the same `DATABASE_URL`, `REDIS_URL`, and other env vars as the service they run in.

## Failure handling

Cron jobs **do not retry**. Each scheduled run executes once; if the command exits non-zero or exceeds its `timeout`, that run is marked failed and the next recovery is simply the next scheduled run — there is no automatic retry or backoff.

For runs where a miss matters, make the command idempotent and handle retries inside it, and alert on failure: `floo logs --app my-app --cron <job>` shows the cron output with `[cron:<job>]` attribution, and [agent webhooks](/docs/guides/agent-webhooks) can route repeated failures to your agent or on-call.

## Agent workflow

```bash theme={null}
# List cron jobs (JSON for parsing)
floo cron list --app my-app --json 2>/dev/null | jq '.data.cron_jobs'

# Trigger a job manually
floo cron run daily-report --app my-app --json 2>/dev/null
```

<Card title="CLI Reference" href="/docs/cli/cron">
  See the exact `floo cron list` and `floo cron run` flags, JSON shape, and `--dry-run` behavior.
</Card>