Runner configuration
For complete container and Linux service examples, see Install a runner. The runner takes command-line flags and environment variables; it does not load a runner YAML configuration file.
Start flags
| Flag | Default | Meaning |
|---|---|---|
--server | PYPLINES_SERVER | Required HTTPS server origin, including port if needed |
--enrollment-token-file | PYPLINES_ENROLLMENT_TOKEN_FILE | Enrollment credential file, required until registration is saved |
--name | Empty | Optional display name submitted during registration |
--ca-file | PYPLINES_CA_FILE | PEM CA bundle added to system trust for HTTPS and NATS |
--max-concurrent | 1 | Maximum workload-container concurrency, from 1 to 64 |
--ephemeral | false | Retire the identity after successfully draining on shutdown |
Explicit flags override their corresponding environment defaults. --server must be an HTTPS origin such as https://pyplines.example.com:8080, without credentials, query parameters, fragments, or an API path prefix. Registration redirects are rejected.
The runner obtains the NATS address from the server after admission. There is no runner flag that overrides a misconfigured server --nats-url. Both endpoints must be reachable and trusted. The runner does not serve an inbound management port.
State and work environment variables
| Variable | Default | Meaning |
|---|---|---|
PYPLINES_RUNNER_STATE | /var/lib/pyplines-runner | Persistent identity and invocation work directory visible to the runner |
PYPLINES_WORK_VOLUME | pyplines-work | Docker named volume from which Action input/output subdirectories are mounted |
PYPLINES_ACTION_NETWORK | Empty | Docker network permitted for Actions that require network access |
These are separate settings with a required relationship: the state directory and work volume must expose the same files. In a container, mount the named work volume at the state path. For a native Linux process, create a Docker local-driver volume backed by that host directory, as shown in the installation guide.
Actions mount only their invocation's input/output subdirectories, not the whole runner state. Docker must support named-volume subdirectory mounts; see Docker volume documentation.
The work directory includes identity.json, its private authentication material, runner.lock, and invocation directories. Keep it private and persistent. A filesystem lock prevents two processes from owning the same state directory. Do not clone an identity into another active runner or delete it to recover unfinished work.
Use a distinct work volume for each runner on a host. For the native service, UMask=0022 preserves read access to ordinary staged inputs for Action UID 65532; identity files are explicitly written as 0600. The runner must be able to assign output ownership to UID/GID 65532, which is why the documented service runs as root.
Docker and registry access
The runner uses its provisioned Docker client environment, including DOCKER_HOST and Docker TLS settings when configured. It does not select a saved interactive Docker context. The documented setup explicitly uses DOCKER_HOST=unix:///var/run/docker.sock on the local host.
The runner must see the filesystem used by its Docker work volume. Pointing DOCKER_HOST at a different machine does not transfer staged input/output files and is not the deployment pattern covered here.
Docker socket access grants control over that daemon. It belongs to the runner service, not to the server or workload containers. Action image read credentials are delivered through the platform's registry configuration; a host docker login used to pull the runner image is a separate concern.
For a network-enabled Action, the Environment's network must equal PYPLINES_ACTION_NETWORK, and the network must exist on the selected runner's Docker host. Actions that do not require networking run with network mode none. Do not use a network name that exists only on another host.
Enrollment and restart
Before registration completes, the runner needs the enrollment file and persists enough local identity to retry an interrupted registration. Once identity.json contains the registered runner ID, restarts reuse it and no longer read the enrollment token. The configured server origin must match the saved origin.
Admission is an administrator decision. A process waiting for approval is not yet execution capacity. After approval, inspect last_seen, admission, pool, and draining status with pyplines --json runner list, then run the verification workflow.
SIGTERM/SIGINT stops acceptance of new work and starts a bounded reconciliation window of about 30 seconds. If it expires, state remains for later reconciliation; shutdown does not prove every external effect has settled. --ephemeral retirement occurs only once draining and reconciliation complete.
An administrative drain persists on the server. The current server has no resume transition; restarting the process does not undo that drain. The installation examples use Restart=on-failure/restart: on-failure so a clean drain exit is respected. See runner management before replacing identities.
Inspect an installed runner
pyplines-runner version
pyplines-runner start --help
pyplines --json runner list
There is no runner HTTP health endpoint. Use service/container status, runner logs, advancing heartbeats, and a successful test Run together. After a server restart, allow runners to reestablish transport and report their state before treating them as available.