Reference
Runner Provisioner Configuration Reference
Every Shipfox runner provisioner environment variable with its default, plus the runner template file schema: labels, image, cpu, memory, and max_concurrency.
This page is the canonical reference for configuring the Docker runner provisioner (@shipfox/provisioner-docker). For how a provisioner works, see Runner Provisioners; for starting one, see Run a provisioner.
Required variables
| Variable | Purpose |
|---|---|
SHIPFOX_API_URL | Base URL of the Shipfox API the provisioner connects to. |
SHIPFOX_PROVISIONER_TOKEN | Long-lived token that authenticates control-plane calls. Create it for the provisioner scope you intend to run and keep it secret. The value is shown once and can be revoked. |
SHIPFOX_PROVISIONER_TEMPLATES_FILE | Path to the YAML file describing the runner templates this provisioner can start. |
Optional variables
| Variable | Default | Purpose |
|---|---|---|
SHIPFOX_RUNNER_API_URL | SHIPFOX_API_URL | Base URL injected into runner containers as their SHIPFOX_API_URL. Set it when containers reach the API through a different address than the provisioner uses. |
SHIPFOX_RUNNER_POLL_MAX_DURATION_MS | 300000 | Injected into each runner as SHIPFOX_POLL_MAX_DURATION_MS: how long a started runner polls for a job before exiting. Use 0 to poll forever. |
SHIPFOX_PROVISIONER_DOCKER_HOST | local socket | Docker daemon host. Set a Docker host URL when the daemon is remote. |
SHIPFOX_PROVISIONER_DOCKER_NETWORK | unset | Docker network attached to runner containers, for reaching the API through a Compose or bridge network. |
SHIPFOX_PROVISIONER_DOCKER_EXTRA_HOSTS | unset | Comma-separated host mappings added to runner containers, such as host.docker.internal:host-gateway. |
SHIPFOX_PROVISIONER_POLL_WAIT_SECONDS | 30 | How long each demand poll waits for work before returning. 0 makes the poll non-blocking. |
SHIPFOX_PROVISIONER_POLL_INTERVAL_MS | 1000 | Wait between demand polls. Backs off toward the max after errors. |
SHIPFOX_PROVISIONER_POLL_MAX_INTERVAL_MS | 5000 | Largest poll backoff interval after repeated errors. |
SHIPFOX_PROVISIONER_MAX_RESERVATIONS | 250 | Most reservations requested in one poll. Also bounded by free template capacity and the API's cap of 1000. |
SHIPFOX_PROVISIONER_RUNNER_INSTANCE_BATCH_SIZE | 250 | Runner instances created per request (1–1000). Must not exceed the API's own batch limit. |
SHIPFOX_PROVISIONER_REGISTRATION_DEADLINE_MS | 120000 | How long a created container may stay unstarted before the provisioner reaps it as stale. |
SHIPFOX_RUNNER_MAX_LIFETIME_SECONDS | 3600 | Hard maximum lifetime injected into each runner. Set it above the longest permitted job so a runner terminates if its provisioner is unavailable. |
Template file schema
The templates file maps label sets to the containers that provide them:
templates:
docker-ubuntu22-2vcpu:
labels: [ubuntu22, ubuntu22-2vcpu]
image: shipfox-runner:ubuntu22
cpu: 2
memory: 4GiB
max_concurrency: 100| Field | Type | Description |
|---|---|---|
labels | string[] | Labels the started runner registers with. A template can serve any job whose required labels are all in this list. |
image | string | Container image to start. |
cpu | number | vCPUs allocated to the container. Also the template's selection cost. |
memory | string | Memory allocation, such as 4GiB. |
max_concurrency | number | Cap on live containers started from this template. |
target_concurrency | number | Enrolled, unassigned runners to keep ready without demand. Defaults to 0. Keep it at or below max_concurrency: the provisioner does not currently reject a template where it is higher. |
Template selection: when several templates satisfy a job's labels, the provisioner picks the cheapest (fewest vCPUs), then the most specific.
Related pages
Runner Provisioners
The control loop: reserve, create runner instances, launch, enroll, and assign.
Run a provisioner
Prerequisites, token creation, and the launch command.
Runner
The variables injected into each provisioned runner.
Was this page helpful?
Edit this page on GitHub