Upload a static site
Relay serves a site folder at /<node>/<site>/.
To put a site there, upload a tar archive of the folder
to the node. One request, and the site is live — atomically replacing
whatever was there before.
The endpoint
POST /_relay/v1/sites/{site}/deploy
Authorization: Bearer {token}
Content-Type: application/x-tar
The body is the raw tar bytes of the site folder's contents
(not the folder itself). {site} is a lowercase name:
letters, digits, and interior hyphens, 1–63 characters.
Example
tar -C ./site-folder -cf site.tar . curl -X POST \ -H "Authorization: Bearer $RELAY_DEPLOY_TOKEN" \ -H "Content-Type: application/x-tar" \ --data-binary @site.tar \ "https://relay.example.org/_relay/v1/sites/docs/deploy"
The response names where the site is live:
{"site":"docs","files":3,"bytes":5120,"url":"/mynode/docs/"}
Credentials: admin token vs deploy keys
There are two credentials. The admin token is the operator's
master credential — generated into <data>/admin-token
(mode 0600) on first run, or set with
relay node --admin-token. It unlocks the operator
console at /_relay/admin.html, not uploads.
Deploy keys are per-user upload credentials the operator
creates on that console. The console lists each user's keys (grouped
by user) and can reveal and copy a token at any time. Upload with a
deploy key's token as a bearer token — never in a URL, never
committed, never logged.
The key
Relay's permanent identity is an Ed25519 key — the deed to a
name. relay key new generates one. For this MVP the
token is what authorizes uploads; keys and signed deploys arrive
with the control API. See docs/keys.md in the source.
Archive rules
- Relative paths only — no
.., no absolute paths, no symlinks or hard links. - Regular files and directories only.
- At most 65536 files and 256 MiB per upload.
- Every upload is a full replacement — send the whole site each time.
Errors
| code | HTTP | Meaning |
|---|---|---|
bad_token | 401 | missing or wrong token |
bad_name | 400 | the site path segment is invalid |
bad_archive | 400 | not a tar, or an entry breaks the rules |
too_large | 413 | archive over the size cap |
Rollback
Deploys keep the last 10 versions. The operator can roll a site back
to a previous version from the console or with
relay rollback --origin … --site …. The current live
site is snapshotted first, so nothing is lost.
The CLI
The node's own relay binary drives both sides:
relay deploy --origin … --site … ./dist uploads a
folder, and relay rollback --origin … --site … rolls it
back.
For agents
Point your agent at the hosted skill — the same contract as
machine-readable instructions:
./skills/relay-deploy/SKILL.md.