HTTP API

This page lists every HTTP route shippyd serves, who may call it and what it answers. You need it to write a monitoring check, debug a client against a box, or read the box's logs. You never call these routes to use shippy: the shippy client does it for you.

Bodies are JSON unless noted. Digests and keys are 64 hex characters. Terms used below:

• Pre-key: a hash of what a compilation reads that is known before rustc runs (toolchain, arguments, environment, compiled inputs).
• Manifest: the source files and env! variables a compilation read, with their content.
• Action key: the pre-key and a manifest together. A result is stored under it.
• Blob: a file stored under its own BLAKE3 digest.
• Claim: a result an untrusted principal uploaded, seen only by that principal until the box re-runs it.
• Pack: the list of results a whole build used, stored per build id (a name for "a build like this one").

The glossary has more.

A miss, then a hit

A wrapper that misses locally asks twice: lookup for the manifests under its pre-key, each with its result, then blobs/fetch for the outputs it lacks. Machine A's upload is a claim if A's token is untrusted: Machine C only gets it once the box has re-run it, or immediately if A is trusted. See the wire and trust.

Authentication

Every /v1/ route needs Authorization: Bearer <token>. A missing or unknown token gets 401 with WWW-Authenticate: Bearer.

/healthz and /readyz need no token. See token roles.

Client routes

For trusted and untrusted tokens.

Who sees what

• lookup, pack and action answer with the public result of a key, else the caller's own claim, and nothing else. Entries with no such result are left out.
• A blob is served to a principal that sent those bytes itself, or that asks through a result it may see (an output or the recipe of that result). A digest alone is not enough.
• A blob the caller may not read is answered like one the box lacks: no frame, 404, or "missing". So no route says whether someone else's blob is there.

Blob asks

A blob ask in JSON is either a bare digest (a blob the caller sent itself) or an object {"key": <action key>, "blobs": [<digests>]} (blobs that result names). One request may mix both.

Frames

blobs/fetch answers, and blobs/put sends, one stream of frames. Each frame is the blob's 32-byte digest, its length as 8 bytes little-endian, then its bytes. Blobs the box lacks have no frame.

• Send Accept-Encoding: zstd to get the same frames as one zstd stream (Content-Encoding: zstd).
• blobs/put takes Content-Encoding: zstd too. Any other encoding gets 415.
• The box keeps a frame only when its bytes have the digest it names. A bad frame costs only itself; the rest of the request goes on.

Packs

GET /v1/pack/{build_id} answers with an ETag. Send it back as If-None-Match and an unchanged pack is answered 304 with no body, so a rebuild after an edit costs one small request. Every pack answer also carries the X-Shippy-Exec header (below).

Remote execution: POST /v1/exec

The client sends Accept: application/x-shippy-exec and a body of frames: the first holds the request as JSON, the others are inputs the client expects the box to lack. Before anything runs, the box answers with a status:

The stream's records are a heartbeat (every five seconds), events as JSON, and the pieces of each output blob. Without the Accept header the route answers the result as JSON, or 422 with the reason. A declared input that is not in the store, or not readable by this caller, is such a reason ("missing input"), given before the request waits for a slot.

Every answer carries X-Shippy-Exec, a comma-separated list of what the box can do beyond the first version of the route: zstd (the request body may be one zstd stream) and finds (a request that declares a whole package may be answered from a result the box already has). See remote execution.

Worker routes

For worker and trusted-worker tokens only. Any other token gets 401. A worker reads no blob by digest, looks up no key and uploads nothing through the client routes.

A lease the worker lost or that ended gets 410. A completion the box refuses (outputs the recipe does not allow, bytes that are not their digest) gets 422 and the run goes to another worker. See workers.

Probes and metrics

/readyz is ready when the store's directories are there, the tokens file can be used, the last sandbox self-test passed and the box is not shutting down. The self-test compiles a crate at start and every five minutes (lifecycle.selftest_every). A box with exec.local = false has no sandbox to test and counts as passed.

metrics.listen (such as 127.0.0.1:9447) serves /metrics, /healthz and /readyz on a second address without a token. Keep it on loopback.

curl -fsS http://box:7447/healthz
curl -fsS http://box:7447/readyz
curl -fsS -H "Authorization: Bearer $TOKEN" http://box:7447/v1/stats | jq .

GET /v1/stats

One JSON object.

Under exec:

Status codes worth knowing

Errors are a status and one line of plain text. Every answer carries x-request-id; send your own (8 to 64 letters, digits, - or _) to match a client's log line with the box's.

Go deeper

• crates/shippy-core/src/proto.rs: wire types and the route table
• DESIGN.md: "The shared box" and "The wire"
• docs/remote-exec.md: /v1/exec in full
• docs/workers.md: the worker routes
• docs/operations.md: metrics, probes and logs