Install

npm install -g @semilayer/runner-cli

Or pull the pre-built Docker image (same bits, node:22-slim base):

docker pull ghcr.io/semilayer/runner:latest

Quickstart

# 1. Mint a runner in the Console (one-time). You get an rk_ token.
# 2. Start the runner. Env vars or flags, either works.
semilayer-runner start \
  --id <runner-id> \
  --token rk_...

The runner opens one outbound WebSocket to wss://runner.semilayer.com/connect and stays idle until a query comes in. Ctrl-C to stop; restart: unless-stopped in Docker or a Deployment replica in Kubernetes for production.

Commands

| Command | What it does | |---|---| | semilayer-runner start | Connect and serve jobs. Accepts --id, --token, --gateway or the matching SEMILAYER_* env vars. | | semilayer-runner status | Print the configured runner + gateway without dialling out. | | semilayer-runner doctor | Check the runner can resolve and reach the gateway. | | semilayer-runner test-source | (Coming soon.) Dry-run a source connection over the gateway. |

Why a runner?

• Zero inbound. Your database never takes a connection from SemiLayer's IPs. The runner dials out.
• Airgap-ready. In runner-local credentials mode, SemiLayer never holds the DB URL at all.
• Redundant by default. Run two (or twenty) with the same assignments. Dedup is handled by an atomic claim on the gateway — no double-execution.
• Drop-in swap. Same APIs, same generated Beam clients, same streaming. Flipping a source from direct to runner dispatch is one checkbox in the Console.

Security

• rk_ tokens are shown once on create; SemiLayer stores only the SHA-256 hash.
• Revoke from the Console → the next frame on the open socket is refused (~25s heartbeat cadence).
• WebSocket uses TLS 1.3; runners validate the gateway certificate before sending the token.

Full security posture at semilayer.dev/runners/security.

Docs

• Overview
• Install
• Source assignments
• Multiple runners
• Airgap mode
• Troubleshooting

License

MIT