| 1 | --- |
| 2 | title: Self-hosted runners |
| 3 | description: Run your workflow jobs, and if you choose your agents' work, on your own machines. Their time costs nothing. |
| 4 | --- |
| 5 | |
| 6 | import { TabItem, Tabs } from '@astrojs/starlight/components'; |
| 7 | |
| 8 | A self-hosted runner is a machine of yours that runs your workflow jobs |
| 9 | instead of g1t's sandboxes. It can be a server, a Mac in a cupboard, a |
| 10 | Windows box with a GPU, or a pod in your cluster. On Linux you run |
| 11 | `g1t-runner` as a container under [Sysbox](#run-it-as-a-container), so |
| 12 | neither the runner nor its jobs can reach the machine; it registers once |
| 13 | and picks up jobs that ask for it with `runs-on: self-hosted`. |
| 14 | |
| 15 | - **Time on your runners is $0**, on every plan, including the free one. |
| 16 | It shows on [usage](/guides/usage-and-billing/) as self-hosted minutes. |
| 17 | - **It only connects out.** The runner polls `api.g1t.sh` over HTTPS for |
| 18 | work. Nothing needs to reach the machine: no open port, no tunnel. |
| 19 | - **Each job in a fresh sandbox.** Every job gets a container of its own, |
| 20 | made for it and removed after it, inside the runner's own container. |
| 21 | See [isolation](#isolation). |
| 22 | - **Any OS.** Linux, macOS and Windows, on x64 and arm64. On your own |
| 23 | computer, `g1t-runner sandbox up` runs Linux jobs in a Linux VM of the |
| 24 | runner's own and Windows jobs each in a Windows Sandbox: see |
| 25 | [sandbox on your computer](#sandbox-on-your-computer). |
| 26 | |
| 27 | | Where | Page | Who manages it | |
| 28 | | --- | --- | --- | |
| 29 | | A workspace | **Workspace → Runners** in the rail, `g1t.sh/<workspace>/-/runners` | Owners only. | |
| 30 | | A project | **Settings → Runners**, `g1t.sh/<workspace>/<project>/settings/runners` | People with the Admin [role](/guides/access-and-roles/) on its repository | |
| 31 | |
| 32 | A workspace's runners serve the repositories their [group](#groups) allows. |
| 33 | A project's own runners serve only that project. |
| 34 | |
| 35 | ## Run it as a container |
| 36 | |
| 37 | On a Linux machine, run the runner's image with the Sysbox runtime. The |
| 38 | runner starts a Docker Engine of its own inside its container and runs |
| 39 | each job in a container on that engine, so jobs are containers inside the |
| 40 | runner's container. Sysbox gives the runner's container a user namespace |
| 41 | of its own, so its root is an unprivileged user on the machine, and lets |
| 42 | it run Docker without `--privileged` and without the machine's Docker |
| 43 | socket. |
| 44 | |
| 45 | 1. Install [Sysbox](https://github.com/nestybox/sysbox) 0.7 or later on |
| 46 | the machine, following its install guide. Earlier versions cannot run |
| 47 | the runner's own Docker Engine, whose `runc` checks `/proc` in a way |
| 48 | they do not allow. Sysbox needs Linux; on a Mac or Windows computer, |
| 49 | use [the sandbox](#sandbox-on-your-computer) instead. |
| 50 | 2. Make a registration token: open **Runners** and click **New runner**. |
| 51 | 3. Run the runner: |
| 52 | |
| 53 | ```sh |
| 54 | docker run -d --name g1t-runner --restart unless-stopped \ |
| 55 | --runtime=sysbox-runc \ |
| 56 | -v g1t-runner:/data \ |
| 57 | -e G1T_RUNNER_URL=https://g1t.sh \ |
| 58 | -e G1T_RUNNER_TOKEN=g1trt_… \ |
| 59 | g1t.sh/flagon-io/g1t-runner |
| 60 | ``` |
| 61 | |
| 62 | The image runs `register-and-run`, which registers once and then runs. |
| 63 | Its configuration and credential are kept on the `g1t-runner` volume, so |
| 64 | the container can be restarted and replaced without registering again. |
| 65 | Every [register option](#register-options) can come from |
| 66 | `G1T_RUNNER_<OPTION>` in the environment, such as `G1T_RUNNER_LABELS=gpu` |
| 67 | or `G1T_RUNNER_MEMORY=8g`, so a secret can hold the token. |
| 68 | |
| 69 | Its log says which isolation it has: |
| 70 | |
| 71 | ```text |
| 72 | … Isolation: nested-container: each job runs in a fresh container on this runner's own Docker Engine, inside the runner's sandboxed container; neither reaches the machine. |
| 73 | ``` |
| 74 | |
| 75 | Do not give the container the machine's Docker socket |
| 76 | (`-v /var/run/docker.sock:/var/run/docker.sock`) or `--privileged`. The |
| 77 | runner looks for both when it starts, and refuses to start if it finds |
| 78 | them: |
| 79 | |
| 80 | | It finds | What it says | |
| 81 | | --- | --- | |
| 82 | | An engine's socket mounted in from the machine (`docker.sock`, `containerd.sock`, `podman.sock`, under any name) | *… is a container engine's socket mounted in from outside this container* | |
| 83 | | An engine's socket it did not make, such as from a mounted `/var/run` | *… is a container engine's socket that this runner did not make* | |
| 84 | | `DOCKER_HOST` set | *DOCKER_HOST is set …* | |
| 85 | | Root in the container is root on the machine (no Sysbox, or `--privileged`) | *root in this container is root on the machine* | |
| 86 | |
| 87 | To start anyway, with jobs able to reach the machine, set |
| 88 | `G1T_RUNNER_UNSAFE_ALLOW_HOST_ACCESS=1`. The runner then logs each |
| 89 | problem with `UNSAFE:` in front, and registers as `container` rather than |
| 90 | `nested-container`. |
| 91 | |
| 92 | The engine's images and build cache are kept in the container, so they |
| 93 | last until the container is removed. Sysbox keeps them on the machine's |
| 94 | disk for that container alone; to keep them when you replace the |
| 95 | container, add `-v g1t-runner-docker:/var/lib/docker`, a volume for one |
| 96 | runner container at a time. |
| 97 | |
| 98 | ## Isolation |
| 99 | |
| 100 | How well a runner keeps work from its machine. A runner tells g1t its |
| 101 | level when it registers and on every poll, and the **Runners** page shows |
| 102 | it on each runner: *Sandboxed*, *VM per job*, *Shared Docker* or |
| 103 | *Unsandboxed*. |
| 104 | |
| 105 | | Isolation | How you get it | What a job can reach | |
| 106 | | --- | --- | --- | |
| 107 | | `nested-container` | The runner's image under Sysbox, as above; on your own computer, `g1t-runner sandbox up`, which runs the same inside a Linux VM of the runner's own; or [the desktop app](/guides/desktop/#how-jobs-run)'s Sandboxed choice. | Its own container, and its own Docker Engine if it uses Docker. Not the machine, and not other jobs. | |
| 108 | | `vm` | `g1t-runner sandbox up` on Windows 11 Pro, Enterprise or Education, or `register --native` there: jobs native to Windows, each in a [Windows Sandbox](#windows-jobs-in-windows-sandbox). | Its own virtual machine, made for the job and discarded after, with a read-only copy of the harness and no other folder of the machine's. | |
| 109 | | `container` | `g1t-runner` installed on the machine with Docker, the desktop app's In Docker choice, or the image given the machine's Docker socket with the override. | Its own container. The runner itself drives the machine's Docker, which can do anything on the machine, so a job that escapes its container, or anything that takes over the runner, controls the machine. | |
| 110 | | `host` | `--no-docker`, or the desktop app's Directly on this computer choice. Deprecated. | Everything the runner's user can: the machine, its files, and what earlier jobs left. | |
| 111 | |
| 112 | ### What a job's container gets |
| 113 | |
| 114 | With `nested-container` and `container` isolation, each job runs in a |
| 115 | container made for it and removed after it: |
| 116 | |
| 117 | | | | |
| 118 | | --- | --- | |
| 119 | | Image | The job's `container:`, else the runner's `--image`, else `node:24-bookworm`. | |
| 120 | | Mounts | The harness (`g1t-runner`), read-only, and a volume of its own at `/home/runner`, removed after the job. Nothing else of the runner's or the machine's. | |
| 121 | | Network | A Docker network of its own, removed after the job. Never the machine's network. | |
| 122 | | Capabilities | Every one dropped but `CHOWN`, `DAC_OVERRIDE`, `FOWNER`, `FSETID`, `SETUID`, `SETGID`, `KILL` and `NET_BIND_SERVICE`, which installing packages and running test servers need. Raw sockets (`ping`) are among those dropped. | |
| 123 | | Privileges | `no-new-privileges`: a setuid program such as `sudo` gains nothing. Run steps as the image's root user rather than with `sudo`. Agent work keeps `sudo`, which its image uses once to put its guardrails out of the agent's reach. | |
| 124 | | Limits | `--memory` (three quarters of the runner's memory unless you set it, with no swap beyond it), `--cpus` (every CPU unless you set it) and `--pids-limit` (4096 unless you set it). | |
| 125 | | Credentials | Only the job's own short-lived token, passed by name. Never the runner's credential. | |
| 126 | |
| 127 | ### Docker in jobs |
| 128 | |
| 129 | With `nested-container` isolation, a job that uses Docker (its |
| 130 | `services:`, a Docker action, a `docker://` step, or `docker` in a step) |
| 131 | gets a Docker Engine of its own. It starts the first time the job uses |
| 132 | Docker, from `docker:28-dind`, beside the job's container and on the job's |
| 133 | network, so a service's published ports are on the job's `localhost`. It |
| 134 | is removed, with its images and containers, when the job ends. A job that |
| 135 | does not use Docker never starts one. |
| 136 | |
| 137 | The job's engine is privileged inside the runner's container. Sysbox keeps |
| 138 | it off the machine, but a job that uses Docker can reach the runner's own |
| 139 | container, the runner's credential included. For code you do not trust, |
| 140 | use [ephemeral runners](#autoscaling), so each job has a runner container |
| 141 | of its own, or register with `--no-job-docker`, which gives jobs no Docker. |
| 142 | |
| 143 | With `container` isolation, jobs have no Docker of their own, since it |
| 144 | would be the machine's: their `services:` are not started, and the log |
| 145 | says so. |
| 146 | |
| 147 | ### Host mode is deprecated |
| 148 | |
| 149 | `--no-docker` still works, and runs each job directly on the machine in a |
| 150 | folder of its own. It will be removed. Until then: |
| 151 | |
| 152 | - The runner's log says so when it starts: *Deprecated: this runner runs |
| 153 | jobs directly on this machine (--no-docker), unsandboxed.* |
| 154 | - Every job's log starts with a warning: *This job ran on the host, |
| 155 | unsandboxed …* |
| 156 | - It is not given a public repository's work, which anyone can propose |
| 157 | code to. The runner says how it is isolated when it registers and on |
| 158 | every poll, and g1t hands a public repository's jobs and agent work |
| 159 | only to runners that are not in host mode. A job no other online runner |
| 160 | could take waits, and its page says *Waiting for a sandboxed runner: |
| 161 | this repository is public, and host-mode runners don't run public |
| 162 | repositories' jobs.* It starts once a sandboxed runner with its labels |
| 163 | comes online. |
| 164 | - A runner from before this, which does not say how it is isolated, may |
| 165 | still be given such a job and refuses it itself: *acme/web is public, |
| 166 | and this self-hosted runner runs jobs directly on its machine |
| 167 | (--no-docker), unsandboxed, so it does not take a public repository's |
| 168 | work.* The job fails with that message. Update the runner. |
| 169 | |
| 170 | Move a Linux runner to [the container](#run-it-as-a-container), and a |
| 171 | Windows or Mac computer to [the sandbox](#sandbox-on-your-computer). A |
| 172 | runner registers as running jobs native to Windows or macOS (the |
| 173 | `windows` or `macos` label) only when it sandboxes them (`--native`), or |
| 174 | when you chose host mode with `--no-docker`. |
| 175 | |
| 176 | ## Sandbox on your computer |
| 177 | |
| 178 | `g1t-runner sandbox` sets up self-hosted runners on your own desktop or |
| 179 | laptop that nothing a job runs can get out of: not to your files, your |
| 180 | other programs, your processes or your Docker. It gives the computer up |
| 181 | to two capabilities, each a runner of its own on the **Runners** page: |
| 182 | |
| 183 | | Capability | Runner | Labels | Isolation | |
| 184 | | --- | --- | --- | --- | |
| 185 | | Linux jobs | `<name>-linux`, inside a Linux VM of the runner's own | `self-hosted`, `linux`, and the architecture | `nested-container` | |
| 186 | | Jobs native to the computer's OS | `<name>-windows`, on the computer, starting a Windows Sandbox per job | `self-hosted`, `windows`, and the architecture | `vm` | |
| 187 | |
| 188 | 1. Make a registration token: open **Runners** and click **New runner**. |
| 189 | 2. Download `g1t-runner` for your computer, as in [add a runner](#add-a-runner), |
| 190 | then run: |
| 191 | |
| 192 | ```sh |
| 193 | g1t-runner sandbox up --url https://g1t.sh --token g1trt_… |
| 194 | ``` |
| 195 | |
| 196 | The first `up` fetches the sandbox's image for this release, checks its |
| 197 | signature and SHA-256, makes the VM, and registers both runners with the |
| 198 | token; it takes a few minutes. After that, `up` starts what is stopped |
| 199 | and needs no token. |
| 200 | |
| 201 | | Command | What it does | |
| 202 | | --- | --- | |
| 203 | | `g1t-runner sandbox up` | Makes the sandbox if there is none, and starts both runners. Waits until the Linux runner is asking for work. | |
| 204 | | `g1t-runner sandbox down` | Stops both now. A running job is cut short, and its run says the runner was stopped. `--drain` waits for it to finish instead. `--delete` also removes the VM and everything in it; the runners stay listed on g1t until you remove them there. | |
| 205 | | `g1t-runner sandbox down --only windows` | Stops Windows jobs alone and keeps them off: Linux jobs carry on, and a later `up` leaves Windows jobs stopped. `--only linux` does the same for Linux jobs, leaving Windows jobs running. Takes `--drain`, not `--delete`. | |
| 206 | | `g1t-runner sandbox up --only windows` | Turns Windows jobs on again and starts them, leaving Linux jobs as they are. `--only linux,windows` turns on both. | |
| 207 | | `g1t-runner sandbox status` | Says how each capability is, and what to do about one that is not available. | |
| 208 | | `g1t-runner sandbox update` | Drains the Linux runner (the job it is running finishes), swaps in the newest release's image, and starts it again. The registration is kept, so it is the same runner on g1t. | |
| 209 | |
| 210 | | Option (`up`) | | |
| 211 | | --- | --- | |
| 212 | | `--url`, `--token` | Where to register and the registration token, for the first `up`. The token can come from `G1T_RUNNER_TOKEN` in the environment instead, which keeps it out of the process list. | |
| 213 | | `--name` | The runners' name before `-linux` and `-windows`. The computer's name if left out. | |
| 214 | | `--labels`, `--group` | As for [register](#register-options), for both runners. | |
| 215 | | `--cpus` | The Linux VM's runner's CPUs, and so its jobs'. Half the computer's, at most 8, if left out. | |
| 216 | | `--memory` | Its memory, such as `8g`. A quarter of the computer's, between 2 and 8 GB and never more than half, if left out. | |
| 217 | | `--disk` | The VM's disk on macOS and Linux, such as `64g` (64 GB if left out). On Windows the disk is not limited: WSL can only resize it with all of WSL shut down. | |
| 218 | | `--only` | The kinds of job to start, of `linux`, `windows` and `macos` (`native` is this computer's own): turned on, and kept on. The others are left as they are, running or not. Without it, `up` starts every kind that isn't turned off. `down` takes it too. | |
| 219 | | `--no-native`, `--native` | Turn the native capability off, or on again, as `down --only` and `up --only` do. Kept until said otherwise. | |
| 220 | | `--state-dir` | Where the sandbox keeps its settings and images. `~/.g1t-runner/sandbox` if left out. Every command takes it. | |
| 221 | | `--json` | Print the status as JSON when done (see below). Every command takes it. | |
| 222 | |
| 223 | ### How each computer runs it |
| 224 | |
| 225 | | Computer | Linux jobs | Native jobs | |
| 226 | | --- | --- | --- | |
| 227 | | Windows 11 Pro, Enterprise, Education | A WSL 2 distribution of the runner's own, `g1t-sandbox` | Windows Sandbox, one per job | |
| 228 | | Windows 11 Home | A WSL 2 distribution of the runner's own, `g1t-sandbox` | Not available: Home has no Windows Sandbox | |
| 229 | | macOS 13 or later | A VM under Apple's Virtualization framework, run by [vfkit](https://github.com/crc-org/vfkit) (`brew install vfkit`) | Not released: sandboxed macOS jobs are designed, not built | |
| 230 | | Linux with Sysbox 0.7+ | No VM: the runner's image under Sysbox, as [above](#run-it-as-a-container) | None (Linux jobs are native) | |
| 231 | | Linux without Sysbox | A VM under QEMU with KVM (`/dev/kvm`, and `qemu-system-x86_64` or `qemu-system-aarch64`) | None | |
| 232 | |
| 233 | Inside the VM (and on Linux with Sysbox) it is the runner's image under |
| 234 | Sysbox, exactly as in [run it as a container](#run-it-as-a-container): |
| 235 | each job is a fresh container on the runner's own Docker Engine, inside the |
| 236 | runner's Sysbox container, inside the VM. Nothing listens on your |
| 237 | computer; the VM only connects out. |
| 238 | |
| 239 | **What the VM gets of your computer:** no folders and no drives, no way |
| 240 | to start its programs, no Docker socket, no clipboard, no GPU, display or |
| 241 | sound, and no network port in. On Windows, the distribution's |
| 242 | `/etc/wsl.conf` turns off WSL's drive mounts, its interop with Windows |
| 243 | programs and Windows' `PATH`, and when it starts the sandbox also unmounts |
| 244 | what WSL puts in every distribution anyway: `/mnt/wsl` (shared by all |
| 245 | distributions, where Docker Desktop keeps sockets to its engine on |
| 246 | Windows), WSLg's display and sound sockets, and Windows' GPU driver |
| 247 | folders. It checks that nothing of the computer's is left, and refuses to |
| 248 | run jobs if anything is. Containers in the VM, every job among them, may |
| 249 | reach the internet but not your computer: a firewall rule in the VM drops |
| 250 | their traffic to the computer's address, but for DNS. |
| 251 | |
| 252 | **Resources:** the runner's container has `--cpus` and `--memory`, and |
| 253 | each job has its own limits inside that ([what a job's container gets](#what-a-jobs-container-gets)). |
| 254 | On Windows these are the sandbox's share of WSL's own VM, which |
| 255 | `%USERPROFILE%\.wslconfig` sizes for all of WSL. |
| 256 | |
| 257 | **Images and updates:** the sandbox's images are published with each |
| 258 | runner release, at `g1t.sh/downloads/runner/<version>/`, and named with |
| 259 | their SHA-256 in the release's manifest, which is signed with g1t's |
| 260 | release key like the runner itself (see [updates](#updates)). The runner's |
| 261 | image inside is named by digest in the same manifest. `update` checks the |
| 262 | signature and every SHA-256 before using anything, and waits for the |
| 263 | running job before it swaps the image. The runner's registration lives |
| 264 | apart from the image (on its own disk on macOS and Linux; on Windows the |
| 265 | launcher carries it across), so an update does not register again. |
| 266 | |
| 267 | ### Windows jobs in Windows Sandbox |
| 268 | |
| 269 | With `vm` isolation, the runner on your computer takes jobs that ask for |
| 270 | `runs-on: [self-hosted, windows]` and runs each in a Windows Sandbox of |
| 271 | its own: a Hyper-V virtual machine with its own kernel, started fresh from |
| 272 | your Windows and discarded, disk and all, when the job ends. |
| 273 | |
| 274 | - Its only folder from your computer is read-only and holds a copy of the |
| 275 | runner (the job's harness) and the job's script. Nothing it writes |
| 276 | outlives it. |
| 277 | - No GPU, clipboard, printers, microphone or camera; networking on, so the |
| 278 | job can reach g1t and the internet. |
| 279 | - A firewall rule in it blocks the address your computer is reached by. |
| 280 | The job runs as an administrator in its sandbox and could remove it, so |
| 281 | it slows a job down rather than stopping it; the wall is the VM. |
| 282 | - One job at a time, as every runner. Agent work runs on Linux runners. |
| 283 | - It needs Windows 11 Pro, Enterprise or Education, version 24H2 or later |
| 284 | (for the `wsb` command), with **Windows Sandbox** turned on under |
| 285 | Settings, System, Optional features, More Windows features. `status` |
| 286 | says which of these is missing. |
| 287 | |
| 288 | On a runner that is not under `sandbox up`, `g1t-runner register --native` |
| 289 | does the same. |
| 290 | |
| 291 | ### What it cannot stop |
| 292 | |
| 293 | - **WSL 2 distributions share one VM.** On Windows, every WSL 2 |
| 294 | distribution, your own among them, runs in one virtual machine with one |
| 295 | Linux kernel, and root in one can reach the others' disks. That is why |
| 296 | nothing a job runs is root in the sandbox's distribution: the runner is |
| 297 | a Sysbox container whose root is an unprivileged user there, and each job |
| 298 | a container inside it. A job would have to escape its container and the |
| 299 | runner's, and then reach root in the distribution, before it could touch |
| 300 | your other distributions, from which Windows is reachable. |
| 301 | - **Mirrored networking.** With `networkingMode=mirrored` in |
| 302 | `.wslconfig`, Linux reaches Windows' own `localhost`, so the sandbox |
| 303 | will not start until it is removed. |
| 304 | - **The computer's network.** Jobs reach the internet, and so the other |
| 305 | machines on your network that the internet could. Only your computer's |
| 306 | own address is blocked. |
| 307 | - **The VM's own root** could reach your computer's services on its |
| 308 | address. Jobs are two containers away from it. |
| 309 | - **A Windows job's sandbox** is as strong as Windows Sandbox: a Hyper-V |
| 310 | VM, with one read-only folder of your computer's. |
| 311 | - **macOS and Linux VMs** (vfkit and QEMU) are built to the same design, |
| 312 | with no shared folders and nothing forwarded in, but have not yet been |
| 313 | run on a Mac or a Linux machine without Sysbox. Windows is where the |
| 314 | sandbox has been checked end to end. |
| 315 | |
| 316 | ### What your computer can see |
| 317 | |
| 318 | The sandbox keeps jobs from reaching your computer. It does not keep your |
| 319 | computer from looking at the sandbox, and so at what a job has while it |
| 320 | runs: |
| 321 | |
| 322 | - **A job's log and secrets go from inside the sandbox straight to g1t.** |
| 323 | The runner inside fetches the job, its secrets and its `G1T_TOKEN` |
| 324 | itself, and sends its log back the same way, masked. None of it passes |
| 325 | through a log or file of your computer's. |
| 326 | - **Anything running as your account can look inside a running |
| 327 | sandbox**, as you can: open the WSL distribution with `wsl -u root`, |
| 328 | run a command in a Windows Sandbox, or read the VM's disk. So can an |
| 329 | administrator, root in another WSL distribution (all of WSL 2 shares one |
| 330 | VM), and on Linux with Sysbox anyone in the `docker` group. Don't run a |
| 331 | [host-mode](#host-mode-is-deprecated) runner, or software you don't |
| 332 | trust, under the account the sandbox runs as: what its jobs run could |
| 333 | read the sandbox's runner credentials and the secrets of the job |
| 334 | running in it. `g1t-runner sandbox status` warns when it finds a |
| 335 | host-mode runner registered for the same account (in `~/.g1t-runner`, |
| 336 | `G1T_RUNNER_DIR`, or the desktop app's folder for running jobs directly |
| 337 | on the computer). Remove it with `g1t-runner remove --dir <its folder>`, |
| 338 | or register it under another account. |
| 339 | - **The job's token on your computer is spent after its first use.** A |
| 340 | workflow job reaches its runner with a token of its own, which sits |
| 341 | where your computer can see it: in a Windows job's script, in the job |
| 342 | folder Windows Sandbox reads, and in a container's environment. The |
| 343 | first thing the runner in the sandbox does is fetch the job with it, |
| 344 | and g1t answers with a new token that only the sandbox has; the first |
| 345 | stops working at once for everything that can be asked through g1t's |
| 346 | API (inside g1t, only the lookup of [brokered |
| 347 | secrets](/guides/secrets-and-variables/#brokered-secrets) still takes it, and that is not reachable |
| 348 | from your computer or a job). A copy left |
| 349 | behind can't fetch the job, its secrets or a `G1T_TOKEN` again. A job's |
| 350 | folder is deleted when the job ends, and a runner that was stopped |
| 351 | mid-job (a crash, or `taskkill`) deletes what it left when it next |
| 352 | starts. |
| 353 | - **The registration token goes once the runner has registered.** It is |
| 354 | kept only until the runner inside has registered with it; then the |
| 355 | launcher takes it out of the VM's seed disk on macOS and Linux, and the |
| 356 | sandbox out of its own settings. On Windows, an `update` keeps the |
| 357 | runner's registration on your computer only while the VM is swapped. |
| 358 | - **The state folders are yours alone.** The runner's folder |
| 359 | (`~/.g1t-runner`, `--dir` or `G1T_RUNNER_DIR`) and the sandbox's |
| 360 | (`--state-dir`) hold the runners' credentials, a Windows job's script |
| 361 | while it runs, and the VM's disk. On macOS and Linux they are made |
| 362 | `0700` and their files `0600`. On Windows a folder in your profile is |
| 363 | already yours alone; one elsewhere, such as `C:\runner`, would let every |
| 364 | user of the computer read it, so the runner makes it private (you, |
| 365 | SYSTEM and Administrators, and nothing inherited from the folder |
| 366 | above). If it can't, it refuses to start and says how to fix it. |
| 367 | - **On Windows, opening the sandbox's distribution without naming a user** |
| 368 | (Explorer at `\\wsl.localhost\g1t-sandbox`, or `wsl -d g1t-sandbox`) |
| 369 | gets a locked account with no shell, which can't read the runner's |
| 370 | registration. The launcher names root itself for what it does there. |
| 371 | |
| 372 | ### The status as JSON |
| 373 | |
| 374 | `g1t-runner sandbox status --json` prints one JSON object, which [the |
| 375 | desktop app](/guides/desktop/) shows. It exits 0 whenever it could read |
| 376 | the status, a sandbox in error included; `up`, `down` and `update` print |
| 377 | the same object with `--json` when they are done, and exit 1 with |
| 378 | `error` set when they fail. |
| 379 | |
| 380 | ```json |
| 381 | { |
| 382 | "schema": 1, |
| 383 | "state": "running", |
| 384 | "backend": "wsl2", |
| 385 | "runner_version": "0.3.0", |
| 386 | "launcher_version": "0.3.0", |
| 387 | "image_version": "0.3.0", |
| 388 | "isolation": "nested-container", |
| 389 | "job": { "kind": "workflow", "id": "job_…", "name": "build", "repo": "acme/web" }, |
| 390 | "error": null, |
| 391 | "resources": { "cpus": 4, "memory_mib": 8192, "disk_gib": 64 }, |
| 392 | "capabilities": [ |
| 393 | { "id": "linux", "available": true, "state": "running", "isolation": "nested-container", |
| 394 | "runner_version": "0.3.0", "job": null, "cause": null, "fix": null, "turned_off": false }, |
| 395 | { "id": "windows", "available": false, "state": "absent", "isolation": "vm", |
| 396 | "runner_version": null, "job": null, "turned_off": false, |
| 397 | "cause": "Windows Sandbox is not turned on, or this edition of Windows has none (Home does not).", |
| 398 | "fix": "On Windows 11 Pro, Enterprise or Education, turn on Windows Sandbox under Settings, System, Optional features, More Windows features, then restart." } |
| 399 | ], |
| 400 | "state_dir": "C:\\Users\\you\\.g1t-runner\\sandbox", |
| 401 | "warnings": [] |
| 402 | } |
| 403 | ``` |
| 404 | |
| 405 | | Field | | |
| 406 | | --- | --- | |
| 407 | | `state` | The Linux VM's: `absent` (never made, or deleted), `stopped`, `starting`, `running`, `updating` or `error`. | |
| 408 | | `backend` | What holds it: `wsl2`, `vfkit`, `qemu` or `sysbox`. | |
| 409 | | `runner_version`, `image_version`, `launcher_version` | The runner inside the VM, the VM's image, and this `g1t-runner`. | |
| 410 | | `job` | What the Linux runner is running now, or null. | |
| 411 | | `error` | A sentence for a person when something is wrong, or null. | |
| 412 | | `capabilities` | Each kind of job the computer can run sandboxed: `linux`, and `windows` or `macos`. `available` says whether it can be had here; when not, `cause` says why and `fix` what to do. Each has its own `state`, `job` and `runner_version`. A native one whose runner didn't start is in `error`, with why in `cause`. | |
| 413 | | `turned_off` | On each capability: someone stopped it (`down --only`, `--no-native`). Its `state` is then `stopped`: stopped by a person, not failing, and nothing in `error`. | |
| 414 | | `warnings` | Sentences about what on the computer weakens the sandbox ([what your computer can see](#what-your-computer-can-see)): a host-mode runner registered for the same account, or a state folder other users can read. Empty when nothing does; left out by earlier versions of `g1t-runner`. `status` without `--json` prints each as a line starting `Warning:`. | |
| 415 | |
| 416 | Fields are only added; `schema` changes if one changes meaning. |
| 417 | |
| 418 | ## The Runners page |
| 419 | |
| 420 | A workspace's **Runners** page shows g1t cloud and your own runners side |
| 421 | by side, with what each is running now and this month's time on each. |
| 422 | |
| 423 | | Part | What it shows | |
| 424 | | --- | --- | |
| 425 | | **g1t cloud** | How many agent runs and workflow jobs are running in g1t's sandboxes now, this month's sandbox time and what it came to at price, the price per minute from g1t's [price book](/guides/usage-and-billing/), and how many agent runs your plan allows at once. | |
| 426 | | **Your runners** | How many are online, busy, idle and offline, this month's self-hosted time (always $0), how many jobs and agent runs are waiting for one of them, and whether they take agent work. | |
| 427 | | **On g1t cloud now** | Each running agent run and workflow job, linked to its run, with its kind, project and when it started. Work handed to one of your runners is listed under that runner instead. | |
| 428 | | **Machine time** | This month's time on g1t cloud against your runners', from your [usage](/guides/usage-and-billing/). | |
| 429 | | **Your runners** list | Each runner's status, labels, OS, architecture, `g1t-runner` version and when it was last heard from, and what it is running, linked to the workflow run or the agent run. | |
| 430 | | **Where work runs** | What decides where each kind of work runs, and the [agent setting](#agents-on-your-runners). | |
| 431 | |
| 432 | A runner is **Idle** when it is online with nothing to do, **Busy** while it |
| 433 | runs a job or an agent run, and **Offline** when it has not polled for 90 |
| 434 | seconds. When a service does not answer, only its part of the page says so. |
| 435 | |
| 436 | Sessions that persist are here for workspace agents: each has |
| 437 | [a computer of its own](/guides/agents/#its-computer) on g1t cloud, whose |
| 438 | home stays between sessions and which sleeps when idle; the page says so |
| 439 | under **Agents' computers and more**. Pinning an agent's computer to one of |
| 440 | your own runners and an official agent image are coming, and the page |
| 441 | labels them so. |
| 442 | |
| 443 | **Desktops** lists every computer in the workspace with [the desktop |
| 444 | app](/guides/desktop/#the-runner), whose runner runs while g1t is open |
| 445 | there: what each is doing, or why it isn't running and how to fix it, in |
| 446 | the app's own words, and how it runs jobs. A computer whose g1t has been |
| 447 | closed for ten minutes says *g1t is closed on* its name, and so does its |
| 448 | runner in the list, rather than *Offline*. |
| 449 | |
| 450 | ## A runner in the desktop app |
| 451 | |
| 452 | [The desktop app](/guides/desktop/#the-runner) runs a runner for you |
| 453 | while it is open, with nothing to install or register: it registers your |
| 454 | computer with the workspace you choose, as you, through the site, and |
| 455 | keeps the runner up to date. It runs jobs sandboxed by default |
| 456 | (`nested-container`); running them in Docker (`container`) or directly |
| 457 | on the computer (`host`) are settings you choose, and the app never falls |
| 458 | back to them. Sandboxed, it is [the sandbox](#sandbox-on-your-computer), |
| 459 | which the app sets up with `g1t-runner sandbox up` and shows with |
| 460 | `sandbox status --json`: Linux jobs and, on Windows 11 Pro and up, |
| 461 | Windows jobs, each a runner of its own. Its runners have the label |
| 462 | `desktop` besides the usual ones. |
| 463 | |
| 464 | ## Add a runner |
| 465 | |
| 466 | On Linux, [run it as a container](#run-it-as-a-container). To install |
| 467 | `g1t-runner` on a machine instead, as on macOS and Windows: |
| 468 | |
| 469 | 1. Open **Runners** (a project's: **Settings → Runners**) and click **New runner**. g1t makes a |
| 470 | registration token and shows the commands for Linux, macOS, Windows and |
| 471 | Docker with it filled in. The token lasts an hour, can register any |
| 472 | number of runners until then, and is shown once. |
| 473 | 2. On the machine, download `g1t-runner` and register it: |
| 474 | |
| 475 | <Tabs syncKey="os"> |
| 476 | <TabItem label="macOS"> |
| 477 | ```sh |
| 478 | # Apple silicon; use g1t-runner-macos-x64 on Intel |
| 479 | curl -fsSLo g1t-runner https://g1t.sh/downloads/runner/latest/g1t-runner-macos-arm64 |
| 480 | chmod +x g1t-runner |
| 481 | ./g1t-runner register --url https://g1t.sh --token g1trt_… |
| 482 | ``` |
| 483 | </TabItem> |
| 484 | <TabItem label="Linux"> |
| 485 | ```sh |
| 486 | # x64; use g1t-runner-linux-arm64 on arm64 |
| 487 | curl -fsSLo g1t-runner https://g1t.sh/downloads/runner/latest/g1t-runner-linux-x64 |
| 488 | chmod +x g1t-runner |
| 489 | ./g1t-runner register --url https://g1t.sh --token g1trt_… |
| 490 | ``` |
| 491 | </TabItem> |
| 492 | <TabItem label="Windows"> |
| 493 | ```powershell |
| 494 | Invoke-WebRequest https://g1t.sh/downloads/runner/latest/g1t-runner-windows-x64.exe -OutFile g1t-runner.exe |
| 495 | .\g1t-runner.exe register --url https://g1t.sh --token g1trt_… |
| 496 | ``` |
| 497 | </TabItem> |
| 498 | </Tabs> |
| 499 | |
| 500 | 3. Start it: `./g1t-runner run` keeps it running in the terminal, or |
| 501 | install it as a service that starts with the machine: |
| 502 | |
| 503 | <Tabs syncKey="os"> |
| 504 | <TabItem label="macOS"> |
| 505 | ```sh |
| 506 | ./g1t-runner service install |
| 507 | ``` |
| 508 | A launch agent, `sh.g1t.g1t-runner-<name>`; its log is `~/.g1t-runner/runner.log`. |
| 509 | </TabItem> |
| 510 | <TabItem label="Linux"> |
| 511 | ```sh |
| 512 | sudo ./g1t-runner service install |
| 513 | ``` |
| 514 | A systemd unit, `g1t-runner-<name>`; its log is `journalctl -u g1t-runner-<name>`. |
| 515 | </TabItem> |
| 516 | <TabItem label="Windows"> |
| 517 | From an Administrator prompt: |
| 518 | ```powershell |
| 519 | .\g1t-runner.exe service install |
| 520 | ``` |
| 521 | A Windows service, `g1t-runner-<name>`, that restarts if it stops. |
| 522 | </TabItem> |
| 523 | </Tabs> |
| 524 | |
| 525 | `service start`, `stop`, `status` and `uninstall` do what they say. |
| 526 | |
| 527 | The runner shows up in the list within a few seconds, with a green dot. |
| 528 | |
| 529 | Installed this way, it has `container` isolation with Docker, or `host` |
| 530 | isolation with `--no-docker`. See [isolation](#isolation). |
| 531 | |
| 532 | ### Register options |
| 533 | |
| 534 | | Option | | |
| 535 | | --- | --- | |
| 536 | | `--url` | The g1t you register with: `https://g1t.sh`. | |
| 537 | | `--token` | The registration token. | |
| 538 | | `--name` | What to call it. The machine's name if left out. Names are unique within a workspace (or project). | |
| 539 | | `--labels` | Extra labels, comma-separated: `gpu,cuda-12`. See [labels](#labels). | |
| 540 | | `--group` | A workspace runner's [group](#groups). The default group, or the one the token was made for, if left out. | |
| 541 | | `--ephemeral` | Take one job, then remove itself. For [autoscaling](#autoscaling). | |
| 542 | | `--no-docker` | Deprecated. Run jobs directly on the machine instead of in containers ([host mode](#host-mode-is-deprecated)). | |
| 543 | | `--native` | Run jobs native to this OS, each in a throwaway VM of its own: [Windows Sandbox](#windows-jobs-in-windows-sandbox) on Windows. Registers with the OS's label and `vm` isolation, and refuses if the sandbox is not there. | |
| 544 | | `--image` | The image workflow jobs run in when they name no `container:`. `node:24-bookworm` if left out. | |
| 545 | | `--agent-image` | The image [agent work](#agents-on-your-runners) runs in. | |
| 546 | | `--memory` | Each job container's memory, such as `8g`. Three quarters of the runner's memory if left out. | |
| 547 | | `--cpus` | Each job container's CPUs, such as `4` or `1.5`. Every CPU if left out. | |
| 548 | | `--pids-limit` | The most processes in a job container. 4096 if left out. | |
| 549 | | `--no-job-docker` | Give jobs no [Docker of their own](#docker-in-jobs). | |
| 550 | | `--job-docker-image` | The image a job's own Docker Engine runs. `docker:28-dind` if left out. | |
| 551 | | `--work-dir` | Where jobs run with `--no-docker` keep their files. `~/.g1t-runner/work` if left out. | |
| 552 | | `--dir` | Where the runner keeps its configuration and credential. `~/.g1t-runner`, or `G1T_RUNNER_DIR`, if left out. Every command takes it. | |
| 553 | | `--replace` | Take the place of a runner with the same name. | |
| 554 | | `--no-auto-update` | Never update itself. | |
| 555 | |
| 556 | To run several runners on one machine, give each its own `--dir` and |
| 557 | `--name`. |
| 558 | |
| 559 | ## Use it in a workflow |
| 560 | |
| 561 | A job runs on a self-hosted runner when its `runs-on` names `self-hosted`: |
| 562 | |
| 563 | ```yaml |
| 564 | jobs: |
| 565 | test: |
| 566 | runs-on: self-hosted |
| 567 | steps: |
| 568 | - uses: actions/checkout@v5 |
| 569 | - run: make test |
| 570 | |
| 571 | gpu: |
| 572 | runs-on: [self-hosted, linux, gpu] |
| 573 | steps: |
| 574 | - run: nvidia-smi |
| 575 | |
| 576 | windows: |
| 577 | runs-on: [self-hosted, windows] |
| 578 | steps: |
| 579 | - run: Get-ComputerInfo | Select-Object OsName |
| 580 | ``` |
| 581 | |
| 582 | Until a runner with every label the job names takes it, the job waits, and |
| 583 | its page says what for: *Waiting for a self-hosted runner with labels |
| 584 | self-hosted, linux, gpu.* A job that waits a day fails. Jobs that have |
| 585 | waited ten minutes with no matching runner online show under **Needs you** |
| 586 | on Mission control. |
| 587 | |
| 588 | `runs-on: { group: GPU, labels: [linux] }` asks for a runner in the group |
| 589 | called GPU as well. |
| 590 | |
| 591 | ### Labels |
| 592 | |
| 593 | Every runner has `self-hosted`, its OS (`linux`, `macos` or `windows`) and |
| 594 | its architecture (`x64` or `arm64`), then the labels you gave it. A runner |
| 595 | that runs jobs in Docker is `linux`, whatever the machine is, since that is |
| 596 | what its jobs run on. Labels are matched without regard to case. |
| 597 | |
| 598 | A job takes a runner only when every label in its `runs-on` is one of the |
| 599 | runner's. Labels that name g1t's own machines, such as `ubuntu-latest` or |
| 600 | `g1t-4core`, never go to a self-hosted runner. |
| 601 | |
| 602 | ### What a job gets |
| 603 | |
| 604 | A job on your runner runs exactly as it would in g1t's sandbox: the same |
| 605 | harness, the same `${{ }}` contexts, `GITHUB_*` variables, secrets and |
| 606 | workflow commands, the same log and artifacts. `runner.name`, `runner.os` |
| 607 | and `runner.arch` are the machine's, and `RUNNER_ENVIRONMENT` is |
| 608 | `self-hosted`. |
| 609 | |
| 610 | - **In a container** (the default), each job gets a fresh container from |
| 611 | its `container:` image or the runner's `--image`, removed when it ends, |
| 612 | with the walls in [what a job's container gets](#what-a-jobs-container-gets). |
| 613 | In the runner's image under Sysbox, its `services:` and Docker actions |
| 614 | get [a Docker Engine of its own](#docker-in-jobs). |
| 615 | - **With `--no-docker`** (deprecated), each job gets a fresh folder under |
| 616 | the work folder, removed when it ends, and runs with whatever the |
| 617 | machine has installed. A step's default shell is `bash` on Linux and |
| 618 | macOS and PowerShell on Windows; `shell: pwsh`, `powershell`, `cmd`, |
| 619 | `bash` and `python` work where installed. On a machine with Docker, the |
| 620 | job's `services:`, `container:`, `docker://` steps and Docker actions |
| 621 | use the machine's Docker, as on GitHub's runners. |
| 622 | |
| 623 | A self-hosted job stops at 360 minutes unless its `timeout-minutes` says |
| 624 | otherwise, as on GitHub, and can ask for up to 24 hours (1440). Jobs on |
| 625 | g1t's own machines stop at 60 minutes. |
| 626 | |
| 627 | ## Groups |
| 628 | |
| 629 | A workspace's runners are in groups, which say which repositories may use |
| 630 | them. Every workspace has a **Default** group, for every repository, which |
| 631 | runners join unless their token or `--group` names another. |
| 632 | |
| 633 | To keep a set of machines for some repositories, open the workspace's |
| 634 | **Runners** page, click **New group**, name it, and choose **Only these** |
| 635 | repositories. Then click **New runner** with that group chosen, or register |
| 636 | with `--group`. Deleting a group moves its runners to the default group. |
| 637 | |
| 638 | ## Agents on your runners |
| 639 | |
| 640 | **Runners → Where work runs** can send g1t's own work to your |
| 641 | runners too: agent runs, checks, reviews, merge checks and the merge queue. |
| 642 | Switch on **Run g1t's work on self-hosted runners** and give the labels |
| 643 | a runner needs to take it (`self-hosted` is always one). |
| 644 | |
| 645 | - The agent works exactly as in g1t's sandbox: the same harness, with a |
| 646 | short-lived credential that can do only what that kind of run may, in |
| 647 | that repository, revoked when it ends. |
| 648 | - Its model calls still go through g1t's model proxy, `models.g1t.sh`, with |
| 649 | that credential, so budgets, caps and the audit log work as before. With |
| 650 | your own [model provider](/guides/models/), g1t charges nothing for the |
| 651 | run; otherwise the model is paid as usual and the machine is free. |
| 652 | - Agent work needs an image with git, Node, `tar` and the agent's CLI: |
| 653 | register the runner with `--agent-image` and an image of yours that has |
| 654 | them. Host mode on a Linux machine set aside for it, where `/work` can be |
| 655 | written, also works, and is deprecated. g1t does not publish an agent |
| 656 | image yet. |
| 657 | - [Guardrails](/guides/guardrails/) still apply to what the agent does, but |
| 658 | their network list cannot be enforced on your machine. The run's session |
| 659 | says so when it starts. |
| 660 | |
| 661 | A project can have its own setting, or follow the workspace's. |
| 662 | |
| 663 | ## What a run gets from Customize |
| 664 | |
| 665 | When g1t's work runs Claude Code on a runner (on g1t's own machines too), |
| 666 | the job gets what the workspace set up in [Customize](/guides/customize/), |
| 667 | as the job's agent would have it. Before Claude Code starts, the runner |
| 668 | reads the workspace's bundle with the job's short-lived agent credential, |
| 669 | once per job, and makes it ready: |
| 670 | |
| 671 | | In the bundle | What the runner does | In Claude Code | |
| 672 | | --- | --- | --- | |
| 673 | | Installed plugins that are switched on, each with where to fetch it and the commit it is pinned to | Fetches each at that commit (GitHub's archive of the commit, a clone of the repository here, or the zip the marketplace names) into `/work/.g1t/plugins/<name>/` and passes it with `--plugin-dir`, one flag per plugin | Its skills as `/<plugin>:<skill>`, its subagents as `<plugin>:<agent>`, and its hooks, LSP servers, output styles and `bin/`, which run only here and never on g1t's own agents | |
| 674 | | The library's own skills that reach the agent, as files | Writes them as one more plugin, `g1t-library`, with a `skills/<name>/` folder each, passed with `--plugin-dir` too. A plugin's skills come with the plugin itself | `/g1t-library:<skill>` | |
| 675 | | The connectors that reach the agent and are connected, with the headers that sign them in | Merges each into the `--mcp-config` file's `mcpServers`, by its name, beside g1t's own server | `mcp__<name>__<tool>` | |
| 676 | |
| 677 | The run's session gets one line saying what was loaded: *Loaded 2 plugins, |
| 678 | 1 library skill and 3 connectors from the workspace's Customize.* A plugin |
| 679 | that could not be fetched, or a bundle that could not be read, is named |
| 680 | there and the run goes on without it; nothing from Customize fails a run. |
| 681 | Plugins from GitHub need `tar` on the machine. |
| 682 | |
| 683 | A run on a fork's head loads none of the fork's own settings, hooks, MCP |
| 684 | servers or commands ([guardrails](/guides/guardrails/)). The workspace's |
| 685 | plugins and connectors are the workspace's, not the checkout's, so they are |
| 686 | still passed and merged; but every skill and command is switched off on |
| 687 | such a run, the plugins' and the library's included, so an agent cannot |
| 688 | invoke them there. |
| 689 | |
| 690 | The bundle carries the connectors' sign-ins, so only a job's agent |
| 691 | credential or a workspace's token reads it, never a person's: |
| 692 | [`GET /workspaces/{workspace}/customize/bundle`](/reference/api/customize/customize-bundle/), |
| 693 | scope `agents:run`. g1t never keeps or logs it, and the runner keeps the |
| 694 | keys it brought out of the session. See |
| 695 | [what a run gets](/guides/customize/#what-a-run-gets). |
| 696 | |
| 697 | ## Billing |
| 698 | |
| 699 | Time on your runners is free. Each job's minutes go on |
| 700 | [usage](/guides/usage-and-billing/) as **Self-hosted runner time** at $0, |
| 701 | so you can see how much ran there. |
| 702 | |
| 703 | - Workflow jobs on your runners need no plan and no card: they work on the |
| 704 | free tier. A workspace on the free plan runs **4** of its workflow jobs |
| 705 | on its runners at once, however many runners it has; the rest stay |
| 706 | queued until one finishes. On the g1t plan there is no such cap. |
| 707 | - A workspace g1t has put a hold on cannot register new runners: making a |
| 708 | registration token answers that it is held. |
| 709 | - Agent work on your runners still needs its model paid for: the g1t plan, |
| 710 | the trial, the open-source pool on a public repository, or your own |
| 711 | model provider, which makes the run free. |
| 712 | |
| 713 | ## Security |
| 714 | |
| 715 | - **Pull requests from forks never run on your runners** unless you allow |
| 716 | it under **Runners → Where work runs**. Leave it off on a |
| 717 | public repository: anyone who can open a pull request could run any code |
| 718 | on the machine, read what it can reach, and leave something behind for |
| 719 | the next job. Such jobs get no secrets either way. |
| 720 | - **Secrets** reach a job on your runner under the same rules as on g1t's: |
| 721 | only trusted runs get them, and only the ones for the job's environment. |
| 722 | - **The runner's credential** can poll for work, report on what it was |
| 723 | given and remove itself, and nothing else; every other endpoint refuses |
| 724 | it. It is kept only as a hash on g1t's side, rotates every day, and stops |
| 725 | working the moment the runner is removed. It is never given to a job: |
| 726 | each job gets only its own short-lived token, which the job spends on |
| 727 | fetching itself and replaces with one only the job has. The runner's |
| 728 | folder is its owner's alone, and the runner refuses to start in one |
| 729 | other users can read ([what your computer can see](#what-your-computer-can-see)). |
| 730 | - **Isolation**: run the runner's image under Sysbox. Each job then gets |
| 731 | a container of its own inside the runner's container, removed after, |
| 732 | and neither reaches the machine. A job with `--no-docker` runs as the |
| 733 | runner's user and can reach whatever that user can; host mode is |
| 734 | deprecated and refuses public repositories' work. Use ephemeral runners |
| 735 | for code you do not trust. See [isolation](#isolation). |
| 736 | - **Network**: g1t's network guardrails are not enforced on your machines. |
| 737 | A job reaches whatever the machine can. |
| 738 | - **Audit**: making a registration token, registering, removing, and every |
| 739 | job a runner takes are in the [audit log](/guides/audit-log/), with the |
| 740 | runner as the actor. |
| 741 | - Only owners (or a repository's admins) register and remove runners, |
| 742 | signed in or with a person's token with `runners:admin`. Workspace |
| 743 | tokens, `G1T_TOKEN` included, cannot, so a workflow cannot add a machine |
| 744 | to run its own jobs. |
| 745 | |
| 746 | ## Docker and Kubernetes |
| 747 | |
| 748 | [Run it as a container](#run-it-as-a-container) covers Docker. The image's |
| 749 | settings, besides the register options: |
| 750 | |
| 751 | | Variable | | |
| 752 | | --- | --- | |
| 753 | | `G1T_RUNNER_SANDBOX` | `nested` in the image: start a Docker Engine inside the container and run jobs on it. | |
| 754 | | `G1T_RUNNER_DIR` | `/data` in the image: where the configuration and credential are kept. | |
| 755 | | `G1T_RUNNER_UNSAFE_ALLOW_HOST_ACCESS` | `1` starts the runner even when it can reach the machine. See [above](#run-it-as-a-container). | |
| 756 | |
| 757 | A runner that ran the image with the machine's Docker socket, as these |
| 758 | docs said before, refuses to start with the new image. Remove the |
| 759 | `-v /var/run/docker.sock:/var/run/docker.sock` and add |
| 760 | `--runtime=sysbox-runc`; the `/data` volume keeps its registration. |
| 761 | |
| 762 | ### Autoscaling |
| 763 | |
| 764 | Ephemeral runners take one job and remove themselves, so each job starts in |
| 765 | a fresh runner container. In Kubernetes with Sysbox installed on the |
| 766 | nodes (its Kubernetes install adds the `sysbox-runc` runtime class), run |
| 767 | them in pods that make their own registration token from an owner's |
| 768 | personal [access token](/guides/authentication/#access-tokens) with only |
| 769 | `runners:admin`, and let the Deployment replace each pod that finishes: |
| 770 | |
| 771 | ```yaml |
| 772 | apiVersion: apps/v1 |
| 773 | kind: Deployment |
| 774 | metadata: |
| 775 | name: g1t-runner |
| 776 | spec: |
| 777 | replicas: 3 |
| 778 | selector: { matchLabels: { app: g1t-runner } } |
| 779 | template: |
| 780 | metadata: |
| 781 | labels: { app: g1t-runner } |
| 782 | annotations: { io.kubernetes.cri-o.userns-mode: "auto:size=65536" } |
| 783 | spec: |
| 784 | runtimeClassName: sysbox-runc |
| 785 | containers: |
| 786 | - name: runner |
| 787 | image: g1t.sh/flagon-io/g1t-runner |
| 788 | command: ["sh", "-c"] |
| 789 | args: |
| 790 | - | |
| 791 | export G1T_RUNNER_TOKEN="$(curl -fsS -X POST \ |
| 792 | -H "Authorization: Bearer $G1T_ADMIN_TOKEN" \ |
| 793 | https://api.g1t.sh/workspaces/acme/actions/runners/registration-token \ |
| 794 | | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')" |
| 795 | exec g1t-runner register-and-run |
| 796 | env: |
| 797 | - { name: G1T_RUNNER_URL, value: https://g1t.sh } |
| 798 | - { name: G1T_RUNNER_LABELS, value: k8s } |
| 799 | - { name: G1T_RUNNER_EPHEMERAL, value: "1" } |
| 800 | - name: G1T_ADMIN_TOKEN |
| 801 | valueFrom: { secretKeyRef: { name: g1t, key: runners-admin-token } } |
| 802 | ``` |
| 803 | |
| 804 | To scale with demand rather than keep a fixed number, change `replicas` |
| 805 | with your autoscaler of choice: [`list_runners`](/reference/api/runners/list-runners-for-workspace/) |
| 806 | says which are busy. |
| 807 | |
| 808 | ## Updates |
| 809 | |
| 810 | The runner checks for a new release every six hours while it is idle, and |
| 811 | updates itself when the release is signed by g1t's release key and its |
| 812 | download matches the release's SHA-256. `g1t-runner update` does it now; |
| 813 | `--no-auto-update` turns it off. Releases are at |
| 814 | `https://g1t.sh/downloads/runner/<version>/`, with a `SHA256SUMS` file. |
| 815 | The runner inside [the sandbox](#sandbox-on-your-computer) does not update |
| 816 | itself: `g1t-runner sandbox update` swaps the whole sandbox's image, which |
| 817 | carries it, once the running job is done. |
| 818 | |
| 819 | ## Remove a runner |
| 820 | |
| 821 | On the machine, `g1t-runner remove` unregisters it and forgets its |
| 822 | credential (run `service uninstall` first if it is a service). Or remove it |
| 823 | from the **Runners** page; the runner stops on its next poll. A job it was |
| 824 | running fails. Runners offline for 14 days are removed by themselves. |
| 825 | |
| 826 | ## API and MCP |
| 827 | |
| 828 | | What | REST | MCP (`workflow` tool) | Scope | |
| 829 | | --- | --- | --- | --- | |
| 830 | | List runners | [`GET /workspaces/{workspace}/actions/runners`](/reference/api/runners/list-runners-for-workspace/), [`GET /repos/{owner}/{name}/actions/runners`](/reference/api/runners/list-runners/) | `list_runners` | `runners:read` | |
| 831 | | Make a registration token | [`POST …/actions/runners/registration-token`](/reference/api/runners/create-runner-registration-token-for-workspace/) | `create_runner_token` | `runners:admin` | |
| 832 | | Remove a runner | [`DELETE …/actions/runners/{id}`](/reference/api/runners/remove-runner-for-workspace/) | `remove_runner` | `runners:admin` | |
| 833 | | Groups | [`GET`](/reference/api/runners/list-runner-groups/), [`POST`](/reference/api/runners/create-runner-group/), [`PATCH`](/reference/api/runners/update-runner-group/), [`DELETE`](/reference/api/runners/delete-runner-group/) `/workspaces/{workspace}/actions/runner-groups` | `list_runner_groups`, `create_runner_group`, `update_runner_group`, `delete_runner_group` | `runners:read`, `runners:admin` | |
| 834 | | Where work runs | [`GET`](/reference/api/runners/get-runner-settings-for-workspace/), [`PATCH`](/reference/api/runners/update-runner-settings-for-workspace/) `…/actions/runner-settings` | `get_runner_settings`, `update_runner_settings` | `runners:read`, `runners:admin` | |
| 835 | | What a run gets from Customize | [`GET /workspaces/{workspace}/customize/bundle`](/reference/api/customize/customize-bundle/) | `customize` tool, `bundle` | `agents:run`, with a job's agent token | |
| 836 | |
| 837 | The [Agent preset](/guides/authentication/#scopes) does not include |
| 838 | `runners:read`. |
| 839 | |
| 840 | ## Troubleshooting |
| 841 | |
| 842 | | What you see | What to do | |
| 843 | | --- | --- | |
| 844 | | The job says *Waiting for a self-hosted runner with labels …* | No online runner has every one of those labels in a group that allows the repository. Compare the labels on the **Runners** page, check the runner's group, or start the runner. | |
| 845 | | *Pull requests from forks do not run on self-hosted runners here.* | The run is from a fork. Allow it under **Where work runs**, if you trust everyone who can open a pull request. | |
| 846 | | `register` says the token is not valid | It expired after an hour, or was mistyped. Make a new one. | |
| 847 | | `register` says a runner with that name is registered | Choose another `--name`, or add `--replace`. | |
| 848 | | `run` says *g1t no longer knows this runner* | It was removed, or its credential was. Register it again. | |
| 849 | | *this runner is not sandboxed from its machine, so it will not take work* | The runner's container can reach the machine: it lists why. Remove the machine's Docker socket and `--privileged`, and run it with `--runtime=sysbox-runc`. See [run it as a container](#run-it-as-a-container). | |
| 850 | | *the runner's own Docker Engine could not start* | The container is not running under Sysbox. Add `--runtime=sysbox-runc`, and check that Sysbox is installed (`docker info` lists `sysbox-runc` under runtimes). | |
| 851 | | The job says *Waiting for a sandboxed runner: this repository is public …* | Every online runner with the job's labels is in host mode, which never runs a public repository's jobs. Run a runner's image under Sysbox, or register one without `--no-docker`. | |
| 852 | | *… is public, and this self-hosted runner runs jobs directly on its machine* | An older runner in host mode refused a public repository's job. Update it, so g1t gives the job to a sandboxed runner instead, and run the runner's image under Sysbox. | |
| 853 | | `sandbox up` says *WSL is not installed* | Open a terminal as administrator, run `wsl --install --no-distribution`, restart, and run `sandbox up` again. That is the one step that needs an administrator. | |
| 854 | | `sandbox up` says *WSL is set to mirrored networking* | Remove `networkingMode=mirrored` from `%USERPROFILE%\.wslconfig`, run `wsl --shutdown`, and try again. | |
| 855 | | `sandbox status` says *this sandbox can reach the computer* | Something of your computer's is mounted in the sandbox's VM, or an engine's socket is there; it lists what. Run `g1t-runner sandbox down --delete` and `up` again, which makes it from the image afresh. | |
| 856 | | `sandbox status` shows the Linux runner in `error` with *The runner stopped …* | The runner inside could not register or start; the message is its last line. Check the token was still valid (an hour), and that the computer reaches `https://api.g1t.sh`. | |
| 857 | | The `windows` capability is unavailable | `status` says why: Windows Sandbox is off, this is Windows 11 Home, or Windows is older than 24H2. | |
| 858 | | A step's `sudo` fails | Job containers have `no-new-privileges`. Steps run as the image's user, root in most CI images, so drop the `sudo`. | |
| 859 | | *could not run docker* | Install Docker and start it, and give the runner's user access to it. | |
| 860 | | Agent work fails at once | Give the runner `--agent-image`. | |
| 861 | | The runner is offline in the list | It has not polled for 90 seconds. Check its log (`journalctl -u g1t-runner-<name>`, `~/.g1t-runner/runner.log`, or the terminal) and that the machine can reach `https://api.g1t.sh`. | |