Install a runner

Two paths — Docker for production, the npm CLI for development or custom integration. Both run the same @semilayer/runner runtime.

Create a runner record

Open Console → Runners and click Add runner. Give it a name (e.g. primary-prod) and pick a deployment type:

Customer — you're hosting it. Default for most.
SaaS — SemiLayer-hosted on your behalf (rare; not exposed for customer self-service yet).

You'll get back two values, shown together as a copy-paste env block:

SEMILAYER_RUNNER_ID=<uuid>
SEMILAYER_RUNNER_TOKEN=rk_...

Copy both now — the token is shown exactly once, and SemiLayer only stores its hash. The ID is the runner's UUID (not its name); the gateway uses it as the registry key.

You can re-look-up the ID anytime with semilayer runners list (the ID column) — the token cannot be recovered, only re-minted.

Run the container

docker run --rm \
  -e SEMILAYER_RUNNER_ID=<runner-uuid> \
  -e SEMILAYER_RUNNER_TOKEN=rk_... \
  ghcr.io/semilayer/runner:latest

SEMILAYER_RUNNER_ID is the runner's UUID — the value semilayer runners create prints in the env block, also visible as the ID column in semilayer runners list. The runner name (e.g. primary-prod) also works as a convenience, but the UUID is the canonical form.

Published at ghcr.io/semilayer/runner — public. Pin to a specific version or a <major>.<minor> tag in production (see the package page for all tags).

The runner connects out, registers its session, and then idles waiting for jobs. Safe to run under docker-compose restart: unless-stopped or a Kubernetes Deployment with replicas: 1+.

Assign sources

Back in the Console, open the runner's detail view and tick the sources it should serve. You can always change this later — the runner picks up the new assignment set on its next handshake.

Confirm it connected

The runner row in Console turns Online (green pill) within a few seconds. The runner's stdout prints connected, awaiting jobs.

If not, jump to Troubleshooting.

ℹ️

The token never leaves your machine. The runner presents it over a TLS-encrypted WebSocket handshake; the gateway verifies it against the hash stored at create time. We never log the plaintext, and rotating it from the Console kills the open session on the next frame.