Early access is open. Stagd is free during the beta. Sign up
Guides

Connect compute

Give Stagd access to the compute account your previews run on, and choose the default.

Previews run in your own compute account. Stagd stores the credentials it needs, encrypted, and only uses them to start, sleep and tear down previews.

See what you can connect

stagd compute providers

Namespace, a Kubernetes cluster (beta) or a Docker host (beta). Each says what it can do: whether previews sleep, whether it builds images, and where it runs them. Compute providers compares them.

Connect

stagd compute connect namespace --name namespace-eu

The CLI asks for each value the provider needs; secrets aren’t shown as you type. Stagd checks them with the provider and only saves them if they work.

In a script, pass values with --value. Read secrets from stdin so they don’t end up in your shell history:

echo "$NAMESPACE_TOKEN" | stagd compute connect namespace --name namespace-eu --value token=@- --value region=eu

Namespace

Stagd needs a workspace token from Namespace: one you can revoke, allowed to run preview instances and nothing else. Make it with Namespace’s CLI, nsc, signed in to the workspace your previews should run in (nsc login; nsc workspace describe says which one you’re in):

nsc token create --name stagd --expires_in 8760h \
  --grant '{"resource_type":"instance","resource_id":"*","actions":["create","get","list","wait","exec","refresh","suspend","resume","destroy"]}' \
  --grant '{"resource_type":"instance/ingress","resource_id":"*","actions":["register","list"]}' \
  --grant '{"resource_type":"ingress","resource_id":"*","actions":["access"]}' \
  --output json

It prints the token once, as JSON: the token is the value of bearer_token, a single long word. Give Stagd only that, when you connect Namespace in Settings → Compute or with stagd compute connect namespace, which asks for it without showing it.

To hand it straight to Stagd without it touching your screen or shell history, pipe it through jq:

nsc token create --name stagd --expires_in 8760h \
  --grant '{"resource_type":"instance","resource_id":"*","actions":["create","get","list","wait","exec","refresh","suspend","resume","destroy"]}' \
  --grant '{"resource_type":"instance/ingress","resource_id":"*","actions":["register","list"]}' \
  --grant '{"resource_type":"ingress","resource_id":"*","actions":["access"]}' \
  --output json | jq -r .bearer_token \
  | stagd compute connect namespace --name namespace-eu --value token=@- --value region=eu

Either way, Stagd checks that the token has each grant before saving it, and says which are missing. A token pasted with the JSON around it is refused, saying so.

What each grant is for

Grant Why Stagd needs it
instance: create, get, list, wait, exec, destroy Start a preview’s instance, run its build and services there, and tear it down
instance: refresh Deploy a new commit onto the preview’s instance and move its deadline, so the preview keeps its data and build cache. Without it, every deploy gets a new instance, and the preview’s database starts over
instance: suspend, resume Put an idle preview to sleep, and wake it when someone opens it
instance/ingress: register, list Give each of the preview’s URLs a way in
ingress: access Reach those URLs, to check the preview is up

Nothing else: the token can’t reach your workspace’s other resources, its other tokens or its billing.

Check it

nsc token list shows each token’s grants and when it expires. stagd compute test checks that Stagd can still use it:

nsc token list
stagd compute test namespace

Stagd’s check (stagd compute test namespace, or Test in Settings → Compute) tries each grant, and a connection whose token is missing one shows on Home with what it can’t do. A preview’s events say so too: “On a new instance: the workspace token isn’t allowed to extend instances” means refresh is missing.

Renew, replace and revoke it

The token lasts a year (8760h). Before it runs out, extend it, using the ID that nsc token list shows:

nsc token refresh --token_id tok_… --minimum_duration 8760h

A token’s grants can’t be changed. To add one, such as refresh for a token made before it was in this guide, replace the token: make a new one with the command above, give it to Stagd (it’s checked before it’s saved), then revoke the old one, using the ID nsc token list shows:

nsc token create … --output json | jq -r .bearer_token | stagd compute update namespace --value token=@-
nsc token revoke --token_id tok_…

Revoking the token cuts Stagd off from the workspace at once. Previews already running keep running until their deadline, but Stagd can’t deploy, wake or tear them down.

Kubernetes and Docker hosts

Neither needs to be reachable from the internet: stagd relay runs next to them and connects out to Stagd. Connecting prints how to start the relay.

For a cluster, apply its install with kubectl; --wait waits for the relay to connect:

stagd compute connect kubernetes --name cluster
stagd compute install cluster --wait | kubectl apply -f -

For a Docker host, run this on the host itself, which starts the relay there and waits for it; or pass --print for the docker run commands to run on another machine:

stagd compute connect docker --name build-box --run

The relay runs as root, with the host’s Docker socket mounted, on a Docker network of its own (stagd-relay): root is what can open the socket, and it joins each preview’s network to reach its services. Whoever reaches the Docker API controls the host, so use a host meant for previews, not one that runs anything else. stagd relay --help shows the commands, and --print gives the exact ones for your connection: with a Cloudflare Tunnel, cloudflared runs beside the relay on the same network.

Stagd checks the connection once the relay is up. For a cluster, run install again to update it (a newer relay, or after changing the connection’s settings): while the relay is connected it keeps its token, and the cluster’s stagd-relay secret stays as it is. --new-token gives the relay a new token and cuts off the old one; so does install on a Docker host, every time. For Kubernetes, choose whether images are built in the cluster (Stagd’s BuildKit and registry are installed with the relay) or elsewhere, with a registry of yours to push them to.

Several connections

Your first connection becomes the default, where new previews run. Add more and switch between them:

stagd compute list
stagd compute default namespace-eu

Check and remove

stagd compute test namespace-eu
stagd compute delete namespace-eu

test checks the credentials again, for example after you rotate a token. delete makes Stagd forget the connection and its credentials.

How credentials are kept Secret values are encrypted before they’re stored, and each one only opens for the connection it belongs to. The API never returns them.

For language models and agents: this page as Markdown, or every page through llms.txt.