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 Runner labels.
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_RUNNER_ENABLE_RENEWABLE_GIT | false in source-run mode; true in verified managed images | Enables automatic renewal for persist-credentials: true Git checkouts. Managed images set this only after verifying the helper and production dependency closure. Do not set it on a self-hosted or unverified image, or add it to provider-rendered runner environment data. |
SHIPFOX_RUNNER_ENABLE_RENEWABLE_INFERENCE | false in source-run mode; true in verified managed images | Enables renewable credentials for managed Pi and Claude inference sessions. Managed images set this only after verifying the helper and production dependency closure, and only after every API instance accepts renewable_inference in runner capability reports. Do not set it on a self-hosted or unverified image, or add it to provider-rendered runner environment data. |
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
Verified managed runner images advertise renewable Git credentials after their
installation checks pass. A checkout with persist-credentials: true can then
renew its exact repository credential during a long job without workflow-supplied
tokens or retry logic.
Only a verified managed image may advertise this capability. Do not set the flag on a self-hosted or unverified image. The helper and production-closure checks must pass before a runner enables it.
Older self-hosted runners remain compatible and continue with static checkout credentials. If a persisted checkout is dispatched to one, the job shows a warning that the credential may expire and recommends upgrading the runner image. Scheduling is not blocked by the missing capability.
Git commands started inside a container from a user step do not inherit the host runner's helper or Unix socket. Supply an explicit credential to that container when it needs authenticated Git access. Mounting the job workspace alone does not change this boundary.
Renewable inference credentials
Verified managed runner images advertise renewable inference credentials for Pi and Claude sessions. The runner refreshes a managed credential when the harness needs it while the job attempt remains active.
Only a verified managed image may advertise this capability. Before using the
image, deploy an API release that accepts renewable_inference in runner
capability reports on every API instance. Older or unverified runners keep the
flag disabled and use static credentials until they are replaced.
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. |
Related pages
Runner labels
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.
Glossary
Definitions for every Shipfox term: workspace, project, workflow, run, job, step, trigger, runner, harness, gate, CEL, filter, key, and more. Quick reference.
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.