# Runner Configuration Reference (https://www.shipfox.io/docs/reference/runner) Description: 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](https://www.shipfox.io/docs/understand/runners-and-execution-environments). To start one, see [Start and register a runner](https://www.shipfox.io/docs/operations/runners). ## Required variables [#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](https://www.shipfox.io/docs/reference/runner#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-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 [#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](https://www.shipfox.io/docs/reference/runner-labels). ## Token types [#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](https://www.shipfox.io/docs/reference/runner-provisioner) | Single-use; grants only enrollment into a workspace-neutral control session, not a workspace, reservation, or job credential. | ## Optional variables [#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 [#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 [#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 [#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 [#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](https://www.shipfox.io/docs/reference/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 [#related-pages] ### [Runner labels](https://www.shipfox.io/docs/reference/runner-labels) Compare Shipfox-hosted runner CPU, memory, and workspace storage. ### [Runners and execution](https://www.shipfox.io/docs/understand/runners-and-execution-environments) Understand placement, labels, capacity, and checkout isolation. ### [Runner Provisioner](https://www.shipfox.io/docs/reference/runner-provisioner) Autoscaling configuration and template schema.