Deploying

#The command

scafo deploy ./my-app --remote prod
scafo deploy ./my-app --name shop --remote prod
scafo deploy ./my-app --name shop --env preview --remote prod

With neither --node nor a resolvable remote, the command fails with invalid-input ("No node to deploy to").

#Which application a deploy lands in

Without --name, the CLI reads name out of the project directory's wrangler.jsonc, then wrangler.json. It is read only: nothing writes that file back, and the name it carries reaches Celld exactly as written. A directory with no config, or one whose name is missing, blank or not an application name, is refused with invalid-input telling you to pass --name.

--env appends to the name: --name shop --env preview deploys into the application shop-preview, exactly as --name shop-preview would. The node never sees an environment.

#What is packed

The whole directory is streamed into a file-backed tar + zstd artifact — no exclusion list — and sent as the raw request body of POST /v1/applications/<name>/deploys with content-type: application/octet-stream and the metadata in an x-scafo-deploy header (bounded to 8 KiB).

The artifact must carry a runtime config named wrangler.jsonc or wrangler.json at its root; one that carries neither is refused with invalid-input. The node never parses or rewrites that file: it locates it and hands it to Celld exactly as it arrived, so what the runtime reads is byte for byte what was uploaded. The name Celld sees is whatever the config itself says; --name and --env choose the Scafo application and change nothing in the file.

The node unpacks the artifact before it publishes, and refuses with invalid-input a tar compressed twice, and an entry whose path or link leaves the directory it unpacks into, naming that entry — a relative link that stays inside is fine. An entry the node cannot write on its own disk fails the deploy as internal. Both land on the deploy's record, after the 202.

Anything the flags change is changed by the CLI, before the directory is packed: it reads the config, applies the edit in memory, and puts the result into the archive. The file in the project directory is never written, whatever flags were given. With neither --var nor --no-bundle, the config is uploaded byte for byte.

#Variables

An application's variables live in its own config's vars — that is the runtime's only variable channel. Keep the defaults there, committed with the project:

// wrangler.jsonc
{
  "name": "shop",
  "main": "dist/index.js",
  "compatibility_date": "2025-01-01",
  "vars": {
    "LOG_LEVEL": "info",
    "DATABASE_URL": "postgres://localhost/shop"
  }
}

--var KEY:VALUE overrides one entry for one deploy and leaves every other entry as written:

scafo deploy ./my-app --name shop --var DATABASE_URL:"$DATABASE_URL"

#Bundling

By default the node bundles the Worker entry with esbuild before Celld publishes it. The image sets CELLD_ESBUILD=/usr/local/bin/esbuild; the Linux installer installs esbuild beside the other binaries.

--no-bundle is for an entry that is already a self-contained module — bundled by your own toolchain, with no bare imports. It sets no_bundle: true in the config the archive carries, and Celld then skips esbuild entirely. A config that already declares no_bundle: true needs no flag.

#Python Workers

A Python Worker deploys like any other application: a wrangler.jsonc whose main is a .py file, with its packages vendored into python_modules/ by uv run pywrangler sync on the machine that runs scafo deploy. What such a project must declare, and what Celld supports of it, is Celld's, in its Python Workers documentation.

Deploy from a directory with no .venv* in it. The whole directory is packed, and uv's virtual environments carry symlinks to absolute paths, which a node refuses with invalid-input naming the entry.

The first Python build on each node downloads the Pyodide runtime, about 12 MB, from cdn.jsdelivr.net into Celld's cache under the node's home — in the image, /var/lib/scafo, on the state volume — and later builds reuse it. CELLD_PYTHON_RUNTIME_DIR in the node's own environment puts it elsewhere; see container engine. Serving a Python deployment needs nothing more of a node.

#The intake path

A node with no deploy runner or no artifact stager refuses with capability-missing. Under scafo sail both are always configured.

#Bursts: one publishes, the rest queue

A node publishes one deploy at a time and queues the rest: up to 64 across the node, of which at most 4 may belong to any one application, and the whole queue is bounded independently by the staged bytes those artifacts occupy.

A node whose queue is full answers deploy-overloaded (429) with a retry-after. scafo deploy honours that number, backs off with jitter when the node named none, and keeps coming back until --queue-timeout has passed — printing one line when the waiting starts and one when it is admitted, and nothing in between. The staged artifact is re-sent rather than re-packed.

scafo: the node's deploy queue is full; waiting up to 600s for a place in it (--no-wait fails at once instead)
scafo: admitted after waiting 47s for a place in the node's deploy queue

--no-wait fails on the first refusal, which is what a caller that would rather see the queue than sit in it asks for.

#Watching the deploy

The CLI follows the Location header, polling GET /v1/deploys/<id> every second and printing each state it enters.

A deploy that stops moving for longer than the 90-second liveness window, on a node that has stopped answering, is answered as failed with deploy-timeout by the poll itself — the record is judged at read time, and the coordinator's sweep writes the same judgement down later. Nobody waits for the sweep to hear it.

#Going live

deployed means the deployment is recorded. Serving it follows within seconds:

A process this pass has just started is never asked: it reads the pointer as it boots.

#Admission bounds

These are scheduling bounds, not OS resource admission. Apply host or container CPU, memory, process, filesystem and network limits separately.

Per-application values must not exceed their node-wide counterparts, and staged bytes must be at least artifactBytes.

#Deploying from CI with OIDC

A workload deploys with the token its CI provider issues, without holding an operator key.

# A repository created before 15 July 2026, never renamed or transferred since.
scafo trust set --name shop \
  --issuer https://token.actions.githubusercontent.com \
  --subject 'repo:acme/shop:ref:refs/heads/main'

# One created after that date, or renamed, transferred or opted in since.
scafo trust set --name shop \
  --issuer https://token.actions.githubusercontent.com \
  --subject 'repo:acme@123456/shop@456789:ref:refs/heads/main'

scafo deploy ./dist \
  --name shop \
  --node https://apps.example.com \
  --token "$OIDC_TOKEN"

scafo: Trust policy does not admit this token: "repo:acme@123456/shop@456789:ref:refs/heads/main" is not a trusted subject of "https://token.actions.githubusercontent.com" for "shop"; an admin of this fleet admits exactly that subject with "scafo trust add --name shop --issuer https://token.actions.githubusercontent.com --subject repo:acme@123456/shop@456789:ref:refs/heads/main" [urn:scafo:trust-mismatch]

#Checking the result

# Is the application placed, and is a process running for it?
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7400/v1/state

# Does the node itself answer?
scafo health
curl -s http://127.0.0.1:7400/.well-known/scafo/health

# Does the application answer, on its own host?
curl -s https://shop.apps.example.com/.well-known/celld/health

GET /v1/state shows the node record, the coordinator lease and fence, this node's processes, its placement views, its last reconcile pass, and any applications the coordinator could not place. Operator callers see it filtered to their application scope.