Runner Configuration Reference
Every Shipfox runner environment variable with its default: registration, labels, polling, heartbeats, log delivery, and agent harness overrides. Plus token types.
This page is the canonical reference for configuring a Shipfox runner process. For the execution model, see Runners and execution environments. To start one, see Start and register a runner.
Required variables
| Variable | Purpose |
|---|---|
SHIPFOX_API_URL | Base URL of the Shipfox API the runner connects to, such as https://api.shipfox.io. |
SHIPFOX_RUNNER_REGISTRATION_TOKEN | Manual registration token (sf_mrt_…) the runner exchanges for a short-lived session token at startup. Set this or SHIPFOX_RUNNER_BOOTSTRAP_TOKEN, but not both. |
SHIPFOX_RUNNER_BOOTSTRAP_TOKEN | One-use provisioner-managed bootstrap token (sf_rbt_…); see Token types. The runner exchanges it for a workspace-neutral control session before waiting for an assignment. Set this or SHIPFOX_RUNNER_REGISTRATION_TOKEN, but not both. |
SHIPFOX_RUNNER_LABELS | Comma-separated labels this runner registers with, such as linux,x64,self-hosted. |
Managed assignment polling
Managed runners request a 30-second bounded wait for each assignment poll. The API owns the
server-side cap through RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS; there is no separate runner
environment variable to keep in sync. The runner derives its HTTP timeout from the requested wait
plus a 15-second transport buffer and retries a transport timeout while its control-session
heartbeat remains healthy.
Label matching
A job is dispatched to a runner only when the runner's labels include all labels the job's runner: field requires. A runner may carry several labels; one machine may run several runner processes with different label sets.
For the Shipfox-hosted labels available in Shipfox Cloud, see Hosted runners.
Token types
| Prefix | Name | Created by | Lifetime |
|---|---|---|---|
sf_mrt_ | Manual registration token | Settings → Runners in the dashboard | Long-lived; revocable in the dashboard; value shown once at creation. |
sf_rbt_ | Bootstrap token | A runner provisioner | Single-use; grants only enrollment into a workspace-neutral control session, not a workspace, reservation, or job credential. |
Optional variables
| Variable | Default | Purpose |
|---|---|---|
SHIPFOX_RUNNER_WORKSPACE_ROOT | OS temp directory | Parent directory for per-job workspaces. The runner only creates and cleans per-job child directories under this root. |
SHIPFOX_POLL_INTERVAL_MS | 1000 | How often the runner asks the API for new jobs. Backs off toward SHIPFOX_POLL_MAX_INTERVAL_MS while idle or after errors. |
SHIPFOX_POLL_MAX_INTERVAL_MS | 5000 | Largest interval the poll backoff can reach. |
SHIPFOX_POLL_MAX_DURATION_MS | 300000 | How long the runner keeps polling without claiming a job before it exits. Use 0 for runners that should poll forever. |
SHIPFOX_HEARTBEAT_INTERVAL_MS | 10000 | How often the runner sends a heartbeat. Keep it well below the server's stuck-job threshold of 180 seconds. |
SHIPFOX_HEARTBEAT_MAX_STALE_MS | 10000 | How long one heartbeat request may stay open before the runner cancels it and starts the next. |
Log delivery
| Variable | Default | Purpose |
|---|---|---|
SHIPFOX_LOG_FLUSH_INTERVAL_MS | 2000 | How often buffered step logs upload. Bounds how much recent output is lost if the machine dies mid-step. |
SHIPFOX_LOG_FLUSH_BYTES | 262144 | Size threshold that triggers an early upload before the interval elapses. |
SHIPFOX_LOG_SPOOL_MAX_BYTES | 67108864 | Maximum unacknowledged log bytes kept on disk per step attempt while the API is unreachable. Past it, output is dropped with a gap marker. |
SHIPFOX_LOG_DRAIN_TIMEOUT_MS | 5000 | How long the runner waits at job end for in-flight uploads before deleting the workspace. |
SHIPFOX_AGENT_SESSION_FLUSH_BYTES | 4194304 | Upload window and per-entry drop threshold for agent-session logs. An entry above it is dropped with a gap marker. |
Renewable Git credentials
Every runner renews Git credentials. A checkout with persist-credentials: true
renews its exact repository credential during a long job without workflow-supplied
tokens or retry logic.
Renewal applies to repositories served over HTTPS. For a repository served over plain HTTP, the credential issued at checkout is not renewed. Git access fails in a job that outlives it.
The runner configures Git to call the git-credential-shipfox helper, so that
command must be on the runner's PATH. Runner images install it. A runner started
another way needs the helper from the runner package on its PATH.
The credential also works in a job container. The steps of a
job that has a container field can use it.
The credential does not work in a container that a step starts, for example
with docker run. Git in that container has no credential, even when the job
workspace is mounted. Pass a token to that container when it must use Git with
authentication.
Job containers
A job can have a container
field. The runner then starts a Docker container and runs the steps of the job
in it.
The runner needs two things:
- The
dockercommand. - A local Docker daemon that the runner user can use.
If one is missing, Set up job fails and shows the error.
The runner pulls the image for its own platform: linux/amd64 or
linux/arm64. The job workspace has the same path in the container and on the
runner. The runner also mounts its own files under /__shipfox.
A step in a job container runs as the default user of the image. If that user
is root, the job can leave files that the runner user cannot delete. The
runner deletes them with sudo. The runner images allow sudo without a
password. On a runner where sudo asks for a password, delete those files
yourself.
An old runner does not know the container field. It ignores the field and
runs the job on the runner itself. Upgrade your self-hosted runners when you
upgrade the API.
Renewable inference credentials
Every runner renews managed inference credentials for Pi and Claude sessions. The runner refreshes a managed credential when the harness needs it while the job attempt remains active.
Runner binaries that predate the capability manifest are rejected at registration and must be upgraded.
For the Claude runtime contract cleanup, upgrade runners using the pre-cleanup
schema before deploying an API release that omits claude.auth_token. This
cleanup has no static-credential fallback. If a pre-cleanup runner must be
restored, restore or roll back the API release before restoring the runner.
Agent steps
Model provider credentials are workspace configuration, delivered to the runner per step by the API. Do not put provider API keys in the runner's environment. The runner machine needs outbound network access to the resolved provider's endpoint. See Model Providers.
| Variable | Default | Purpose |
|---|---|---|
AGENT_CLAUDE_ANTHROPIC_BASE_URL | unset | Anthropic-compatible base URL override for the claude harness, for tests or private deployments (for example a local Ollama server). Unset uses the Anthropic API. |
AGENT_CLAUDE_ANTHROPIC_MODEL | unset | Model ID the claude harness sends when the base URL override is set. |
AGENT_CLAUDE_ANTHROPIC_SMALL_FAST_MODEL | unset | Small fast model ID for the claude harness when the base URL override is set. |
AGENT_CUSTOM_PROVIDER_ALLOW_PRIVATE_NETWORKS | true | Allows custom model providers to target private, loopback, and internal networks. Keep true for local and self-hosted private networks; set false on cloud instances. |
AGENT_CUSTOM_PROVIDER_HOST_DENYLIST | empty | Comma-separated hosts and IP ranges custom model providers may not call. Accepts exact hosts, suffix patterns, IP literals, and CIDR blocks. |
Step environment
The runner sets these variables on run steps and action steps. A step env entry with the same name does not override them.
| Variable | Value |
|---|---|
SHIPFOX_RUN_ID | ID of the workflow run. |
SHIPFOX_RUN_NUMBER | Number of the workflow run. |
SHIPFOX_RUN_ATTEMPT | Attempt of the workflow run, starting at 1. |
SHIPFOX_RUN_URL | Link to the run in the Shipfox dashboard. |
SHIPFOX_ENV | Path of a file. Each NAME=value line, or NAME<<DELIMITER block, sets an environment variable for later steps of the job. PATH and names that start with SHIPFOX_ fail the step. |
SHIPFOX_PATH | Path of a file. Each line names a directory that later steps of the job get at the front of PATH. A relative directory resolves against the step working directory. |
SHIPFOX_MASK | Path of a file. Each line names a value that the runner replaces with *** in the logs, outputs, and annotations of later steps of the job. A value shorter than 8 characters fails the step. |
The runner reads SHIPFOX_ENV, SHIPFOX_PATH, and SHIPFOX_MASK when the step
exits, whatever its exit code. See Set environment variables for later
steps.
Related pages
Hosted runners
Compare Shipfox-hosted runner CPU, memory, and workspace storage.
Runners and execution
Understand placement, labels, capacity, and checkout isolation.
Runner Provisioner
Autoscaling configuration and template schema.
Model Providers
Open source edition only. The built-in model provider catalog, including provider IDs, support status, default models, compatible harnesses, and resolution rules.
Runner Provisioner
Every Shipfox runner provisioner environment variable with its default, plus the runner template file schema: vars, defaults, matrix families, labels, image, cpu, memory, cost, and max_concurrency.