Skip to main content
A BoxRouter runner is a new Ubuntu 24.04 x64 sandbox for one job. Set runs-on to one BoxRouter label and BoxRouter picks a provider that can supply at least that many CPUs and that much memory.

Runner Labels

Use exactly one BoxRouter label per job. Labels ignore letter case. GitHub’s standard self-hosted, linux and x64 labels are allowed beside it. Append -full to any of these labels, as in boxrouter-ubuntu-24.04-full, to request the full image profile on the same size.
The sizes are floors, so identical labels can land on different hardware. BoxRouter never rounds an unsupported size to another one; it refuses the job. Ubuntu 26.04, a -4 suffix and a floating latest label are unsupported. The runner catalog is the authority for these labels if this table lags.

What Works Today

Provider support for each size depends on your connected accounts, so read it live from Actions readiness. Each provider lists its cpu_options, any unavailable_shapes with a reason, and max_job_minutes. The same data is under Runner Sizes And Providers on the Actions page.

Ranking and Objectives

The label names the machine only. Your workspace’s Routing settings decide which providers may run the job, who pays and the cheapest-or-fastest ranking. A label cannot widen access or change who pays.

Time Limits

A job runs for up to 6 hours after GitHub assigns it, the same limit as GitHub-hosted runners. Before that, BoxRouter waits up to 5 minutes for a machine to start and pick up the job. GitHub’s timeout-minutes can end a job sooner and never extends the limit. Three things can lower the 6 hours:
  • A repository policy’s max_runtime_seconds sets a shorter limit. It can’t raise the limit.
  • A connected provider account can cap a sandbox’s life below 6 hours. max_job_minutes in readiness reports the cap, and a job that reaches it ends there. When several accounts can run the job, the job takes the shortest cap among them.
  • A job paid with Credits keeps 30 minutes unless every provider that can run it renews the sandbox’s life as the job goes. Then the job gets the full 6 hours.
Keep jobs shorter than their limit or split them.

Actions Runner Image

Every runner starts from one pinned image, separate from the standard sandbox image, and runs a single GitHub runner as the non-root user runner. The image is smaller than a GitHub-hosted one, so install what is missing: Docker is not in the default image, so docker build, container actions, and service containers fail there. The full image adds Docker, Java, Rust, and the Android SDK. Append -full to a runner label to request it, as in boxrouter-ubuntu-24.04-full, on workspaces whose policy allows the full profile. Until BoxRouter verifies a runner image for that profile, Actions readiness reports profile_unavailable and jobs that use it stay queued. Image Contents lists the versions in both. Disk space varies by route; use df -h to check free space before a large build.

Limits

A matrix starts one sandbox per cell, within the concurrency limit. actions/cache and artifacts live in GitHub and work as on any runner; nothing stays on the sandbox between jobs.

Set Worker Counts Yourself

On providers that enforce CPU with a quota, nproc and os.availableParallelism() report the host’s CPU count instead of your runner’s size. Tools that use that count start more workers than the quota lets run, so the provider throttles them. Set the count to the runner size. For a runner with 2 vCPUs, use:
  • vitest run --maxWorkers=2
  • jest --maxWorkers=2
  • make -j2
  • pytest -n 2
  • GOMAXPROCS=2

Next Steps

Move a Workflow

Pick a label for each job.

Troubleshoot Actions

Fix a refused label or a queued job.

Find a Run

Follow a run, its sandbox, and its cost.