+----------------+        +-------------------+        +--------------------+
| Gitea instance | <----> |  act_runner       | -----> | job container      |
| (queues jobs)  |   poll | (this docker-     |  docker| cargoxx-runner-    |
|                |        |  compose service) |  spawn | job:latest         |
+----------------+        +-------------------+        +--------------------+

compose.yml runs the official gitea/act_runner:nightly image, which polls Gitea for jobs and spawns one container per workflow run via the host's Docker socket.
flake.nix builds the job container image — reproducible, declarative, ships nix, git, curl, jq, tea, and a single-user NIX_CONFIG. This image runs the actual workflow steps; act_runner just orchestrates it.
config.yaml maps runs-on: self-hosted (from .gitea/workflows/*.yml) to the job image.

One-time setup

Build + load the job image into the host's Docker daemon:
```
cd runner
nix run --extra-experimental-features 'nix-command flakes' .#load-image
```
Re-run whenever you bump nixpkgs or change the tool list.
Mint a runner registration token in the Gitea UI: Site Administration → Actions → Runners → Create new Runner. Copy the token.

Provision the .env alongside compose.yml:

GITEA_INSTANCE_URL=https://git.amadey.xyz
GITEA_RUNNER_REGISTRATION_TOKEN=<paste here>
GITEA_RUNNER_NAME=cargoxx-pkgs-runner
GITEA_RUNNER_LABELS=self-hosted

Start the runner:
```
docker compose up -d
docker compose logs -f runner
```
First boot registers the runner with Gitea; subsequent boots reuse the persisted token in ./data/.runner.

Updating

Change a workflow step's tools → edit flake.nix, rerun nix run .#load-image.
Bump nixpkgs → nix flake update in this dir, rebuild the image.
act_runner itself updates by docker compose pull && docker compose up -d.

Why not host mode?

Host mode (act_runner running workflows directly on the host) would save the Docker indirection but tightly couples the runner host to the toolchain. Docker mode lets us treat the job image as a deployable artifact — same image on every runner, no drift.