Runner configuration reference

Precedence, lowest to highest: built-in defaults, the YAML config file (--config or SLIPWAY_RUNNER_CONFIG), environment variables, command-line flags. Unknown keys in the YAML file are errors.

Core settings

YAML key	Flag	Environment	Default	Description
`server`	`--server`	`SLIPWAY_RUNNER_SERVER`		Slipway server URL
`token`	`--token`	`SLIPWAY_RUNNER_TOKEN`		Pool registration token. Prefer `--token-file`
`token_file`	`--token-file`	`SLIPWAY_RUNNER_TOKEN_FILE`		File containing the token
`pool`	`--pool`	`SLIPWAY_RUNNER_POOL`		Pool name or id
`name`	`--name`	`SLIPWAY_RUNNER_NAME`	hostname	Runner name
`executor`	`--executor`	`SLIPWAY_RUNNER_EXECUTOR`	`docker`	`docker`, `kubernetes` or `shell`
`labels`	`--labels`	`SLIPWAY_RUNNER_LABELS`		Extra labels, comma separated
`concurrency`	`--concurrency`	`SLIPWAY_RUNNER_CONCURRENCY`	`1`	Max concurrent jobs
`workdir`	`--workdir`	`SLIPWAY_RUNNER_WORKDIR`	OS temp dir	Base directory for job workspaces
`state_file`	`--state-file`	`SLIPWAY_RUNNER_STATE_FILE`		Persists runner id and credential
`ca_file`	`--ca-file`	`SLIPWAY_RUNNER_CA_FILE`		Extra CA bundle for the server connection
`insecure_tls`	`--insecure-tls`	`SLIPWAY_RUNNER_INSECURE_TLS`	`false`	Skip TLS verification. Development only
`transport`	`--transport`	`SLIPWAY_RUNNER_TRANSPORT`	`auto`	How the control stream reaches the server: `websocket` passes through Cloudflare and HTTP/1.1 load balancers; `connect` is the HTTP/2 bidirectional stream; `auto` tries WebSocket and falls back to `connect` on a server without it
`heartbeat_interval`		`SLIPWAY_RUNNER_HEARTBEAT_INTERVAL`	`10s`	Lease renewal cadence
`drain_timeout`	`--drain-timeout`	`SLIPWAY_RUNNER_DRAIN_TIMEOUT`	`10m`	Time to wait for jobs on `SIGTERM`
`log_flush_interval`			`500ms`	How often buffered log lines are shipped
`debug_hold`		`SLIPWAY_RUNNER_DEBUG_HOLD`	`15m`	How long a failed job is held for a debug session

Docker executor

YAML key	Flag / env	Default
`docker.host`	`--docker-host`, `SLIPWAY_RUNNER_DOCKER_HOST`, then `DOCKER_HOST`	engine default socket
`docker.default_image`	`SLIPWAY_RUNNER_DOCKER_IMAGE`	`ubuntu:24.04`
`docker.pull_policy`		`missing` (`always`, `missing`, `never`)
`docker.allow_privileged`		`false`
`docker.allowed_volumes`		none (host path prefixes jobs may bind-mount)
`docker.registries`		none (`server`, `username`, `password` pull credentials)
`docker.selinux_label`		`true`
`docker.network`		engine default

Kubernetes executor

YAML key	Flag / env	Default
`kubernetes.namespace`	`--k8s-namespace`, `SLIPWAY_RUNNER_K8S_NAMESPACE`	`slipway`
`kubernetes.kubeconfig`	`--kubeconfig`, `SLIPWAY_RUNNER_KUBECONFIG`	in-cluster
`kubernetes.context`		current
`kubernetes.service_account`		namespace default
`kubernetes.default_image`		`ubuntu:24.04`
`kubernetes.init_image`		`alpine/git:latest`
`kubernetes.workspace_size`		`10Gi`
`kubernetes.image_pull_secrets`		none
`kubernetes.node_selector`		none
`kubernetes.cpu_request`, `cpu_limit`, `memory_request`, `memory_limit`		cluster defaults
`kubernetes.pod_start_timeout`		`5m`

Shell executor

YAML key	Default
`shell.inherit_env`	`true` (steps inherit the runner’s environment)

Self-update

YAML key	Default
`self_update.check`	`true`
`self_update.channel`	`stable`
`self_update.interval`	`6h`

Example file

server: https://slipway.example.com
token_file: /etc/slipway/token
executor: docker
name: build-01
labels: [linux, x64, docker]
concurrency: 4
workdir: /var/lib/slipway-runner/work
state_file: /var/lib/slipway-runner/state.json
docker:
  host: unix:///run/podman/podman.sock
  pull_policy: always
  allowed_volumes: [/var/cache/ci]
  registries:
    - { server: registry.example.com, username: ci, password: "..." }

Subcommands

Command	Purpose
`slipway runner`	Run the runner
`slipway runner check`	Validate configuration and executor connectivity, then open the control stream to the server with a credential it must refuse (nothing is registered); `--no-server` skips that probe
`slipway runner version`	Print the runner version