Scheduled tasks

Pier lets you run shell commands on your servers — either on demand or on a cron schedule — and stores reusable commands as templates. The same scheduler that fires these tasks also drives backups and Docker cleanup.

Task templates

A template is a saved shell command plus defaults: a name, an optional description, a default timeout and a default environment map. Templates are the reusable building block — pick one, choose a server, and run it.

Ad-hoc runs

You can start a run two ways: from a template, or with an inline one-off command. If you supply both, the inline command wins. Each run targets one server, takes an optional environment override, and a timeout (default 1800 seconds, clamped between 1 second and 24 hours).

The command runs on the target server’s pier-agent, and Pier polls the agent roughly once a second to mirror stdout, stderr and status back into the run record — so the UI shows a near-live log tail. A run ends in one of these terminal states:

Status	Meaning
success / failed	Agent finished; see exit code
cancelled	You cancelled it (agent is told to stop)
timeout	Exceeded the run’s timeout
unreachable	Agent couldn’t be contacted

Tasks run through pier-agent. The local server and peer-type servers don’t run shell tasks this way.

Schedules

A schedule attaches a cron expression and timezone to an action. Three action types exist:

Action	What it does
task	Runs a task template on a chosen server
backup	Fires a backup schedule
cleanup	Runs the Docker cleanup pipeline

Backup and cleanup schedules are managed from their own screens but appear here in the unified Schedules list, so you have one place to see what runs when. Each schedule keeps a history of its recent runs, and you can enable, disable or run one immediately.

The unified scheduler

A single scheduler ticks every 60 seconds and fires any schedule whose next run time has passed. It is deliberately conservative about overlap and missed runs:

• No double-firing. If a schedule’s previous run is still in flight, the new tick records a skipped run instead of starting a second one.
• No replay. A long downtime simply skips the runs that would have happened; next_run_at is recomputed forward, never backfilled.

Cron format and validation

Pier accepts the conventional 5-field cron format (m h dom mon dow) as well as the common shortcuts @hourly, @daily, @weekly, @monthly and @yearly. Expressions are validated when you create or edit a schedule — an invalid one is rejected with the parser’s error. A validate endpoint also previews the next several fire times for a given expression and timezone, so you can confirm a schedule does what you expect before saving it.

Next steps

• Backups — the backup action the scheduler fires.
• System maintenance — the cleanup action and its cadence.
• Alerts & notifications — get told when a scheduled run fails.