The runner guides cover g1t-runner 0.3.5's needs and the desktop app's Set up in full (#52). Self-hosted runners gets "What the sandbox needs": run `g1t-runner sandbox status` first, since it downloads nothing; a sample of what it prints; a row for each need it names (windows_update, virtualization, nested_virtualization, vm_platform, wsl, wsl_update, windows_edition, windows_sandbox, restart, kvm_module, kvm_group, qemu, macos_update, homebrew, vfkit) with its kind of job and the fix; that each is named only when the computer says it for certain, and Windows' facts are kept per boot; and that `sandbox up` stops before downloading the image when Linux jobs lack something, leaving out Windows jobs unless named with --only. Its JSON sample and field table gain `needs`, with the current cause and fix wording, and the troubleshooting rows and the desktop app section point at the new section.
The desktop guide's Set up now says what the code does: Restart now asks in Windows' own dialog with No chosen, g1t opens once at the next sign-in after either Restart now or Later, a step that fails after a feature was turned on still asks for the restart and offers Set up again after it, WSL comes by --web-download first and through the Store only if that fails, only features that are off are turned on, and Set up is Windows-only, with macOS and Linux given commands and the VMs there not yet run end to end. The Virtualization and nested-virtualization rows name the "How to turn it on" button and say when each is detected. The anchors the app's buttons open are unchanged.
- Checked:
- crates/runner/src/selfhosted/needs.rs (Need::said, wsl_needs, windows_sandbox_needs, kvm_needs, vfkit_needs), launcher/mod.rs (status, print, up), launcher/wsl.rs and vm.rs availability; apps/desktop/src-tauri/src/runner/setup.rs (script, run_elevated, ask_and_restart, open_after_restart), diagnosis.rs need_words and its action labels, mod.rs's set_up, restart_windows and restart_later and the docs URLs it opens. Docs build (543 pages) and tests (4).
- G1t-Session:
- ses_01m4ynr1peevvs8zwaqakycv2e
2 files+98−150/2 viewed
| 363 | 363 | have on, and installs or updates WSL. Windows asks you to allow it, once | |
| 364 | 364 | (on a standard account, an administrator types their password). The cards | |
| 365 | 365 | say *Setting up* meanwhile, a few minutes. When what it turned on takes a | |
| 366 | − | restart, they say *Restart needed*, with **Restart now**, which asks first | |
| 367 | − | (save your work), and **Later**. After the restart g1t opens again by | |
| 368 | − | itself and carries on: Linux jobs download their image and start. Set up | |
| 369 | − | is the same as running these in an admin terminal, and its log goes into | |
| 370 | − | the runner's: | |
| 366 | + | restart, they say *Restart needed*, with **Restart now** and **Later**. | |
| 367 | + | **Restart now** asks first, in a Windows dialog of its own (*Restart | |
| 368 | + | Windows now to finish setting up the runner?*, with No chosen until you | |
| 369 | + | choose Yes), so save your work before you answer; a page can't restart | |
| 370 | + | your computer without you. Either way, g1t opens once by itself the next | |
| 371 | + | time you sign in to Windows, whether or not it opens at sign-in anyway, | |
| 372 | + | and carries on: Linux jobs download their image and start. Until Windows | |
| 373 | + | has restarted, the cards keep saying *Restart needed*. | |
| 374 | + | ||
| 375 | + | If a step fails after a feature was turned on, the cards still ask for the | |
| 376 | + | restart, and offer **Set up** again after it for what is left. Set up is | |
| 377 | + | the same as running these in an admin terminal, and its log goes into the | |
| 378 | + | runner's (**View log**): | |
| 371 | 379 | ||
| 372 | 380 | ```powershell | |
| 373 | 381 | Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -All -NoRestart | |
| 374 | 382 | Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All -NoRestart | |
| 375 | − | wsl --install --no-distribution # or wsl --update, for an older WSL | |
| 383 | + | wsl --install --no-distribution --web-download # or wsl --update --web-download, for an older WSL | |
| 376 | 384 | ``` | |
| 377 | 385 | ||
| 386 | + | It turns on only the features that are off, for the kinds of job that are | |
| 387 | + | on. WSL is downloaded directly first (`--web-download`), which needs no | |
| 388 | + | Microsoft Store; if that fails, the same command runs again without it, | |
| 389 | + | through the Store. | |
| 390 | + | ||
| 391 | + | Set up is for Windows alone. On Linux and macOS nothing the sandbox needs | |
| 392 | + | can be installed without your password in a terminal, so the card gives | |
| 393 | + | the command, with **Copy command**, and changes by itself once it has | |
| 394 | + | run. The sandbox has been checked end to end on Windows; on macOS and on | |
| 395 | + | Linux without Sysbox, the checks and commands below are what the app does, | |
| 396 | + | but the VMs themselves [have not yet been run there](/guides/self-hosted-runners/#what-it-cannot-stop). | |
| 397 | + | ||
| 378 | 398 | Whatever is missing, nothing falls back to running jobs in Docker or | |
| 379 | 399 | directly on your computer: those are only ever [your choice](#how-jobs-run). | |
| 380 | 400 | ||
| ⋯ | |||
| 386 | 406 | | *Needs setting up*: *Windows Sandbox is off* | The Windows Sandbox feature, which each Windows job runs in. | **Set up**, then restart. | | |
| 387 | 407 | | *Not available*: *Not in Windows Home* | Windows Sandbox, which Windows Home doesn't have. Linux jobs run all the same. | Nothing, for Linux jobs. For Windows jobs, Windows 11 Pro, Enterprise or Education: **Open Activation** is where Windows upgrades. | | |
| 388 | 408 | | *Restart needed*: *Restart to finish setting up* | Set up turned on a Windows feature, which takes effect after a restart. | **Restart now**, or **Later** and restart when it suits you. g1t opens again after and carries on. | | |
| 389 | − | | *Virtualization is off* | Intel VT-x or AMD-V, turned off in your computer's firmware, where Windows can't turn it on. | [Turn on virtualization](#turning-on-virtualization), then **Check now**. | | |
| 390 | − | | *This VM can't run the sandbox* | g1t is in a virtual machine whose host doesn't pass virtualization through to it. | [Turn on nested virtualization](#in-a-virtual-machine) on the host. | | |
| 409 | + | | *Virtualization is off* | Intel VT-x or AMD-V, turned off in your computer's firmware, where Windows can't turn it on. Said on Windows jobs too, when Windows Sandbox is on but could not start. | [Turn on virtualization](#turning-on-virtualization) (**How to turn it on** opens these steps), then **Check now**. | | |
| 410 | + | | *This VM can't run the sandbox* | g1t is in a virtual machine whose host doesn't pass virtualization through to it. Said once the sandbox's VM has failed to start for that reason, since it can't be known before. | [Turn on nested virtualization](#in-a-virtual-machine) on the host (**How to turn it on**). | | |
| 391 | 411 | | *Windows needs an update*, on Linux jobs | Windows older than Windows 10 version 2004, the first with WSL 2. | **Open Windows Update**, update, and restart. | | |
| 392 | 412 | | *Windows needs an update*, on Windows jobs | Windows Sandbox's command line, `wsb`, which came with Windows 11 24H2. | **Open Windows Update**, update to 24H2 or later, and restart. | | |
| 393 | 413 | | *Set up didn't finish* | You said No to Windows' prompt, or a step failed, with its reason. | **Set up** again; **View log** says what happened. | | |
| 204 | 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 | 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 | 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. | | |
| 207 | + | | `g1t-runner sandbox status` | Says how each capability is, what the computer still lacks for one that is not available, and what to do. It downloads nothing, so it is the first thing to run on a new computer. See [what the sandbox needs](#what-the-sandbox-needs). | | |
| 208 | 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 | 209 | ||
| 210 | 210 | | Option (`up`) | | | |
| ⋯ | |||
| 264 | 264 | apart from the image (on its own disk on macOS and Linux; on Windows the | |
| 265 | 265 | launcher carries it across), so an update does not register again. | |
| 266 | 266 | ||
| 267 | + | ### What the sandbox needs | |
| 268 | + | ||
| 269 | + | The sandbox is a small VM, so a computer needs what any VM needs. Run | |
| 270 | + | `g1t-runner sandbox status` first: before anything is downloaded, it says | |
| 271 | + | for each kind of job what the computer still lacks, what must come first | |
| 272 | + | first, with why and what to do: | |
| 273 | + | ||
| 274 | + | ```text | |
| 275 | + | Sandbox: absent (wsl2) | |
| 276 | + | linux unavailable | |
| 277 | + | Virtual Machine Platform, the Windows feature WSL 2 runs on, is turned off. | |
| 278 | + | Open a terminal as administrator and run `wsl --install --no-distribution`, which turns it on, then restart Windows. | |
| 279 | + | windows unavailable | |
| 280 | + | Windows Sandbox is not turned on, and Windows jobs each run in one. | |
| 281 | + | Turn on Windows Sandbox under Settings, System, Optional features, More Windows features, then restart. | |
| 282 | + | Error: Virtual Machine Platform, the Windows feature WSL 2 runs on, is turned off. | |
| 283 | + | ``` | |
| 284 | + | ||
| 285 | + | With `--json`, each capability's `needs` lists the same by name. Each is | |
| 286 | + | named only when the computer says it for certain, from Windows itself, | |
| 287 | + | `/proc` on Linux or `sw_vers` on macOS, so a computer that can run the | |
| 288 | + | sandbox is never held back by a guess. One kind of job missing something | |
| 289 | + | never stops the other: Windows jobs that Windows Home can't run leave | |
| 290 | + | Linux jobs running. | |
| 291 | + | ||
| 292 | + | | Need | Kind of job | What is missing | What to do | | |
| 293 | + | | --- | --- | --- | --- | | |
| 294 | + | | `windows_update` | Linux, on Windows | Windows older than Windows 10 version 2004, the first with WSL 2. | Update Windows, then restart. | | |
| 295 | + | | `windows_update` | Windows | Windows Sandbox's command line, `wsb`, which came with Windows 11 24H2. | Update Windows to 24H2 or later. | | |
| 296 | + | | `virtualization` | Any | Virtualization (Intel VT-x or AMD-V) off in the firmware, or, on Linux, a processor without it. | Turn it on in the BIOS or UEFI settings ([how](/guides/desktop/#turning-on-virtualization)). On Linux, Sysbox 0.7 or later needs no VM. | | |
| 297 | + | | `nested_virtualization` | Any | The computer is itself a VM whose host doesn't pass virtualization through. On Windows this is named from the error the VM gives as it fails to start, since it can't be known before. | Turn on nested virtualization for the VM on its host ([how](/guides/desktop/#in-a-virtual-machine)). | | |
| 298 | + | | `vm_platform` | Linux, on Windows | The Virtual Machine Platform feature. | `wsl --install --no-distribution` in an admin terminal, then restart. | | |
| 299 | + | | `wsl` | Linux, on Windows | WSL. | `wsl --install --no-distribution` in an admin terminal, then restart. Every edition of Windows 11, Home included, has it. | | |
| 300 | + | | `wsl_update` | Linux, on Windows | WSL older than 2.0, or the one built into older Windows rather than the Microsoft Store's. | `wsl --update` in an admin terminal. | | |
| 301 | + | | `windows_edition` | Windows | Windows Home, which has no Windows Sandbox. | Nothing for Linux jobs. Windows jobs need Windows 11 Pro, Enterprise or Education. | | |
| 302 | + | | `windows_sandbox` | Windows | The Windows Sandbox feature. | Turn it on under Settings, System, Optional features, More Windows features, then restart. | | |
| 303 | + | | `restart` | Linux, Windows, on Windows | The desktop app's Set up turned on a Windows feature, which takes effect after Windows restarts. | Restart Windows. | | |
| 304 | + | | `kvm_module` | Linux, on Linux | `/dev/kvm`, though the processor can run VMs: KVM isn't loaded. | `sudo modprobe kvm_intel` (or `kvm_amd`), or install Sysbox. | | |
| 305 | + | | `kvm_group` | Linux, on Linux | Permission to use `/dev/kvm`. | `sudo usermod -aG kvm $USER`, then log out and in again. | | |
| 306 | + | | `qemu` | Linux, on Linux | QEMU. | Install it (`qemu-system-x86` on Debian and Ubuntu, `qemu-kvm` on Fedora), or Sysbox. | | |
| 307 | + | | `macos_update` | Linux, on macOS | macOS older than 13. | Update macOS. | | |
| 308 | + | | `homebrew` | Linux, on macOS | vfkit, and Homebrew, which installs it. | Install Homebrew from [brew.sh](https://brew.sh), then `brew install vfkit`. | | |
| 309 | + | | `vfkit` | Linux, on macOS | vfkit. | `brew install vfkit`. | | |
| 310 | + | ||
| 311 | + | On Linux with Sysbox 0.7 or later, none of the Linux rows apply: the | |
| 312 | + | runner's image runs under Sysbox, without a VM. On Windows, what Windows | |
| 313 | + | says of itself is read once per boot and kept in the state folder | |
| 314 | + | (`windows-facts.json`), since none of it changes before a restart. | |
| 315 | + | ||
| 316 | + | `sandbox up` asks the same first. When Linux jobs lack something, it | |
| 317 | + | stops before downloading the image, with the first need's words; Windows | |
| 318 | + | jobs that can't run here are left out, unless you named them with | |
| 319 | + | `--only windows`, when it says why. [The desktop app](/guides/desktop/#getting-the-runner-running) | |
| 320 | + | shows each need on its kind of job's card and, on Windows, sets up | |
| 321 | + | `vm_platform`, `wsl`, `wsl_update` and `windows_sandbox` together with | |
| 322 | + | one **Set up** button and a single administrator prompt. | |
| 323 | + | ||
| 267 | 324 | ### Windows jobs in Windows Sandbox | |
| 268 | 325 | ||
| 269 | 326 | With `vm` isolation, the runner on your computer takes jobs that ask for | |
| ⋯ | |||
| 400 | 457 | "resources": { "cpus": 4, "memory_mib": 8192, "disk_gib": 64 }, | |
| 401 | 458 | "capabilities": [ | |
| 402 | 459 | { "id": "linux", "available": true, "state": "running", "isolation": "nested-container", | |
| 403 | − | "runner_version": "0.3.0", "job": null, "cause": null, "fix": null, "turned_off": false }, | |
| 460 | + | "runner_version": "0.3.0", "job": null, "cause": null, "fix": null, "turned_off": false, "needs": [] }, | |
| 404 | 461 | { "id": "windows", "available": false, "state": "absent", "isolation": "vm", | |
| 405 | 462 | "runner_version": null, "job": null, "turned_off": false, | |
| 406 | − | "cause": "Windows Sandbox is not turned on, or this edition of Windows has none (Home does not).", | |
| 407 | − | "fix": "On Windows 11 Pro, Enterprise or Education, turn on Windows Sandbox under Settings, System, Optional features, More Windows features, then restart." } | |
| 463 | + | "cause": "Windows Sandbox is not turned on, and Windows jobs each run in one.", | |
| 464 | + | "fix": "Turn on Windows Sandbox under Settings, System, Optional features, More Windows features, then restart.", | |
| 465 | + | "needs": ["windows_sandbox"] } | |
| 408 | 466 | ], | |
| 409 | 467 | "state_dir": "C:\\Users\\you\\.g1t-runner\\sandbox", | |
| 410 | 468 | "warnings": [] | |
| ⋯ | |||
| 419 | 477 | | `job` | What the Linux runner is running now, or null. | | |
| 420 | 478 | | `error` | A sentence for a person when something is wrong, or null. | | |
| 421 | 479 | | `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`. | | |
| 480 | + | | `needs` | On each capability: what the computer still lacks for it, by name, first what must come first; `cause` and `fix` say the first. The names are in [what the sandbox needs](#what-the-sandbox-needs). Empty when nothing is missing; left out by `g1t-runner` before 0.3.5. | | |
| 422 | 481 | | `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`. | | |
| 423 | 482 | | `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:`. | | |
| 424 | 483 | ||
| ⋯ | |||
| 461 | 520 | which the app sets up with `g1t-runner sandbox up` and shows with | |
| 462 | 521 | `sandbox status --json`: Linux jobs and, on Windows 11 Pro and up, | |
| 463 | 522 | Windows jobs, each a runner of its own. Its runners have the label | |
| 464 | − | `desktop` besides the usual ones. | |
| 523 | + | `desktop` besides the usual ones. What [the sandbox | |
| 524 | + | needs](#what-the-sandbox-needs) and the computer lacks, each kind of | |
| 525 | + | job's card says in plain words, and on Windows **Set up** turns on the | |
| 526 | + | features and installs or updates WSL behind one administrator prompt: | |
| 527 | + | see [getting the runner running](/guides/desktop/#getting-the-runner-running). | |
| 465 | 528 | ||
| 466 | 529 | ## Add a runner | |
| 467 | 530 | ||
| ⋯ | |||
| 817 | 880 | | *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). | | |
| 818 | 881 | | 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`. | | |
| 819 | 882 | | *… 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. | | |
| 820 | − | | `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. | | |
| 883 | + | | `sandbox up` says *WSL is not installed*, or another of [what the sandbox needs](#what-the-sandbox-needs) | Do what it says, which is that need's row there; `wsl --install --no-distribution` in an admin terminal, then a restart, is the one step on Windows that needs an administrator. Then run `sandbox up` again. | | |
| 821 | 884 | | `sandbox up` says *WSL is set to mirrored networking* | Remove `networkingMode=mirrored` from `%USERPROFILE%\.wslconfig`, run `wsl --shutdown`, and try again. | | |
| 822 | 885 | | `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. | | |
| 823 | 886 | | `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`. | | |
| 824 | − | | The `windows` capability is unavailable | `status` says why: Windows Sandbox is off, this is Windows 11 Home, or Windows is older than 24H2. | | |
| 887 | + | | The `windows` capability is unavailable | `status` says why, and its `needs` by name: Windows Sandbox is off (`windows_sandbox`), this is Windows Home (`windows_edition`), Windows is older than 24H2 (`windows_update`), or virtualization is off in the firmware (`virtualization`). | | |
| 825 | 888 | | 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`. | | |
| 826 | 889 | | *could not run docker* | Install Docker and start it, and give the runner's user access to it. | | |
| 827 | 890 | | 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`. | | |
Comments
Sign in to comment.