# Running cron jobs

URL: https://docs.vaultpanel.net/guides/backups-and-automation/cron-jobs

> Run commands on a schedule as a website's or app's own Linux user, in the server's time zone, with the output of every run kept in the panel.

Cron jobs run commands on a schedule: clear a cache, send a report, run a framework's scheduler. Each
job runs as the website's or app's own Linux user, never as root, and every run's result and output
come back to the panel.

## How cron jobs run

The agent keeps each job's settings in a root-only file and writes one line per job to
`/etc/cron.d/vaultpanel`. That line runs the agent with the job's id, never your commands
themselves. When the job is due, the agent runs the saved commands, one after another and without a
shell, as the site's or app's user, starting in its home folder.

Because the server's own cron daemon starts the jobs, they keep running while the panel is down. The
agent reports each run with its next request to the panel.

The server needs the cron daemon. If it is missing, install it from the **Scheduler** card on the
server's page; until then, a job is saved but does not run on its schedule.

## Create a cron job

Go to **Cron Jobs** and click **New cron job**, or use the **Cron** tab of a website or app.

| Field | What it does |
| --- | --- |
| **Runs as** | The website or app whose Linux user runs the job. |
| **Name** | Up to 100 characters, such as `Clear the cache`. |
| **Schedule** | When it runs, in the server's time zone. See [Schedules](https://docs.vaultpanel.net/guides/backups-and-automation/cron-jobs#schedules). |
| **Commands** | One command per line, run in order, up to 10 lines. A failing command stops the run. |
| **Run in folder** | A folder inside the site's or app's home to start in, such as `current` for an app or `public` for a site. Empty for the home folder itself. |
| **Stop after** | How long a run may take before it is stopped: 1, 5, 15 or 30 minutes, or 1, 3, 6 or 24 hours. Default 1 hour. |
| **Load the app's environment variables** | Apps only. The run gets the variables from the app's **Environment** tab, as the app itself gets them. |
| **Run on the schedule** | Untick to pause the job. A paused job can still be run by hand. |

Commands run without a shell, like an app's commands: pipes, redirects, `;` and `&&` are not
supported. Put anything more complex in a script and run the script.

```text
php artisan schedule:run
```

## Schedules

Cron jobs and backup schedules use the same five-field cron expressions:

```text
┌─ minute (0-59)
│ ┌─ hour (0-23)
│ │ ┌─ day of month (1-31)
│ │ │ ┌─ month (1-12 or JAN-DEC)
│ │ │ │ ┌─ day of week (0-7 or SUN-SAT; 0 and 7 are Sunday)
│ │ │ │ │
0 3 * * *
```

Each field accepts `*`, lists (`1,15`), ranges (`1-5`), steps (`*/10`, `0-30/5`) and names (`JAN`,
`MON`). A start without a range, such as `5/10`, is refused because cron versions read it
differently: write `5-59/10`. As in Vixie cron, when both day fields are restricted, a day matches
either of them.

These shortcuts also work:

| Shortcut | Means |
| --- | --- |
| `@hourly` | `0 * * * *` |
| `@daily`, `@midnight` | `0 0 * * *` |
| `@weekly` | `0 0 * * 0` |
| `@monthly` | `0 0 1 * *` |
| `@yearly`, `@annually` | `0 0 1 1 *` |

The form also offers common schedules, such as **Every 5 minutes** (`*/5 * * * *`) and
**Every day at 03:00** (`0 3 * * *`), and shows the next run time.

## Run now

Click **Run now** to run a job right away. Its result comes back with the job, like a scheduled run.

## Runs and output

Each job keeps its last 50 runs, with up to 16 KB of output each. Open a job's runs to see when each
started, how long it took, its exit code and its output.

| Status | Meaning |
| --- | --- |
| Succeeded | Every command exited with 0. |
| Failed | A command failed, which stopped the run. |
| Timed out | The run took longer than **Stop after**. |
| Skipped (still running) | The previous run had not finished, so this one did not start. |

A failed or timed-out run sends the webhook event `cron.failed`. See
[Webhook notifications](https://docs.vaultpanel.net/guides/backups-and-automation/webhooks).

## Delete a cron job

Deleting a job removes it from the server, so it stops running. Its run history is deleted too.

## Permissions

| Permission | Allows |
| --- | --- |
| `cron.read` | Seeing cron jobs and their runs. |
| `cron.run` | Running a job now. |
| `cron.manage` | Creating, changing and deleting cron jobs. |

Hosting customers manage the cron jobs of their own websites and apps, within their plan's limit.
