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 an rk_ token. Copy it now — it's shown exactly once, and SemiLayer only stores its hash.

Run the container

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

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.