Manage runners

Runners execute Actions and retain the state needed to reconcile their invocations. Use the same platform release for the server and runners, with Docker available on each runner host.

Choose a pool

The initial local pool is available for enrollment. To create another pool, an administrator uses POST /v1/runner-pools with a JSON object such as {"name": "production-amd64"}. There is currently no operator CLI command for creating pools; see API integration. Configure the Environment with the same pool name and matching platform.

Enroll a runner

Use Install a runner for Docker preparation, persistent volume mapping, enrollment, and service configuration. When adding capacity, use a new enrollment and a distinct state directory/work volume for each identity. Enroll into the pool selected by its Environments.

Inspect and admit a registered identity from the administrator workstation:

pyplines --json runner list
pyplines runner approve RUNNER_ID

Use the ID returned by runner list. Confirm admission, draining: false, and advancing last_seen timestamps. Automatic admission requires explicitly creating enrollment with --automatic --max-active N; use it only when automated admission is intended.

Persist state and configure Docker

The runner configuration reference documents state, work-volume, network, and Docker settings. Preserve those settings and identity across ordinary restarts. For network-enabled Actions, provision the Environment's configured network on every runner host in its pool.

Control admission and capacity

pyplines runner drain RUNNER_ID

Drain prevents new work while existing work settles; the runner exits after reconciliation and cleanup. Inspect active Runs before maintenance. The current CLI advertises runner resume, but the server does not implement that transition. Treat draining as retirement from service: after execution settles, restore capacity with a newly enrolled identity, preserving the old runner state and evidence. reject handles an unwanted runner admission; revoke withdraws a runner identity. Neither is a substitute for reconciling an uncertain external effect.

--max-concurrent bounds concurrent workload containers on a node. --ephemeral drains and retires its identity on graceful shutdown. These settings do not remove the one-attempt-at-a-time rule within an Environment.

Investigate connectivity loss

Check the server HTTPS endpoint, advertised NATS TLS endpoint, CA trust, persistent state, and runner service logs. After server restart, connectivity remains unknown until a heartbeat arrives.

Preserve the owning runner's identity and state so it can reconcile execution. There is no automatic reassignment of uncertain work. Follow recovery guidance before replacing a runner with unfinished invocations.