Runners

A runner is the agent that executes your jobs. It is the same slipway binary you run as a server, started with the runner subcommand, packaged also as a container image and as deb, rpm and apk packages.

How runners work

Outbound only. A runner dials the Slipway server over HTTPS (a WebSocket by default, or a bidirectional Connect stream) and keeps that connection open. It needs no inbound ports and works behind NAT and corporate firewalls. This is the same model as the Harness delegate and Octopus’s polling Tentacle.
Pools. Runners register into a runner pool using the pool’s registration token. A pool has a kind (self_hosted or hosted), an executor and labels, and is scoped to an org or a project.
Leases. The scheduler assigns a job to a runner with a lease that the runner renews by heartbeat. If the runner disappears, the lease expires and the job becomes runner_lost (and can be retried).
Streams. Logs, step results, artifact uploads and cache transfers flow back to the control plane. Log lines are masked on the runner before they leave it.

runner ──(outbound HTTPS, token or mTLS, bidi stream)──▶ slipway server
   │ executes job in:  shell | docker/podman container | Kubernetes pod
   └ job gets: workspace, env, secrets (masked), OIDC token, cache and artifact access

Executors

Executor	Runs each job in	Good for	Isolation
`shell`	A directory on the runner’s host, as the runner’s user	Bare-metal builds, macOS, tasks that need the host	None beyond the OS user. Use dedicated hosts
`docker`	A container via the Docker or Podman API	Most Linux CI	Container, optional per-job network
`kubernetes`	A pod created in a namespace, then deleted	Elastic CI on a cluster, strong per-job isolation	Pod, namespace, RBAC
hosted	Our managed fleet (Firecracker microVMs planned)	No infrastructure to run	MicroVM

Self-hosted runners cost nothing and are unlimited on every plan. Concurrency limits apply per plan (10, 50, 250, unlimited).

Pages

Page	Covers
Install a runner	Packages, container image, systemd, per executor
Pools and labels	Creating pools, tokens, routing with `runs_on`
Kubernetes	Helm values, RBAC, manifests, pod-per-job
Configuration reference	Flags, environment variables and the YAML file
Security model	Trust boundaries, secrets, isolation, hardening

Quick start

slipway runner pool create linux-docker --executor docker --label linux
slipway runner token linux-docker          # shows the token once
slipway runner --server https://slipway.example.com --token-file /etc/slipway/token --executor docker --labels linux

Then runs_on: [linux] in a job selects it. Check with slipway runner list.