Runner labels
A label names a size and an operating system. Each size allocates that many CPUs and that many GiB of memory to the job. Use the smallest one that fits; a larger label does not run the job faster, it reserves more of your machine.
| Label | CPUs | Job memory |
|---|---|---|
tbench-2vcpu-ubuntu-2404 | 2 | 2048 MiB |
tbench-4vcpu-ubuntu-2404 | 4 | 4096 MiB |
tbench-8vcpu-ubuntu-2404 | 8 | 8192 MiB |
tbench-16vcpu-ubuntu-2404 | 16 | 16384 MiB |
Ubuntu 24.04 x64 is the only qualified image; there is no 22.04 label. Windows job images, macOS/ARM and GPU jobs are not qualified.
Device capacity
A device advertises the largest label its own caps and Docker allocation allow. A job is never silently placed above the device’s opted-in capacity — an oversized assignment is refused, not reduced.
- Defaults are
TBENCH_MAX_CPUS=2andTBENCH_MAX_MEMORY_MB=4096. The memory figure includes the 128 MiB egress proxy. - The proxy has its own 0.25 CPU ceiling — small, bounded overhead, not part of the job’s advertised CPU class.
- The effective offer is the smaller of your flags and the host. The default tbench-2vcpu-ubuntu-2404 fits a two-CPU, four-GiB device.
Docker Engine 28 or newer is required for the qualified isolated network mode. The engine must report an x86-64 Linux container type, which on Windows means Docker Desktop in Linux-container mode.
Environment variables
| Name | Purpose |
|---|---|
TBENCH_MAX_CPUS | Upper bound on job CPUs this device will offer. Default 2; range 1–16. |
TBENCH_MAX_MEMORY_MB | Device memory budget for jobs, in MiB. Default 4096; range 1024–65536. |
TBENCH_EGRESS_PROFILE | Network policy. Default github-only; package-registries adds only the npm and PyPI registries. |
TBENCH_RUNNER_IMAGE | Override the pinned runner image tag (advanced; the preflight still verifies the image OS). |
TBENCH_PROXY_IMAGE | Override the pinned egress proxy image tag (advanced). |
Caps are clamped to the host: you cannot advertise more CPUs or memory than Docker will actually give the container.
Egress profiles
| Profile | Allowed |
|---|---|
github-only (default) | GitHub only. |
package-registries | GitHub plus registry.npmjs.org, pypi.org and files.pythonhosted.org. |
HTTPS CONNECT on port 443 is required. All DNS answers must be globally routable; the connection uses the validated address without a second lookup. Private, LAN and cloud-metadata addresses and arbitrary hosts remain denied.
Worker commands
The launcher is tbench-worker. After enrollment its installer prints the path where it was placed; it does not change your PATH for you.
| Name | Purpose |
|---|---|
tbench-worker enroll | Enroll this device with a single-use token, by hidden prompt or --enrollment-file. Refuses to run twice. |
tbench-worker check | Run the local diagnostics: device caps, the Ubuntu 24.04 image, Docker version, and broker enrollment. |
tbench-worker serve | Take jobs for a bounded session. Defaults: tbench-worker serve --max-hours 8 --max-jobs 10. |
tbench-worker run | Claim and run a single job once, then exit. |
tbench-worker recover <request-id> | After a crash, check owned local resources and GitHub, then clear a request that is safe to clear. |
tbench-worker stop | Ask a serving worker to stop within one poll interval. Enrollment and stop never claim work. |
A bounded session serves for up to eight hours or ten jobs, whichever comes first, and polls for work. It installs no background service and starts no paid cloud fallback.
Files a device keeps
| Name | Purpose |
|---|---|
.worker-state.json | The device’s revocable enrollment bearer and enrolled repository set. Written with private permissions. |
.worker.lock | Held while a worker runs, so only one process on the device owns jobs at a time. |
.worker-journal | The exact containers, networks and runner a request created, so recovery removes only those. |
.worker-stop | Present when a bounded session has been asked to stop. |
.upgrade-in-progress | Retained after an interrupted upgrade; blocks claiming until a reviewed reinstall finishes. |
None of these hold a GitHub credential. If a run is interrupted, recovery reads the journal to remove only what that request owned.