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

# Recipes

> A script you keep, run across the servers you choose.

A recipe is a shell script saved against the organization and run on machines
you pick from a list. Installing a package across the fleet, rotating something,
checking a version on twenty boxes at once.

## Runs as

**Root** — anything on the machine: packages, services, every site on it.

**Site user** — only what the sites can reach, the way a
[deploy script](/sites/deploy-script) runs.

Only these two. An arbitrary username would be a third thing to get wrong at
the moment somebody presses run across a fleet, and every account Shipways puts
on a server is one of these anyway.

## Who may write one, and who may run one

**Writing** a recipe sits with the organization's administrators. It is root
code that other people will run on machines they chose from a list, without
reading it — closer to holding the organization's credentials than to operating
its servers.

**Running** one sits with developers, on the same footing as opening a shell.
Somebody who can open a root shell on a machine can already do anything a
recipe could do to it.

What running adds is **reach** — one press touching a whole fleet — which is
why the panel names the number of machines in the confirmation before it goes.

## Running one

Pick the machines. Only servers Shipways is currently talking to are offered; a
machine whose agent is quiet cannot be sent work.

A run does not stop at its first failure. It goes to every machine you picked
and reports per machine, so a nine-of-ten run and a ten-of-ten one do not look
the same.

Each machine's output is kept and can be opened from the run. A failure opens
itself, because that is the one you came back for.

## Timeout

A recipe is stopped after **600 seconds** on a single machine.

Longer than a [site command](/sites/commands#it-is-bounded), because the reason
to run something on twenty servers at once is usually a package install rather
than a status check — and short enough that a script waiting on a prompt nobody
can answer does not hold a server's queue lane for the afternoon.

Write scripts non-interactively. `apt-get -y`, `DEBIAN_FRONTEND=noninteractive`.

Self-hosted installations can change the limit with `SHIPWAYS_RECIPE_TIMEOUT`.

## History

Runs keep **the script as it ran**, not as the recipe reads now. The two differ
precisely when somebody has been in to fix it, which is when it matters.

Editing a recipe changes what happens next. Removing one keeps everything it
already did.