Runners and execution environments

A runner is the process that claims and executes Shipfox jobs on compute the team controls. Shipfox plans the job, tracks its state, and stores its result. The runner owns the environment where commands and agents actually work.

Shipfox decides which work is ready. A runner decides which ready job it can claim.

A label is a promise about the host. Capacity says how much work it can take. Both must fit before a job starts.

The workflow asks for needs, not a machine name. This keeps placement easy to review. It also keeps jobs portable.

This boundary lets work reach private code and internal networks. It can also use special hardware and local tools. Shipfox does not own that infrastructure. The team owns its capacity and access.

Labels express placement needs

A job requests labels. A runner can claim it only when the runner has every requested label and free capacity.

Useful labels describe capabilities or policy.

• Operating system or architecture.
• Hardware such as a GPU or large-memory machine.
• Access to a private network.
• A trusted environment for one team or class of work.

A label is not a runner identity. Any available runner with the required set can claim the job. This allows capacity to grow without changing the workflow.

Very specific labels give precise placement but reduce the pool that can run the job. Broad labels improve availability but may place work in an environment with more access than it needs.

Capacity is part of scheduling

A job can be ready even when it cannot start. No online runner may match its labels, or every matching runner may already be at capacity.

In that state the job remains pending. The workflow has not failed, and starting another run does not create the missing capacity. The scheduler waits for a suitable runner.

This distinction matters during diagnosis.

• A dependency can keep a job pending because earlier work is not done.
• Runner placement can keep a ready job pending because no capacity matches.

Resolve pending jobs provides the procedural checks. The explanation here is the reason a valid run may wait without making progress.

A job gets an isolated checkout

Each job execution receives a fresh repository checkout. Steps in that execution share the files. Separate jobs and later listening executions do not share files, installed packages, process environment, or logs.

Isolation makes placement flexible. A retry or parallel job does not depend on files from another runner. Isolation also adds setup work. Each job must install its own tools or restore them from an external cache.

Use outputs for small values and external storage for artifacts. Treat local files as part of one job execution only.

Network access is a capability

The runner environment must reach every service used by the job. That usually includes Shipfox and the source repository. Agent jobs also need the selected model provider. Commands may need package registries, internal APIs, or other project services.

Network access belongs in placement design. A runner on a private network can reach internal systems. Work placed there also gets that reach. Use labels and workspace boundaries to send only the intended jobs there.

Long-lived and provisioned runners trade speed for isolation

The two models make different tradeoffs.

Both models use the same job and label rules. Checkout and permission rules also stay the same. A workspace can use both. The workflow asks for labels. It does not choose how long a runner lives.

Use Start and register a runner for the operational task. The Runner reference lists exact configuration and token facts. Jobs and steps explains when work should share one execution environment.