# Runners and execution environments (https://www.shipfox.io/docs/understand/runners-and-execution-environments) Description: Understand how Shipfox-hosted and self-managed runners use labels, capacity, isolation, and network access. A **runner** is the process that claims and runs Shipfox jobs. Shipfox plans the job, tracks its state, and stores its result. The runner provides the machine where commands and agents run. Shipfox-hosted runners need no installation or registration. Workflows select them with a [hosted runner label](https://www.shipfox.io/docs/reference/runner-labels). Teams can also connect self-managed runners for private networks, special hardware, or local tools. Both kinds use the same job and label model. With self-managed runners, the team controls capacity and access. Hosted runners handle that work for jobs that fit the hosted environment. ## How labels choose a runner [#how-labels-choose-a-runner] A job requests labels. A runner can claim the job only when it has every requested label and free capacity. Hosted labels select a documented execution environment and size. The [Runner labels reference](https://www.shipfox.io/docs/reference/runner-labels) lists their CPU, memory, storage, operating system, and architecture. Self-managed labels describe the capabilities or policies that the team provides, such as: * An operating system or architecture. * Hardware such as a GPU or a large-memory machine. * Access to a private network. * A trusted environment for one team or one class of work. A label isn't a runner identity. Any available runner with the required labels can claim the job. Capacity can therefore grow without a workflow change. Very specific labels give precise placement but shrink the pool of runners that can run the job. Broad labels improve availability but can place work in an environment with more access than it needs. ## Why a ready job can wait [#why-a-ready-job-can-wait] A job can be ready and still not start. Either no online runner has its labels, or every matching runner is busy. Hosted capacity can be busy too, so a job can wait for a hosted runner as well. The job stays pending. The workflow hasn't failed, and another run doesn't create the missing capacity. The scheduler waits for a suitable runner. During diagnosis, tell the two reasons apart: * A dependency keeps a job pending because earlier work isn't done. * Placement keeps a ready job pending because no runner with the right labels is free. [Resolve pending jobs](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/pending-jobs) gives the checks to run. This page explains why a valid run can wait without making progress. ## Each job gets its own checkout [#each-job-gets-its-own-checkout] Each job execution gets a fresh checkout of the repository. Steps in that execution share its files. Separate jobs and later listening executions don't share files, installed packages, process environment, or logs. A hosted runner serves one job and stops when that job ends. Isolation makes placement flexible: a retry or a parallel job doesn't depend on files from another runner. It also adds setup work: each job installs its own tools or restores 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. ## What the runner must reach [#what-the-runner-must-reach] The runner must reach every service the job uses. That usually includes Shipfox and the source repository. Agent jobs also need the selected model provider. Commands can need package registries, internal services, or other project services. Plan network access together with placement. A runner on a private network can reach internal systems, and so can every job placed on it. Use labels and workspace boundaries to send only the intended jobs there. ## Hosted and self-managed runners [#hosted-and-self-managed-runners] Shipfox creates a hosted runner for one job. A self-managed runner can stay online, or the team can create one for each job. The models make different tradeoffs. | Model | Fits | Tradeoff | | ------------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Shipfox-hosted runner | Jobs that fit a documented hosted environment. | Needs no runner infrastructure from the team, but its capabilities follow the hosted runner catalog. | | Self-managed long-lived runner | Steady work and environments that are slow to create. | Starts quickly, but the team maintains the host and its capacity over time. | | Self-managed per-job runner | Occasional bursts of work, or a strict cleanup boundary after each job. | Starts from a cleaner environment, but adds startup time and infrastructure. | All models use the same job and label rules. Checkout and permission rules stay the same too. A workspace can combine hosted and self-managed runners. The workflow asks for labels; it doesn't choose how long a runner lives. Use the [Runner labels reference](https://www.shipfox.io/docs/reference/runner-labels) to choose hosted capacity. Use [Start and register a runner](https://www.shipfox.io/docs/operations/runners) to add self-managed capacity. The [Runner configuration reference](https://www.shipfox.io/docs/reference/runner) lists exact configuration and token facts. [Jobs and steps](https://www.shipfox.io/docs/understand/jobs-and-steps) explains when work should share one execution environment.