Server configuration

This page lists every setting of shippyd, the server on the box, with its default. Use it when you write shippyd.toml, tune a box, or hand out tokens.

Every setting has three names that mean the same thing: a key in the config file, a SHIPPYD_* variable and a command-line flag. A wrong value is refused the same way wherever it came from, with an error that names where it was, and shippyd does not start.

Quick start

shippyd config print-default > /etc/shippy/shippyd.toml   # every key, its default, its variable
sudoedit /etc/shippy/shippyd.toml
shippyd config check                                       # what a start would find; starts nothing

Where settings come from

1. The file. --config <file>, else SHIPPYD_CONFIG, else /etc/shippy/shippyd.toml when it exists. No file is fine if the required settings come from elsewhere.
2. The environment goes over the file. The systemd unit also reads /etc/shippy/shippyd.env. An empty variable counts as unset.
3. Flags go over both.

A key in the file that is not a setting is an error, so a typo is never silently ignored. A change to the file needs systemctl restart shippyd. Only the tokens file is followed live.

Required settings

shippyd will not start without these three. shippyd config print-default writes them with the values shown.

• listen is an address and a port. Inside a tailnet, use the box's Tailscale address.
• store.path is the store directory. The sandbox's scratch space is inside it, so its inputs are hard links: the filesystem must allow executables (no noexec). A tmpfs keeps the cache in memory.
• tokens.file holds the hashes of accepted tokens. Keep it out of /usr and the toolchains' directories, which the sandbox can read.

All settings

Durations are written like 30s, 15m, 12h, 30d. Sizes like 200GB or 64GiB.

Top level and [store]

See eviction.

[exec]

A claim is a result an untrusted principal uploaded. The box re-runs its recipe (the full description of one rustc call) in a sandbox before anyone else gets it. These settings control those re-runs.

[workers]

How the box treats its worker machines. See workers.

[worker]

Read by shippyd worker alone, on a worker machine. A worker also reads store.path (its cache of inputs and scratch space), exec.timeout, [toolchains], [log], [lifecycle] and [env].

[toolchains]

A claim is re-run with the exact compiler its recipe names. These say which toolchains rustup may install on the box.

[tokens], [log], [metrics], [lifecycle]

The [env] table

Some parts of the server read the environment themselves: the sandbox's limits, remote execution's quotas and build scripts. Put those variables in the file's [env] table. shippyd copies them into its own environment before anything starts, unless the real environment already has them. Only SHIPPYD_* names are allowed.

[env]
SHIPPYD_SANDBOX_MEMORY = "16GiB"
SHIPPYD_EXEC_SLOTS = 48

Sandbox limits

What one sandboxed compilation may use. A run past a limit is ended and its claim stays a claim. Memory and CPU limits need a cgroup per run (the systemd unit's Delegate=yes).

Remote execution

Limits of /v1/exec, the route that compiles a client's cache misses (remote execution). Sizes are bytes.

Build scripts

The box runs build scripts in its sandbox (build scripts). A box with exec.local = false runs none.

Connections

A request's body that stands still for a minute, or comes slower than four kilobytes a second after its first minute of waiting, is given up and its request answered 400.

Token roles

A principal is one named identity (a person, a CI pool, a scraper) with one role. It may have several tokens. Results and claims are kept per principal, so use one principal per person or machine pool.

shippyd token add alice                       # untrusted, the default
shippyd token add ci-main --role trusted
shippyd token add prometheus --role metrics
shippyd token add worker-1 --role worker

--require-trusted-pool on a trusted token has it served only what a trusted principal uploaded or the trusted pool produced.

The tokens file

[[token]]
id = "3f9a1c2e"                 # the first hex digits of the hash; token revoke takes it
principal = "alice"
role = "untrusted"              # trusted, untrusted, metrics, worker or trusted-worker
sha256 = "3f9a1c2e..."
created = "2026-11-13T20:00:00Z"
expires = "2027-02-11T20:00:00Z"  # optional

The file holds only the SHA-256 of each token, so a copy of it lets nobody in. Tokens start with shp_. A running shippyd looks at the file on every request: a new token works and a revoked one is refused from the next request. SIGHUP (systemctl reload shippyd) reads it again anyway. A file that cannot be read or parsed lets nobody in until it is fixed.

Go deeper

• docs/operations.md: configuration, sandbox limits, tokens
• deploy/shippyd.toml: the deployed config file
• docs/remote-exec.md: remote execution limits
• docs/workers.md: workers and their settings
• crates/shippyd/src/config.rs: where every key is defined