igneum/docs/plans/ci-self-hosted.md

CI on the box: the self-hosted runner and the workflow change (proposal, 6 October 2026)

The runner igneum-build-1 (labels self-hosted, linux, x64, igneum-build-1) is installed by infra/build-server/provision.sh step_runner and registered by infra/build-server/runner/register.sh (docs/plans/build-server.md section 7). The workflows are NOT changed here: the shipper owns .github/workflows tonight. This is the proposed diff for main.

1. The shape: one repository variable decides, GitHub-hosted is the fallback

GitHub has no "try this runner, else that one" in runs-on: a list of labels means ALL of them must match one runner, so [self-hosted, igneum-build-1, ubuntu-latest] would never schedule. The fallback is therefore a repository variable read in the expression. IGNEUM_CI_RUNNER = box sends the job to the box; unset or anything else keeps ubuntu-latest. Flipping it back is one click in Settings > Secrets and variables > Actions > Variables (or gh variable set IGNEUM_CI_RUNNER --body box and gh variable delete IGNEUM_CI_RUNNER as igneum-labs), with no commit and no queue lost: a job already queued for the box stays queued; the next push goes to GitHub's machines.

2. ci.yml (the two jobs that compile or compute; the site job stays on GitHub's machines)

 jobs:
   pow:
     name: igneum-pow tests, igneum-census build
-    runs-on: ubuntu-latest
+    runs-on: ${{ vars.IGNEUM_CI_RUNNER == 'box' && fromJSON('["self-hosted", "linux", "x64", "igneum-build-1"]') || 'ubuntu-latest' }}
     steps:
       - uses: actions/checkout@v4
       - name: toolchain
         run: rustc --version && cargo --version
@@
   sims:
     name: simulators, quick modes
-    runs-on: ubuntu-latest
+    runs-on: ${{ vars.IGNEUM_CI_RUNNER == 'box' && fromJSON('["self-hosted", "linux", "x64", "igneum-build-1"]') || 'ubuntu-latest' }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
+        if: vars.IGNEUM_CI_RUNNER != 'box'   # the box has python3 and numpy from provision.sh; setup-python would download a second Python
         with:
           python-version: '3.12'
-      - run: python3 -m pip install --quiet numpy
+      - run: python3 -m pip install --quiet numpy
+        if: vars.IGNEUM_CI_RUNNER != 'box'

What the box gives these two jobs: rustc 1.99.0 pinned (GitHub's ubuntu-latest carries whatever stable it ships; the box is the Mac's version, so CI compiles what the agents compile), sccache hits from the agents' cache (read-only), 48 cargo jobs. The site job is Node and shell checks and takes under a minute on GitHub's runners; moving it buys nothing and would put tools/ci/public-api-check.mjs (a live HTTPS check) behind the box's egress for no reason.

Why the toolchain line still runs: on the box rustc --version must print 1.99.0; a mismatch means provision.sh and the runner's rustup disagree (R5 in build-server.md) and the job should say so in its first step.

3. windows.yml: no change possible on this box

Every job of windows.yml runs on windows-latest for a reason the box cannot answer: the engine builds on the MSVC target, the window host needs the Windows SDK and WebView2, the installer needs Inno Setup, the smoke run executes the exes and the launcher under Windows PowerShell 5.1. A Linux runner has none of that. The only self-hosted option for this workflow is a Windows runner on PC 1 or PC 2 (actions/runner for Windows under a service account), which conflicts with the rule that the PCs keep only GPU and Windows-runtime JOBS through the signed job system, and is not proposed tonight.

What the box already does for Windows is upstream of this workflow: tools/cross-remote.sh builds igneumd.exe and igneum-miner.exe (the payload inputs) in 1 min 44 s, and the night battery rebuilds them for the reproducibility record.

4. What to check after the flip (main, the first run on the box)

Check	Where	Pass
the job landed on the box	the run's "Set up job" log says Runner name: 'igneum-build-1'	yes
the toolchain	the toolchain step prints rustc 1.99.0	yes
sccache hits	add sccache --show-stats as a step once, or read /srv/sccache size before and after: the runner's config is READ_ONLY, so the size must NOT change	size unchanged
the agents were not starved	/srv/builds/_log/builds.jsonl secs of the builds during the run against the same crate's earlier lines	within the usual spread
the fallback	gh variable delete IGNEUM_CI_RUNNER, push a no-op commit: the job runs on ubuntu-latest again	yes

Open: a CI job on the box does not take a build slot (/srv/builds/_locks/build-<k>), it runs at Nice 10 with 48 jobs; if a CI job ever delays a release build visibly, the fix is a step at the top of the job that takes a slot through infra/build-server/remote-run.sh's flock, the same file the agents use.