Glossary
The words you'll meet across these docs, in alphabetical order.
| Term | Meaning |
|---|---|
| Action key | The address of a result: a hash of the pre-key and the manifest. Found when a stored manifest matches your files. More |
| Action result | What an action key maps to: the files the compilation wrote (by digest) and the compiler's messages. |
| Blob | One stored file, named by the BLAKE3 hash of its bytes. A blob can't lie about its content. |
| The box | The shared server, shippyd. It holds the cache, rebuilds claims in a sandbox and can compile for you. More |
| Broker | Connections the shippy front end keeps open to the box and lends to its wrappers, so each crate doesn't connect on its own. |
| Build id | A name for "a build like this one" that leaves out paths and sources: toolchain, Cargo.lock, cargo arguments and key-changing switches. Used to find a pack. More |
| Claim | An upload from an untrusted principal. Private to them until the box's sandbox reproduces it. More |
| Fixed place | Building with the checkout, target directory and cargo home mounted at /shippy/at/..., so paths are the same everywhere. More |
| Front end | The shippy command you type instead of cargo. It starts cargo, prefetches and uploads. |
| Image id | A name for the box's system directories. A result the sandbox made is filed under its key and the image id, so a box with a different system doesn't serve it. |
| Lease | One sandbox run a box hands to a worker machine. More |
| Local store | The cache on your machine, ~/.cache/shippy by default. Same layout as the box's store. |
| Manifest | The source files a compilation opened and the env! variables it read, with their content. Known after rustc runs once. |
| Pack | The list of results a whole build used, kept on the box under its build id so the next machine can fetch them all at once. |
| Pinned | A result tied to one checkout location, because the crate embedded its own directory. Reused only where that root is the same. |
| Pre-key | A hash of everything known before rustc runs: toolchain, arguments, environment and compiled inputs. Leads to manifests. |
| Prefetch | Downloading a whole build's results before cargo starts. |
| Principal | A named user of the box, identified by a token. Each principal has a role. |
| Public result | A result every principal is served: uploaded by a trusted principal, or produced by the box's sandbox. |
| Recipe | A description of one rustc call by content: toolchain, arguments with placeholders for paths, environment, compiled inputs and manifest. |
| Remapping | Telling rustc to record the workspace, target directory and cargo home as /shippy/ws, /shippy/target and /shippy/cargo. |
| Remote execution | Having the box compile what the cache misses, beside your machine or instead of it. More |
| Role | What a token may do: trusted, untrusted, metrics, worker or trusted-worker. |
| Sandbox | The bubblewrap jail where the box runs recipes: no network, read-only inputs, a system call filter and resource limits. |
| Trusted principal | One whose uploads are public as they are. Meant for CI on protected branches. |
| Verification | The box re-running a claim in its sandbox and publishing its own output. |
| Warmer | shippy-warm: builds every new commit of watched branches through shippy, so the box has results before anyone asks. |
| Worker | A machine that runs sandbox runs leased by the box, holding no store of its own. More |
| Wrapper | shippy-rustc: what cargo runs instead of rustc for every crate. Same binary as shippy. |