From 6e0b90c96864eadb3a802cd01aa9bcd251ccc6c6 Mon Sep 17 00:00:00 2001
From: Joseph Mearman <joseph@mearman.co.uk>
Date: Mon, 2 Nov 2026 23:42:12 +0000
Subject: [PATCH 1/3] feat(cluster): start the node's Colima profile from a
 launchd daemon at boot

The login agent only runs once someone logs in, so a Mac that reboots or loses power sits at the
login window with the node's Colima profile stopped, and its k3s container never comes back.

The profile named by github_runner_cluster_runtime_boot_profile (node) is now started by a launchd
daemon, a property list in /Library/LaunchDaemons owned by root:wheel with mode 0644, loaded into
the system domain and running as the connecting user (UserName) with HOME, PATH and COLIMA_HOME in
its environment. Writing and loading it use become. Any other profile keeps its login agent,
rendered and installed exactly as before. github_runner_cluster_runtime_autostart_at (auto, login
or boot) overrides the choice per host.

A profile has one kind of job at a time. Installing the daemon unloads and deletes the profile's
agent from an earlier run, whether or not the user has a login session, and installing the agent
does the same to a daemon, so the profile is not started twice. Neither unload stops the VM.
---
 README.md                                     |   2 +-
 roles/github_runner_cluster/README.md         |  20 +-
 roles/github_runner_cluster/defaults/main.yml |  13 +-
 .../meta/argument_specs.yml                   |   7 +-
 roles/github_runner_cluster/tasks/runtime.yml |  73 +----
 .../tasks/runtime_agent.yml                   | 104 +++++++
 .../tasks/runtime_daemon.yml                  |  91 ++++++
 .../templates/colima-launchd.plist.j2         |  12 +
 tests/runtime_autostart/render_plist.yml      |   3 +-
 tests/runtime_autostart/run.yml               |   3 +-
 tests/unit/test_runtime_autostart.py          | 269 +++++++++++++++++-
 11 files changed, 508 insertions(+), 89 deletions(-)
 create mode 100644 roles/github_runner_cluster/tasks/runtime_agent.yml
 create mode 100644 roles/github_runner_cluster/tasks/runtime_daemon.yml

diff --git a/README.md b/README.md
index e7faa3b2..c9a8b904 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
 
 There are two ways to deploy. A fleet's hosts are managed from a control machine with Ansible, from the fleet's own inventory (see [Ansible](#ansible) below). `bootstrap.sh`, described here, brings up a single machine from a checkout of this repository without a control node or inventory. It runs the same Ansible role against the machine itself, so both paths deploy identically.
 
-Prerequisites on the host: Docker (or Colima) with the Compose plugin, any release but 2.37.1 to 2.38.x (the cluster role refuses those; see Docker Compose versions in `roles/github_runner_cluster/README.md`), `python3`, `jq`, `openssl`, and `gh`. On macOS, the playbook installs `helm`, `kubectl` and Docker through Homebrew itself, and the cluster role starts a Colima host's profile at every login and fails unless the runtime is up (Docker Desktop needs its own start-at-login setting; see Container runtime at login in `roles/github_runner_cluster/README.md`). Elsewhere, install `helm` and `kubectl` from the host's package manager first.
+Prerequisites on the host: Docker (or Colima) with the Compose plugin, any release but 2.37.1 to 2.38.x (the cluster role refuses those; see Docker Compose versions in `roles/github_runner_cluster/README.md`), `python3`, `jq`, `openssl`, and `gh`. On macOS, the playbook installs `helm`, `kubectl` and Docker through Homebrew itself, and the cluster role starts a Colima host's profile again after a reboot (the node's profile at boot, with nobody logged in, any other at login) and fails unless the runtime is up (Docker Desktop needs its own start-at-login setting; see Container runtime after a reboot in `roles/github_runner_cluster/README.md`). Elsewhere, install `helm` and `kubectl` from the host's package manager first.
 
 1. **Create a GitHub App** on the organisation with **Self-hosted runners: read & write** permission, and install it on the organisation. `playbooks/github_app_setup.yml` does this through GitHub's manifest flow (see `roles/github_runner_arc/README.md`). For one repository's runners instead, which is how a repository of a personal account uses the fleet, the App needs repository **Administration: read & write** and **Metadata: read**, installed where it reaches that repository, and `RUNNER_REPOSITORY` names it (see Repository scope in `roles/github_runner_arc/README.md`).
 2. **Configure the environment.** Copy `.env.bootstrap.example` to `.env.bootstrap` and fill in the following (the file's own comments cover the rest, such as joining an existing cluster or running as an agent):
diff --git a/roles/github_runner_cluster/README.md b/roles/github_runner_cluster/README.md
index 35102e4e..85662f2b 100644
--- a/roles/github_runner_cluster/README.md
+++ b/roles/github_runner_cluster/README.md
@@ -136,21 +136,26 @@ By default the role drives whichever Docker daemon the host's current Docker con
 
 Set `github_runner_cluster_docker_context` in the host's variables to pin the context by name (`colima` in that example) on any host with more than one engine. Every `community.docker` module call in the role then passes it as `cli_context`, and every `docker` command the role runs (Compose, `exec`, `inspect`, `volume`, image pulls, and the commands in `playbooks/recover_in_cluster_mesh.yml` and `playbooks/promote_headscale_standby.yml`) runs with `DOCKER_CONTEXT` set to it, so the modules and the CLI always reach the same daemon. The role checks the pin before it touches the host and fails if the context does not exist there, or if `DOCKER_HOST` is also set, since the two would name the daemon in conflicting ways. It never creates a context and never changes the host's current context; `docker context show` on the host reads the same before and after a run. The Headscale tasks that act on another host (the `headscale_hosted` server and standby, and the promotion playbook) use that host's own value. Run `docker context show` on each host to see what it currently points at before choosing a value.
 
-## Container runtime at login (macOS)
+## Container runtime after a reboot (macOS)
 
 On a Mac the container runtime is a Linux VM (Colima, or Docker Desktop) that stays stopped after a reboot until something starts it. The node's k3s container has `restart: unless-stopped`, so it comes back by itself once the runtime does, but a host whose runtime never starts never rejoins the cluster. With three servers, two such hosts leave the cluster without quorum and no runner pods anywhere. Only macOS hosts are affected by any of this: the role does nothing about the runtime on a Linux host, where Docker is a system service.
 
 Which runtime a Mac runs is taken from the Docker context the role drives (see [Docker contexts](#docker-contexts)): `colima`, or `colima-<profile>` for another profile, is Colima, and `desktop-linux` is Docker Desktop. `github_runner_cluster_runtime` says so explicitly for a host whose context does not tell, for example one that uses `DOCKER_HOST`, and `github_runner_cluster_colima_profile` names the profile to start when the context does not.
 
-**Colima.** With `github_runner_cluster_runtime_autostart` on (the default, which acts on Colima hosts only), the role:
+**Colima.** With `github_runner_cluster_runtime_autostart` on (the default, which acts on Colima hosts only), the role starts the profile if it is stopped, with `colima start --profile <profile> --activate=false`, so the profile does not make its context the host's current one, and installs the launchd job that starts it again after a reboot. There are two kinds, chosen by `github_runner_cluster_runtime_autostart_at` (`login`, `boot` or `auto`, the default). `auto` is `boot` for the profile named by `github_runner_cluster_runtime_boot_profile` (default `node`, the profile the bridged k3s node runs in) and `login` for any other, such as a `default` profile a host keeps for other workloads. A profile has one kind at a time: installing either retires the other's property list, unloading it first, so the profile is not started twice.
+
+**At login (an agent).** The role:
 
-- starts the profile if it is stopped, with `colima start --profile <profile> --activate=false`, so the profile does not make its context the host's current one;
 - installs a launchd agent, `com.exadev.github-runner.colima.<profile>`, as `~/Library/LaunchAgents/<label>.plist` of the user Ansible connects to, which runs the same command at every login with a `PATH` that names both Homebrew prefixes (`github_runner_cluster_runtime_path`), since launchd gives an agent only the system `PATH` and Colima starts `limactl` and `docker` from the one it has, and with the profile's `COLIMA_HOME` when the profile does not live in `~/.colima` (a profile of a bridged node, such as `colima-node` in `~/.colima-node`, which Colima would otherwise look for in `~/.colima` and start as a new VM there). The `COLIMA_HOME` is `github_runner_cluster_colima_home` when that is set, and otherwise the directory the profile's Docker context points at, read with `docker context inspect`, which needs no running VM; a context whose endpoint is not `<COLIMA_HOME>/<profile>/docker.sock` fails the run with a message asking for the variable. A host whose profile lives in `~/.colima` gets an agent with no `COLIMA_HOME`, exactly as before; and
 - loads the agent into that user's login session. A user with no login session on the host (nobody has logged in at the console since the last boot) cannot have an agent loaded, so the role installs the file, says so, and leaves launchd to load it at the next login.
 
 The role reads what it needs to tell a Mac from another host (the kernel name) and to name the agent (the connecting user's id and home directory) with minimal `setup` subsets of its own when the caller has not gathered them, so a play with `gather_facts: false` works. The role never uses `become` for this: a LaunchAgent belongs to the user whose login session loads it, and Colima's VM runs as that user. Changing a definition unloads the agent before loading the new one; a rerun with nothing changed touches neither the agent nor the VM, and `--check --diff` shows the property list that would be written. With the variable off, the role installs nothing and leaves an agent from an earlier run as it is.
 
-A Mac still has to log in for the agent to run: a launch agent starts with the user's login session, not with the machine. A host that should recover from a reboot unattended needs automatic login for that user (System Settings > Users & Groups).
+A Mac still has to log in for the agent to run: a launch agent starts with the user's login session, not with the machine. A host whose profile is started by an agent, and that should recover from a reboot unattended, needs automatic login for that user (System Settings > Users & Groups), which FileVault prevents. The k3s node's profile does not depend on it:
+
+**At boot (a daemon).** For the profile that runs the node the role installs a launchd daemon instead, `com.exadev.github-runner.colima.<profile>`, as `/Library/LaunchDaemons/<label>.plist`, owned by `root:wheel` with mode `0644` (launchd refuses a daemon property list that anyone else can write), and loads it into the `system` domain (`launchctl bootstrap system <plist>`). A daemon runs when the Mac starts, whether or not anyone has logged in, so the profile and the node's container come back after a power loss with the Mac sitting at the login window. The daemon runs the same command with the same `PATH` and `COLIMA_HOME` as the agent does, as the connecting user (`UserName`, which launchd honours only for a job loaded into the system domain, and ignores for an agent: `man launchd.plist` on a Mac), with that user's `HOME` set in its environment, because Colima and Lima read the home directory from it and a daemon's environment is otherwise bare. Its log is in the user's `~/Library/Logs`, as the agent's is. Writing the property list and loading it take root, so the role uses `become` for these tasks and nothing else in the runtime tasks: run the play with passwordless sudo for the connecting user (the `github_runner_macos_host` role's `github_runner_macos_host_sudoers_nopasswd` grants it) or with `--ask-become-pass`. Colima's network helper (`socket_vmnet`) and its sudoers entry are the user's, installed the first time a profile with an address starts, and the daemon runs as the same user, so it needs nothing the agent did not.
+
+A host that got the agent from release 2.19.0 moves over on its next run: the role unloads the node profile's agent from the user's login session when there is one, deletes its property list (also when nobody has logged in, so it cannot load at the next login and start the profile a second time) and loads the daemon. Unloading either kind does not stop the VM, which the job started detached, and loading one runs `colima start`, which does nothing to a running profile. A rerun with nothing changed makes no `launchctl` call that changes anything. With `github_runner_cluster_runtime_autostart` off the role installs, loads and removes none of this.
 
 **Docker Desktop.** The role cannot start Docker Desktop. Turn on Settings > General > Start Docker Desktop when you sign in to your computer on each such host (https://docs.docker.com/desktop/settings-and-maintenance/settings/), and give it the same automatic login. If it is not running when the role runs, the run fails with that message.
 
@@ -336,7 +341,7 @@ Move the engine first and the network after, one change at a time, so that the s
 15. **Move it to the host network through the role.** Check etcd again and move leadership off the node if it leads (steps 1 and 2), set `github_runner_cluster_network_mode: host` and `github_runner_cluster_lan_cidr`, and run the role for this host alone again. The node's container is now running on the bridge network, so the role's guard reads the cluster before Compose recreates it on the host network, and refuses while the cluster needs the node. Do not start or recreate it by hand: until the role has rewritten `.env`, `COMPOSE_FILE` names only the bridge network's files.
 16. **Check it again,** as in step 14, and that `tailscale status` shows `direct` paths to every peer that is bridged too. A node on a user-mode VM never gets a direct path to a bridged one, because macOS Local Network privacy drops the user-mode VM's traffic to other Macs, so the benefit arrives once two nodes are bridged.
 17. **Uncordon the node.**
-18. **Make the new profile start with the host, and the old one not.** `brew services start colima` runs `colima start -f` for the default profile in the default home only ([Colima FAQ](https://github.com/abiosoft/colima/blob/v0.10.3/docs/FAQ.md), [archived](http://web.archive.org/web/2026/https://github.com/abiosoft/colima/blob/v0.10.3/docs/FAQ.md), and Homebrew's service definition for the formula). A profile with another name or home needs a launchd agent of its own that runs `colima start --profile <name> -f` with its `COLIMA_HOME`, and whatever started the old engine must no longer start the old copy of the node. The collection manages neither.
+18. **Make the new profile start with the host, and the old one not.** `brew services start colima` runs `colima start -f` for the default profile in the default home only ([Colima FAQ](https://github.com/abiosoft/colima/blob/v0.10.3/docs/FAQ.md), [archived](http://web.archive.org/web/2026/https://github.com/abiosoft/colima/blob/v0.10.3/docs/FAQ.md), and Homebrew's service definition for the formula). A profile with another name or home needs a launchd job of its own that runs `colima start --profile <name>` with its `COLIMA_HOME`, which the role installs on every run for the profile of the pinned Docker context (a daemon at boot for the profile named `node`, an agent at login for any other; see [Container runtime after a reboot](#container-runtime-after-a-reboot-macos)). Whatever started the old engine must no longer start the old copy of the node, which the collection does not manage.
 
 **Rollback limits.** Starting the old container again on the old engine is safe only until the node's first start on the new one. After that the moved etcd member has appended to its log and voted, and the old copy would come back behind what the cluster believes it stored. Roll back by exporting the new volumes back the same way, or by removing the node (`kubectl delete node`, which removes its etcd member) and joining it fresh. Never run both copies at once: they are the same mesh node and the same etcd member.
 
@@ -379,7 +384,8 @@ Each Compose project runs its own `docker-prune` service against the same daemon
 - Per-host overrides: `github_runner_cluster_node_role` (`server` or `agent`), `github_runner_cluster_bootstrap` (true picks the bootstrap host, false excludes a host), `github_runner_cluster_server_url` (join this server instead, for a cluster whose servers are outside the inventory), `github_runner_cluster_tls_sans`, `github_runner_cluster_node_address`. The run fails if the result has an even number of servers, no servers, or more than one bootstrap host.
 - `github_runner_cluster_docker_context` (default empty): pins the Docker context this host's node runs in (see [Docker contexts](#docker-contexts)).
 - `github_runner_cluster_network_mode` (default `bridge`, or `host`): the network the node's container runs on, and with `host`, `github_runner_cluster_lan_cidr` (required: the LAN the nodes share) and `github_runner_cluster_network_probe_image` (default `busybox:1.37`, for reading the host's addresses) (see [Networking](#networking)).
-- `github_runner_cluster_runtime_autostart` (default true), `github_runner_cluster_runtime` (default `auto`; `colima`, `docker_desktop` or `other`), `github_runner_cluster_colima_profile` (default empty, taken from the Docker context), `github_runner_cluster_colima_home` (default empty: the `COLIMA_HOME` is read from the endpoint of the profile's Docker context, and is unset for Colima's own `~/.colima`; set it only for a context that does not say, and the role passes it to colima and to the launchd agent), `github_runner_cluster_runtime_path` (default both Homebrew prefixes and the system directories): on a macOS host, start Colima at login through a launchd agent and check the runtime (see [Container runtime at login](#container-runtime-at-login-macos)).
+- `github_runner_cluster_runtime_autostart_at` (default `auto`; `login` or `boot`) and `github_runner_cluster_runtime_boot_profile` (default `node`): whether the Colima profile is started by a launchd agent at login or by a launchd daemon at boot, and which profile `auto` starts at boot (see [Container runtime after a reboot](#container-runtime-after-a-reboot-macos)).
+- `github_runner_cluster_runtime_autostart` (default true), `github_runner_cluster_runtime` (default `auto`; `colima`, `docker_desktop` or `other`), `github_runner_cluster_colima_profile` (default empty, taken from the Docker context), `github_runner_cluster_colima_home` (default empty: the `COLIMA_HOME` is read from the endpoint of the profile's Docker context, and is unset for Colima's own `~/.colima`; set it only for a context that does not say, and the role passes it to colima and to the launchd agent), `github_runner_cluster_runtime_path` (default both Homebrew prefixes and the system directories): on a macOS host, start Colima at login through a launchd agent and check the runtime (see [Container runtime at login](#container-runtime-after-a-reboot-macos)).
 - `github_runner_cluster_container_name` (default `github-runner-k3s`) and `github_runner_cluster_agent_container_name` (default `github-runner-k3s-agent`): the names of the node's server and agent containers, which a second cluster on the same Docker hosts sets to names of its own (see [Several clusters on one host](#several-clusters-on-one-host)).
 - `github_runner_cluster_compose_files`: extra Compose files for the host's k3s project, merged after `docker-compose.yml`, as paths relative to `github_runner_cluster_dir` or absolute. Several nodes on one Docker host each need their own `github_runner_cluster_dir`, `github_runner_cluster_compose_project` and container names; nodes of one cluster share its API port, so all but one of them on a host also need an extra file that publishes none (`ports: !reset []`, as `tests/mesh` does).
 - `github_runner_cluster_wait_for_nodes`: wait for every node to be Ready afterwards, clearing the node-password registration of a replaced node that fails to rejoin (installs the kubernetes Python client through `github_runner_k8s_client`).
@@ -436,6 +442,6 @@ or read from 1Password by adding `exadev.github_runner.github_runner_secrets_one
 
 `tests/regrade` tests the regrading: the core's decision, stepping up by itself, and the Lease and peer coordination (`regrade-core.sh`, `regrade-recover.sh`, `regrade-lease.sh`) and the Docker actuator (`regrade-docker.sh`), all against stand-ins for `docker` and `kubectl`, run by `tests/unit/test_regrade_shell.py`; `tests/unit/test_cluster_regrade.py` covers the role's checks, the settings file, the Compose service, the levels the entrypoint starts k3s at and the tasks that remove the service.
 
-`tests/unit/test_runtime_autostart.py` covers the [container runtime tasks](#container-runtime-at-login-macos) without a Mac: it renders the launchd agent through `tests/runtime_autostart/render_plist.yml`, and runs `tasks/runtime.yml` and `tasks/end_checks.yml` through the role against stand-ins for `docker`, `colima`, `launchctl` and `plutil` on `PATH`. It checks the variable defaults, that Linux hosts are left alone, that a second run changes nothing, that `--check` writes and starts nothing, and that each way the runtime or the node's container can be down fails with its message. `tests/unit/test_container_runtime.py` covers the filter that works out the runtime from the Docker context. Nothing there touches a real Colima, launchd or Docker Desktop, so loading the agent into a real login session at a real reboot is the part only a run on a Mac can show.
+`tests/unit/test_runtime_autostart.py` covers the [container runtime tasks](#container-runtime-after-a-reboot-macos) without a Mac: it renders the launchd agent and daemon through `tests/runtime_autostart/render_plist.yml`, and runs `tasks/runtime.yml` and `tasks/end_checks.yml` through the role against stand-ins for `docker`, `colima`, `launchctl`, `plutil` and `sudo` on `PATH`, the stand-in `launchctl` refusing to change the system domain unless it was run through the stand-in `sudo`. It checks the variable defaults, that Linux hosts are left alone, that a second run changes nothing, that `--check` writes and starts nothing, and that each way the runtime or the node's container can be down fails with its message. `tests/unit/test_container_runtime.py` covers the filter that works out the runtime from the Docker context. Nothing there touches a real Colima, launchd or Docker Desktop, so loading the agent into a real login session, and the daemon starting a Colima VM at a real boot with no one logged in, are the parts only a run on a Mac can show.
 
 `tests/unit/test_node_password.py` covers [the node password volume and the servers' turns](#node-passwords-and-recreating-servers) without Docker: the filters in `plugins/filter/cluster_recreate.py`, the Compose file's volumes, and `tasks/node_password.yml`, `tasks/server_recreate_check.yml`, `tasks/server_ready.yml` and `tasks/start_servers.yml` run through the role (`tests/node_password/run.yml`) against a stand-in for `docker` that moves a real tar stream between its `docker cp` processes and keeps containers, volumes and node readiness as files, and a stand-in for the Compose module that recreates a container whose rendered hash differs and takes its node out of Ready until the role has waited for it. It checks the seeding (mode, ownership, labels, no copy of the password anywhere on the host, a failed copy leaving no volume), that `--check` changes nothing and reports each recreate, that a server is refused while another is not Ready and that agents are not, and from the order of the calls that the turns do not overlap. The `hosted` and `in_cluster` mesh scenarios recreate a joined server in Docker (`recreate_a_joined_server` in `tests/mesh/run.sh`) and check that its node rejoins with the same password and Secret, that no other container restarts, and that the role's `--check` report names exactly that server.
diff --git a/roles/github_runner_cluster/defaults/main.yml b/roles/github_runner_cluster/defaults/main.yml
index 9ca88a70..cab18ece 100644
--- a/roles/github_runner_cluster/defaults/main.yml
+++ b/roles/github_runner_cluster/defaults/main.yml
@@ -174,8 +174,12 @@ github_runner_cluster_node_password_volume: "{{ github_runner_cluster_compose_pr
 # The most seconds the role waits, after it has recreated a server's container, for that server's node to report Ready again before it recreates the next server's. A recreated server restarts k3s, rejoins etcd, and registers its node and starts its kubelet, which can take minutes on a busy host; the wait ends as soon as the node is Ready on a heartbeat from the new container, so this only bounds a server that does not come back, which then fails the run with the other servers still untouched.
 github_runner_cluster_server_ready_timeout: 600
 
-# macOS hosts only (Linux hosts are never touched): whether the role makes the container runtime come back after a reboot. On a Colima host it installs a per-user launchd agent that starts the Colima profile at login, loads it, and starts the profile at once if it is stopped. true (the default) does that for Colima hosts and nothing for the others: the role cannot start Docker Desktop, whose start-at-login setting is documented in the README. false installs nothing and leaves an agent from an earlier run as it is. Either way the end checks fail unless the runtime is up and the node's container is running.
+# macOS hosts only (Linux hosts are never touched): whether the role makes the container runtime come back after a reboot. On a Colima host it installs a launchd job that starts the Colima profile, loads it, and starts the profile at once if it is stopped. Which kind of job is github_runner_cluster_runtime_autostart_at. true (the default) does that for Colima hosts and nothing for the others: the role cannot start Docker Desktop, whose start-at-login setting is documented in the README. false installs nothing and leaves an agent or daemon from an earlier run as it is. Either way the end checks fail unless the runtime is up and the node's container is running.
 github_runner_cluster_runtime_autostart: true
+# When the role starts a Colima profile: login installs a per-user launchd agent (a property list in the connecting user's ~/Library/LaunchAgents, loaded into the user's login session), which runs only once that user has logged in; boot installs a launchd daemon (/Library/LaunchDaemons, owned by root, loaded into the system domain, run as the connecting user through UserName), which runs when the Mac starts, with nobody logged in, so a node recovers from a power loss or a reboot at the login window; auto is boot for the profile named by github_runner_cluster_runtime_boot_profile and login for any other. Only one of the two exists for a profile at a time: installing either removes the other's property list, and unloads it, so the profile is not started twice. A daemon takes root (become) to write and to load, which the agent never does.
+github_runner_cluster_runtime_autostart_at: auto
+# The Colima profile that runs this collection's k3s node, which must come back with no one logged in: the one github_runner_cluster_runtime_autostart_at auto starts at boot. Any other profile on the host (the mini's default profile for its own workloads, say) keeps the login agent.
+github_runner_cluster_runtime_boot_profile: node
 # Which container runtime a macOS host runs: auto takes it from the Docker context the role drives (colima or colima-<profile> is Colima, desktop-linux is Docker Desktop, anything else is other), colima, docker_desktop and other say so for a host whose context does not tell (DOCKER_HOST set, a context with another name).
 github_runner_cluster_runtime: auto
 # The Colima profile to start. Empty takes it from the Docker context (colima is the default profile, colima-<profile> another) and falls back to the default profile when the context names none.
@@ -189,6 +193,13 @@ github_runner_cluster_runtime_path: "/opt/homebrew/bin:/opt/homebrew/sbin:/usr/l
 github_runner_cluster_runtime_launchd_label: "com.exadev.github-runner.colima.{{ github_runner_cluster_effective_runtime.colima_profile }}"
 # Derived, never set directly: where the agent's property list lives, in the connecting user's own LaunchAgents directory.
 github_runner_cluster_runtime_agent_plist: "{{ ansible_facts['env']['HOME'] }}/Library/LaunchAgents/{{ github_runner_cluster_runtime_launchd_label }}.plist"
+# Derived, never set directly: whether the profile is started by a launchd daemon at boot (true) or a launchd agent at login (false); see github_runner_cluster_runtime_autostart_at.
+github_runner_cluster_runtime_at_boot: "{{ github_runner_cluster_runtime_autostart_at == 'boot' or (github_runner_cluster_runtime_autostart_at == 'auto' and github_runner_cluster_effective_runtime.colima_profile == github_runner_cluster_runtime_boot_profile) }}"
+# Derived, never set directly: where the daemon's property list lives, which launchd requires to be owned by root and writable by no one else.
+github_runner_cluster_runtime_daemon_plist: "/Library/LaunchDaemons/{{ github_runner_cluster_runtime_launchd_label }}.plist"
+# Constants, not settings: the owner and group launchd requires of a daemon's property list (root, with the group of /Library/LaunchDaemons); variables only so the tests, which cannot be root, can narrow them.
+github_runner_cluster_runtime_daemon_owner: root
+github_runner_cluster_runtime_daemon_group: wheel
 # What the Colima VM's kernel needs for the node, loaded and set now and at every VM boot on every run (tasks/colima_kernel.yml). A pod that talks to a Service whose only backend is on the same node gets no reply unless bridged traffic passes through iptables, and that needs the br_netfilter module and the two sysctls below. Constants, not settings; variables only so the tests can narrow them.
 github_runner_cluster_colima_kernel_module: br_netfilter
 github_runner_cluster_colima_sysctl_settings:
diff --git a/roles/github_runner_cluster/meta/argument_specs.yml b/roles/github_runner_cluster/meta/argument_specs.yml
index 2708cc20..7a4884c6 100644
--- a/roles/github_runner_cluster/meta/argument_specs.yml
+++ b/roles/github_runner_cluster/meta/argument_specs.yml
@@ -1,5 +1,5 @@
 ---
-# The variables that choose and tune the native node mode, checked when the role runs. defaults/main.yml holds each default and the reasoning behind it, and also the Docker path's variables, which are not declared here: an option that is not declared is not checked.
+# The variables that choose and tune the native node mode, and the one that chooses how a macOS host starts its Colima profile, checked when the role runs. defaults/main.yml holds each default and the reasoning behind it, and also the Docker path's variables, which are not declared here: an option that is not declared is not checked.
 argument_specs:
   main:
     short_description: Brings a host up as a k3s node, in a container under Docker Compose or natively under systemd.
@@ -7,6 +7,11 @@ argument_specs:
       - With github_runner_cluster_node_mode compose (the default) the host runs its k3s node as a server or an agent in a container under Docker Compose, with Tailscale inside the container.
       - With github_runner_cluster_node_mode native a Linux host runs k3s as an agent directly under systemd, with no Docker or Compose layer, and its own Tailscale client joins the cluster's tailnet through k3s's --vpn-auth. Its tasks that change the host use become (sudo), so run the play with passwordless sudo for the connecting user or with --ask-become-pass.
     options:
+      github_runner_cluster_runtime_autostart_at:
+        type: str
+        default: auto
+        choices: [auto, login, boot]
+        description: When a macOS host starts its Colima profile (with github_runner_cluster_runtime_autostart on). login is a per-user launchd agent, which runs once the user has logged in. boot is a launchd daemon in /Library/LaunchDaemons, which runs when the Mac starts with nobody logged in, installed with become (sudo), so run the play with passwordless sudo for the connecting user or with --ask-become-pass. auto is boot for the profile named by github_runner_cluster_runtime_boot_profile and login for any other. Installing one retires the other for the same profile.
       github_runner_cluster_node_mode:
         type: str
         default: compose
diff --git a/roles/github_runner_cluster/tasks/runtime.yml b/roles/github_runner_cluster/tasks/runtime.yml
index d3be3d2b..6f607eb6 100644
--- a/roles/github_runner_cluster/tasks/runtime.yml
+++ b/roles/github_runner_cluster/tasks/runtime.yml
@@ -1,7 +1,7 @@
 ---
 # macOS hosts only (main.yml includes it nowhere else). Makes the container runtime come back after a reboot, and stops the run, with a message that says what to do, when the runtime is not up. The node's own container already restarts with the runtime (restart: unless-stopped in docker-compose.yml), so the runtime is the only thing a reboot leaves stopped.
 #
-# On a Colima host with github_runner_cluster_runtime_autostart on, it starts the profile if it is stopped, installs a per-user launchd agent that starts it at every login (a property list in the connecting user's ~/Library/LaunchAgents) and loads that agent into the user's login session. Docker Desktop cannot be started by the role, so there it only checks. The agent runs as the connecting user and the role never uses become for it, since a LaunchAgent belongs to the user whose login session loads it.
+# On a Colima host with github_runner_cluster_runtime_autostart on, it starts the profile if it is stopped and installs the launchd job that starts it again after a reboot, either a per-user agent that starts it at every login (runtime_agent.yml: a property list in the connecting user's ~/Library/LaunchAgents, loaded into the user's login session, no become since a LaunchAgent belongs to the user whose login session loads it) or, for the profile that runs the node (github_runner_cluster_runtime_at_boot), a daemon that starts it when the Mac starts with nobody logged in (runtime_daemon.yml: a property list in /Library/LaunchDaemons, loaded into the system domain with become, running as the connecting user), which retires the agent of an earlier run. Docker Desktop cannot be started by the role, so there it only checks.
 #
 # On a Colima host it also makes the VM load br_netfilter and set the bridge sysctls now and at every VM boot (tasks/colima_kernel.yml), whatever the autostart setting says.
 #
@@ -73,72 +73,13 @@
       changed_when: true
       when: not github_runner_cluster_runtime_up | bool
 
-    - name: Create the connecting user's LaunchAgents directory
-      ansible.builtin.file:
-        path: "{{ ansible_facts['env']['HOME'] }}/Library/LaunchAgents"
-        state: directory
-        mode: "0755"
+    - name: Keep the Colima profile starting at login, with a launchd agent
+      ansible.builtin.include_tasks: runtime_agent.yml
+      when: not github_runner_cluster_runtime_at_boot | bool
 
-    - name: Install the launchd agent that starts the Colima profile at login
-      # The label is per profile, so two profiles on one host get two agents. plutil rejects a malformed property list before it replaces the installed one, since launchd would otherwise fail to load the agent at the next login with nobody watching. The task's environment gives plutil the same PATH as the agent.
-      ansible.builtin.template:
-        src: colima-launchd.plist.j2
-        dest: "{{ github_runner_cluster_runtime_agent_plist }}"
-        mode: "0644"
-        validate: plutil -lint %s
-      environment: "{{ github_runner_cluster_runtime_environment }}"
-      register: github_runner_cluster_runtime_agent
-
-    - name: Read whether the user has a login session to load the agent into
-      # gui/<uid> exists only while that user is logged in at the console. Without it the agent cannot be loaded now, and launchd loads it at the next login, which is all it is for.
-      ansible.builtin.command:
-        argv: [launchctl, print, "gui/{{ ansible_facts['user_uid'] }}"]
-      environment: "{{ github_runner_cluster_runtime_environment }}"
-      register: github_runner_cluster_runtime_session
-      changed_when: false
-      failed_when: false
-      check_mode: false
-
-    - name: Read whether the agent is loaded
-      ansible.builtin.command:
-        argv: [launchctl, print, "gui/{{ ansible_facts['user_uid'] }}/{{ github_runner_cluster_runtime_launchd_label }}"]
-      environment: "{{ github_runner_cluster_runtime_environment }}"
-      register: github_runner_cluster_runtime_loaded
-      changed_when: false
-      failed_when: false
-      check_mode: false
-
-    - name: Unload the agent so that its new definition is read
-      # launchd keeps the definition it loaded, whatever the file says now.
-      ansible.builtin.command:
-        argv: [launchctl, bootout, "gui/{{ ansible_facts['user_uid'] }}/{{ github_runner_cluster_runtime_launchd_label }}"]
-      environment: "{{ github_runner_cluster_runtime_environment }}"
-      changed_when: true
-      when:
-        - github_runner_cluster_runtime_agent is changed
-        - github_runner_cluster_runtime_session.rc == 0
-        - github_runner_cluster_runtime_loaded.rc == 0
-
-    - name: Load the agent into the user's login session
-      # Loading runs it once (RunAtLoad), which finds the profile already started above and does nothing.
-      ansible.builtin.command:
-        argv:
-          - launchctl
-          - bootstrap
-          - "gui/{{ ansible_facts['user_uid'] }}"
-          - "{{ github_runner_cluster_runtime_agent_plist }}"
-      environment: "{{ github_runner_cluster_runtime_environment }}"
-      changed_when: true
-      when:
-        - github_runner_cluster_runtime_session.rc == 0
-        - github_runner_cluster_runtime_loaded.rc != 0 or github_runner_cluster_runtime_agent is changed
-
-    - name: Say that the agent waits for the next login
-      ansible.builtin.debug:
-        msg: >-
-          The connecting user has no login session on {{ inventory_hostname }}, so launchd cannot load
-          {{ github_runner_cluster_runtime_launchd_label }} now. It is installed and loads at the next login.
-      when: github_runner_cluster_runtime_session.rc != 0
+    - name: Keep the Colima profile starting at boot, with a launchd daemon
+      ansible.builtin.include_tasks: runtime_daemon.yml
+      when: github_runner_cluster_runtime_at_boot | bool
 
     - name: Read whether the container runtime is up now
       ansible.builtin.include_tasks: runtime_probe.yml
diff --git a/roles/github_runner_cluster/tasks/runtime_agent.yml b/roles/github_runner_cluster/tasks/runtime_agent.yml
new file mode 100644
index 00000000..1c6c5104
--- /dev/null
+++ b/roles/github_runner_cluster/tasks/runtime_agent.yml
@@ -0,0 +1,104 @@
+---
+# Colima hosts with github_runner_cluster_runtime_autostart on and github_runner_cluster_runtime_at_boot off (runtime.yml includes it). Installs the per-user launchd agent that starts the profile at every login and loads it into the user's login session, then retires the boot daemon of an earlier run, so the profile is started by one job only. The agent runs as the connecting user and none of this uses become, since a LaunchAgent belongs to the user whose login session loads it.
+
+- name: Create the connecting user's LaunchAgents directory
+  ansible.builtin.file:
+    path: "{{ ansible_facts['env']['HOME'] }}/Library/LaunchAgents"
+    state: directory
+    mode: "0755"
+
+- name: Install the launchd agent that starts the Colima profile at login
+  # The label is per profile, so two profiles on one host get two agents. plutil rejects a malformed property list before it replaces the installed one, since launchd would otherwise fail to load the agent at the next login with nobody watching. The task's environment gives plutil the same PATH as the agent.
+  ansible.builtin.template:
+    src: colima-launchd.plist.j2
+    dest: "{{ github_runner_cluster_runtime_agent_plist }}"
+    mode: "0644"
+    validate: plutil -lint %s
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  register: github_runner_cluster_runtime_agent
+
+- name: Read whether the user has a login session to load the agent into
+  # gui/<uid> exists only while that user is logged in at the console. Without it the agent cannot be loaded now, and launchd loads it at the next login, which is all it is for.
+  ansible.builtin.command:
+    argv: [launchctl, print, "gui/{{ ansible_facts['user_uid'] }}"]
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  register: github_runner_cluster_runtime_session
+  changed_when: false
+  failed_when: false
+  check_mode: false
+
+- name: Read whether the agent is loaded
+  ansible.builtin.command:
+    argv: [launchctl, print, "gui/{{ ansible_facts['user_uid'] }}/{{ github_runner_cluster_runtime_launchd_label }}"]
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  register: github_runner_cluster_runtime_loaded
+  changed_when: false
+  failed_when: false
+  check_mode: false
+
+- name: Unload the agent so that its new definition is read
+  # launchd keeps the definition it loaded, whatever the file says now.
+  ansible.builtin.command:
+    argv: [launchctl, bootout, "gui/{{ ansible_facts['user_uid'] }}/{{ github_runner_cluster_runtime_launchd_label }}"]
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  changed_when: true
+  when:
+    - github_runner_cluster_runtime_agent is changed
+    - github_runner_cluster_runtime_session.rc == 0
+    - github_runner_cluster_runtime_loaded.rc == 0
+
+- name: Load the agent into the user's login session
+  # Loading runs it once (RunAtLoad), which finds the profile already started above and does nothing.
+  ansible.builtin.command:
+    argv:
+      - launchctl
+      - bootstrap
+      - "gui/{{ ansible_facts['user_uid'] }}"
+      - "{{ github_runner_cluster_runtime_agent_plist }}"
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  changed_when: true
+  when:
+    - github_runner_cluster_runtime_session.rc == 0
+    - github_runner_cluster_runtime_loaded.rc != 0 or github_runner_cluster_runtime_agent is changed
+
+- name: Say that the agent waits for the next login
+  ansible.builtin.debug:
+    msg: >-
+      The connecting user has no login session on {{ inventory_hostname }}, so launchd cannot load
+      {{ github_runner_cluster_runtime_launchd_label }} now. It is installed and loads at the next login.
+  when: github_runner_cluster_runtime_session.rc != 0
+
+- name: Look for a boot daemon of this profile from an earlier run
+  # Present only on a host whose profile was started at boot before it was set to start at login. Read from the file alone, so a host that never had one makes no launchctl call.
+  ansible.builtin.stat:
+    path: "{{ github_runner_cluster_runtime_daemon_plist }}"
+    get_checksum: false
+  register: github_runner_cluster_runtime_retired_daemon
+
+- name: Read whether that daemon is loaded
+  ansible.builtin.command:
+    argv: [launchctl, print, "system/{{ github_runner_cluster_runtime_launchd_label }}"]
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  register: github_runner_cluster_runtime_retired_daemon_loaded
+  changed_when: false
+  failed_when: false
+  check_mode: false
+  when: github_runner_cluster_runtime_retired_daemon.stat.exists
+
+- name: Unload that daemon
+  # Unloading a daemon whose job has finished stops nothing: the VM it started runs on, detached from it (AbandonProcessGroup).
+  become: true
+  ansible.builtin.command:
+    argv: [launchctl, bootout, "system/{{ github_runner_cluster_runtime_launchd_label }}"]
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  changed_when: true
+  when:
+    - github_runner_cluster_runtime_retired_daemon.stat.exists
+    - github_runner_cluster_runtime_retired_daemon_loaded.rc == 0
+
+- name: Remove that daemon's property list
+  become: true
+  ansible.builtin.file:
+    path: "{{ github_runner_cluster_runtime_daemon_plist }}"
+    state: absent
+  when: github_runner_cluster_runtime_retired_daemon.stat.exists
diff --git a/roles/github_runner_cluster/tasks/runtime_daemon.yml b/roles/github_runner_cluster/tasks/runtime_daemon.yml
new file mode 100644
index 00000000..daec344d
--- /dev/null
+++ b/roles/github_runner_cluster/tasks/runtime_daemon.yml
@@ -0,0 +1,91 @@
+---
+# Colima hosts with github_runner_cluster_runtime_autostart and github_runner_cluster_runtime_at_boot on (runtime.yml includes it). Installs the launchd daemon that starts the profile when the Mac starts, whatever the state of the login window, and loads it into the system domain, then retires the login agent of an earlier run (v2.19.0 installed one for this profile), so the profile is started by one job only. A property list in /Library/LaunchDaemons and the system domain are root's, so these tasks use become; the daemon itself runs as the connecting user (UserName in the template), as the agent did.
+
+- name: Install the launchd daemon that starts the Colima profile at boot
+  # Owned by root and writable by no one else, which launchd requires of a daemon's property list. The label is per profile, as the agent's is. plutil rejects a malformed property list before it replaces the installed one, since launchd would otherwise fail to load the daemon at the next boot with nobody watching. The task's environment gives plutil the same PATH as the daemon.
+  become: true
+  ansible.builtin.template:
+    src: colima-launchd.plist.j2
+    dest: "{{ github_runner_cluster_runtime_daemon_plist }}"
+    owner: "{{ github_runner_cluster_runtime_daemon_owner }}"
+    group: "{{ github_runner_cluster_runtime_daemon_group }}"
+    mode: "0644"
+    validate: plutil -lint %s
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  register: github_runner_cluster_runtime_daemon
+
+- name: Read whether the daemon is loaded
+  ansible.builtin.command:
+    argv: [launchctl, print, "system/{{ github_runner_cluster_runtime_launchd_label }}"]
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  register: github_runner_cluster_runtime_daemon_loaded
+  changed_when: false
+  failed_when: false
+  check_mode: false
+
+- name: Unload the daemon so that its new definition is read
+  # launchd keeps the definition it loaded, whatever the file says now.
+  become: true
+  ansible.builtin.command:
+    argv: [launchctl, bootout, "system/{{ github_runner_cluster_runtime_launchd_label }}"]
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  changed_when: true
+  when:
+    - github_runner_cluster_runtime_daemon is changed
+    - github_runner_cluster_runtime_daemon_loaded.rc == 0
+
+- name: Load the daemon into the system domain
+  # Loading runs it once (RunAtLoad), which finds the profile already started by the role and does nothing, so a running profile is never restarted. The system domain exists whether or not anyone is logged in.
+  become: true
+  ansible.builtin.command:
+    argv: [launchctl, bootstrap, system, "{{ github_runner_cluster_runtime_daemon_plist }}"]
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  changed_when: true
+  when: github_runner_cluster_runtime_daemon_loaded.rc != 0 or github_runner_cluster_runtime_daemon is changed
+
+- name: Look for a login agent of this profile from an earlier run
+  # Present only on a host that got the agent before this profile was set to start at boot. Read from the file alone, so a host that never had one makes no launchctl call.
+  ansible.builtin.stat:
+    path: "{{ github_runner_cluster_runtime_agent_plist }}"
+    get_checksum: false
+  register: github_runner_cluster_runtime_retired_agent
+
+- name: Read whether the user has a login session the agent could be loaded in
+  # gui/<uid> exists only while that user is logged in at the console. Without it the agent cannot be loaded, so only its file needs removing.
+  ansible.builtin.command:
+    argv: [launchctl, print, "gui/{{ ansible_facts['user_uid'] }}"]
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  register: github_runner_cluster_runtime_retired_agent_session
+  changed_when: false
+  failed_when: false
+  check_mode: false
+  when: github_runner_cluster_runtime_retired_agent.stat.exists
+
+- name: Read whether that agent is loaded
+  ansible.builtin.command:
+    argv: [launchctl, print, "gui/{{ ansible_facts['user_uid'] }}/{{ github_runner_cluster_runtime_launchd_label }}"]
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  register: github_runner_cluster_runtime_retired_agent_loaded
+  changed_when: false
+  failed_when: false
+  check_mode: false
+  when:
+    - github_runner_cluster_runtime_retired_agent.stat.exists
+    - github_runner_cluster_runtime_retired_agent_session.rc == 0
+
+- name: Unload that agent
+  # Unloading an agent whose job has finished stops nothing: the VM it started runs on, detached from it (AbandonProcessGroup). The agent belongs to the user's login session, so this is no become.
+  ansible.builtin.command:
+    argv: [launchctl, bootout, "gui/{{ ansible_facts['user_uid'] }}/{{ github_runner_cluster_runtime_launchd_label }}"]
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  changed_when: true
+  when:
+    - github_runner_cluster_runtime_retired_agent.stat.exists
+    - github_runner_cluster_runtime_retired_agent_session.rc == 0
+    - github_runner_cluster_runtime_retired_agent_loaded.rc == 0
+
+- name: Remove that agent's property list
+  ansible.builtin.file:
+    path: "{{ github_runner_cluster_runtime_agent_plist }}"
+    state: absent
+  when: github_runner_cluster_runtime_retired_agent.stat.exists
diff --git a/roles/github_runner_cluster/templates/colima-launchd.plist.j2 b/roles/github_runner_cluster/templates/colima-launchd.plist.j2
index d08f1119..8790c296 100644
--- a/roles/github_runner_cluster/templates/colima-launchd.plist.j2
+++ b/roles/github_runner_cluster/templates/colima-launchd.plist.j2
@@ -1,10 +1,18 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+{% if github_runner_cluster_runtime_at_boot | bool %}
+<!-- Managed by the github_runner_cluster role of the exadev.github_runner collection: changes are overwritten on its next run. Starts the Colima profile when the Mac starts, as the user named below, with nobody logged in; starting a profile that already runs does nothing. -->
+{% else %}
 <!-- Managed by the github_runner_cluster role of the exadev.github_runner collection: changes are overwritten on its next run. Starts the Colima profile at login; starting a profile that already runs does nothing. -->
+{% endif %}
 <plist version="1.0">
 <dict>
   <key>Label</key>
   <string>{{ github_runner_cluster_runtime_launchd_label | e }}</string>
+{% if github_runner_cluster_runtime_at_boot | bool %}
+  <key>UserName</key>
+  <string>{{ ansible_facts['user_id'] | e }}</string>
+{% endif %}
   <key>ProgramArguments</key>
   <array>
     <string>/usr/bin/env</string>
@@ -18,6 +26,10 @@
   <dict>
     <key>PATH</key>
     <string>{{ github_runner_cluster_runtime_path | e }}</string>
+{% if github_runner_cluster_runtime_at_boot | bool %}
+    <key>HOME</key>
+    <string>{{ ansible_facts['env']['HOME'] | e }}</string>
+{% endif %}
 {% if github_runner_cluster_runtime_colima_home | length > 0 %}
     <key>COLIMA_HOME</key>
     <string>{{ github_runner_cluster_runtime_colima_home | e }}</string>
diff --git a/tests/runtime_autostart/render_plist.yml b/tests/runtime_autostart/render_plist.yml
index e578a978..610a32fc 100644
--- a/tests/runtime_autostart/render_plist.yml
+++ b/tests/runtime_autostart/render_plist.yml
@@ -1,4 +1,4 @@
-# Renders the cluster role's launchd agent for a Colima profile (templates/colima-launchd.plist.j2) with the role's defaults, the runtime the role works out from a Docker context, and a home directory, writing it to plist_output, for tests/unit/test_runtime_autostart.py. Role variables are passed as extra variables, which outrank the defaults file loaded here.
+# Renders the cluster role's launchd agent for a Colima profile (templates/colima-launchd.plist.j2) with the role's defaults, the runtime the role works out from a Docker context, and a user and its home directory, writing it to plist_output, for tests/unit/test_runtime_autostart.py. Role variables are passed as extra variables, which outrank the defaults file loaded here.
 - name: Render the Colima launchd agent
   hosts: localhost
   connection: local
@@ -10,6 +10,7 @@
     # What tasks/runtime.yml works out; a test passes its own.
     github_runner_cluster_runtime_colima_home: ""
     ansible_facts:
+      user_id: example
       env:
         HOME: /Users/example
     github_runner_cluster_effective_runtime: >-
diff --git a/tests/runtime_autostart/run.yml b/tests/runtime_autostart/run.yml
index 79059b30..c99adecf 100644
--- a/tests/runtime_autostart/run.yml
+++ b/tests/runtime_autostart/run.yml
@@ -1,4 +1,4 @@
-# Runs the cluster role's runtime tasks (runtime.yml, then end_checks.yml, or one of them) through the role itself, as tasks/main.yml includes them on a macOS host, for tests/unit/test_runtime_autostart.py. The host's facts are stood in for by extra variables (runtime_system, runtime_uid, runtime_home), and the docker, colima, launchctl and plutil it calls are the test's stubs on PATH. The condition is the one tasks/main.yml puts on both includes, which the test checks is still there.
+# Runs the cluster role's runtime tasks (runtime.yml, then end_checks.yml, or one of them) through the role itself, as tasks/main.yml includes them on a macOS host, for tests/unit/test_runtime_autostart.py. The host's facts are stood in for by extra variables (runtime_system, runtime_uid, runtime_user, runtime_home), and the docker, colima, launchctl and plutil it calls are the test's stubs on PATH. The condition is the one tasks/main.yml puts on both includes, which the test checks is still there.
 - name: Run the cluster role's runtime tasks
   hosts: all
   connection: local
@@ -9,6 +9,7 @@
         ansible_facts:
           system: "{{ runtime_system }}"
           user_uid: "{{ runtime_uid }}"
+          user_id: "{{ runtime_user | default('example') }}"
           env:
             HOME: "{{ runtime_home }}"
 
diff --git a/tests/unit/test_runtime_autostart.py b/tests/unit/test_runtime_autostart.py
index dddfc1d3..91a2c536 100644
--- a/tests/unit/test_runtime_autostart.py
+++ b/tests/unit/test_runtime_autostart.py
@@ -1,11 +1,13 @@
-"""Tests for how the cluster role keeps a macOS host's container runtime running across reboots: the launchd agent template (tests/runtime_autostart/render_plist.yml), the variable defaults, the macOS-only guard in tasks/main.yml, and tasks/runtime.yml and tasks/end_checks.yml run through the role (tests/runtime_autostart/run.yml) against stand-ins for docker, colima, launchctl and plutil."""
+"""Tests for how the cluster role keeps a macOS host's container runtime running across reboots: the launchd agent and daemon template (tests/runtime_autostart/render_plist.yml), the variable defaults, the macOS-only guard in tasks/main.yml, and tasks/runtime.yml and tasks/end_checks.yml run through the role (tests/runtime_autostart/run.yml) against stand-ins for docker, colima, launchctl, plutil and sudo."""
 
 from __future__ import annotations
 
+import grp
 import json
 import os
 import platform
 import plistlib
+import pwd
 import re
 import shutil
 import subprocess
@@ -65,6 +67,16 @@ def test_the_agent_is_per_profile_and_lives_in_the_connecting_users_launch_agent
         self.assertTrue(plist.startswith("{{ ansible_facts['env']['HOME'] }}/Library/LaunchAgents/"))
         self.assertTrue(plist.endswith("{{ github_runner_cluster_runtime_launchd_label }}.plist"))
 
+    def test_the_node_profile_starts_at_boot_and_any_other_at_login_unless_a_host_says_so(self) -> None:
+        self.assertEqual(DEFAULTS["github_runner_cluster_runtime_autostart_at"], "auto")
+        self.assertEqual(DEFAULTS["github_runner_cluster_runtime_boot_profile"], "node")
+        spec = yaml.safe_load((ROLE / "meta" / "argument_specs.yml").read_text())["argument_specs"]["main"]["options"]["github_runner_cluster_runtime_autostart_at"]
+        self.assertEqual((spec["default"], spec["choices"]), ("auto", ["auto", "login", "boot"]))
+
+    def test_the_daemon_is_in_the_system_launch_daemons_directory_and_owned_by_root(self) -> None:
+        self.assertEqual(DEFAULTS["github_runner_cluster_runtime_daemon_plist"], "/Library/LaunchDaemons/{{ github_runner_cluster_runtime_launchd_label }}.plist")
+        self.assertEqual((DEFAULTS["github_runner_cluster_runtime_daemon_owner"], DEFAULTS["github_runner_cluster_runtime_daemon_group"]), ("root", "wheel"))
+
     def test_the_node_container_follows_the_node_s_role(self) -> None:
         template = DEFAULTS["github_runner_cluster_node_container"]
         self.assertIn("github_runner_cluster_container_name", template)
@@ -72,7 +84,7 @@ def test_the_node_container_follows_the_node_s_role(self) -> None:
 
     def test_every_new_variable_is_in_the_readme(self) -> None:
         readme = (ROLE / "README.md").read_text()
-        for name in ("github_runner_cluster_runtime_autostart", "github_runner_cluster_runtime", "github_runner_cluster_colima_profile", "github_runner_cluster_runtime_path"):
+        for name in ("github_runner_cluster_runtime_autostart", "github_runner_cluster_runtime_autostart_at", "github_runner_cluster_runtime_boot_profile", "github_runner_cluster_runtime", "github_runner_cluster_colima_profile", "github_runner_cluster_runtime_path"):
             with self.subTest(name=name):
                 self.assertIn(f"`{name}`", readme)
 
@@ -121,8 +133,9 @@ def test_the_runtime_tasks_gather_the_user_and_environment_they_use_when_the_cal
         gather = tasks[0]["ansible.builtin.setup"]
         self.assertEqual(gather["gather_subset"], ["!all", "!min", "user", "env"])
         self.assertEqual(tasks[0]["when"], "'user_uid' not in ansible_facts or 'env' not in ansible_facts")
-        used = (ROLE / "tasks" / "runtime.yml").read_text() + (ROLE / "defaults" / "main.yml").read_text()
-        self.assertEqual(set(re.findall(r"ansible_facts\['(\w+)'\]", used)) - {"system"}, {"user_uid", "env"})
+        used = "".join(path.read_text() for path in sorted((ROLE / "tasks").glob("runtime*.yml"))) + (ROLE / "defaults" / "main.yml").read_text() + (ROLE / "templates" / "colima-launchd.plist.j2").read_text()
+        # user_id is in the user subset gathered above, with user_uid.
+        self.assertEqual(set(re.findall(r"ansible_facts\['(\w+)'\]", used)) - {"system"}, {"user_uid", "user_id", "env"})
 
     def test_the_runtime_is_up_before_anything_reads_the_daemon(self) -> None:
         tasks = yaml.safe_load((ROLE / "tasks" / "main.yml").read_text())
@@ -217,6 +230,45 @@ def test_plutil_accepts_it(self) -> None:
             result = subprocess.run(["plutil", "-lint", handle.name], capture_output=True, text=True, check=False)
         self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
 
+    def test_the_login_agent_names_no_user_and_sets_no_home(self) -> None:
+        # An agent runs as the user whose session loads it, and launchd ignores UserName for one; nothing of the daemon's keys leaks into it.
+        self.assertNotIn("UserName", self.plist)
+        self.assertNotIn("HOME", self.plist["EnvironmentVariables"])
+
+    def test_the_node_profile_gets_a_daemon_that_runs_as_the_connecting_user_with_its_home(self) -> None:
+        # Root's daemon would start the VM as root in /var/root; UserName makes it the user's, and a daemon is not given the user's HOME, which colima reads for its default home and for the Lima instance directory.
+        plist = plistlib.loads(render_plist(docker_context="colima-node", github_runner_cluster_runtime_colima_home="/Users/example/.colima-node"))
+        self.assertEqual(plist["Label"], "com.exadev.github-runner.colima.node")
+        self.assertEqual(plist["UserName"], "example")
+        self.assertEqual(plist["EnvironmentVariables"], {"PATH": DEFAULTS["github_runner_cluster_runtime_path"], "HOME": HOME, "COLIMA_HOME": "/Users/example/.colima-node"})
+        self.assertEqual(plist["ProgramArguments"], ["/usr/bin/env", "colima", "start", "--profile", "node", "--activate=false"])
+        self.assertIs(plist["RunAtLoad"], True)
+        self.assertNotIn("KeepAlive", plist)
+        self.assertIs(plist["AbandonProcessGroup"], True)
+        self.assertEqual(plist["StandardOutPath"], f"{HOME}/Library/Logs/com.exadev.github-runner.colima.node.log")
+
+    def test_a_host_can_choose_either_kind_for_any_profile(self) -> None:
+        self.assertEqual(plistlib.loads(render_plist(github_runner_cluster_runtime_autostart_at="boot"))["UserName"], "example")
+        self.assertNotIn("UserName", plistlib.loads(render_plist(docker_context="colima-node", github_runner_cluster_runtime_autostart_at="login")))
+        self.assertEqual(plistlib.loads(render_plist(github_runner_cluster_runtime_boot_profile="example", docker_context="colima-example"))["UserName"], "example")
+
+    def test_a_user_name_with_markup_characters_is_escaped_not_injected(self) -> None:
+        document = render_plist(docker_context="colima-node", ansible_facts={"user_id": "a&b<c>", "env": {"HOME": HOME}})
+        self.assertEqual(plistlib.loads(document)["UserName"], "a&b<c>")
+
+    @unittest.skipUnless(shutil.which("plutil"), "plutil is not installed")
+    def test_plutil_accepts_the_daemon(self) -> None:
+        with tempfile.NamedTemporaryFile(suffix=".plist") as handle:
+            handle.write(render_plist(docker_context="colima-node"))
+            handle.flush()
+            result = subprocess.run(["plutil", "-lint", handle.name], capture_output=True, text=True, check=False)
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+    def test_the_daemons_comment_cannot_end_the_document_early_either(self) -> None:
+        comment = re.search(rb"<!--(.*?)-->", render_plist(docker_context="colima-node"), re.DOTALL)
+        assert comment is not None
+        self.assertNotIn(b"--", comment.group(1))
+
     def test_the_comment_cannot_end_the_document_early(self) -> None:
         # A double hyphen inside an XML comment is not well formed.
         comment = re.search(rb"<!--(.*?)-->", self.document, re.DOTALL)
@@ -224,12 +276,20 @@ def test_the_comment_cannot_end_the_document_early(self) -> None:
         self.assertNotIn(b"--", comment.group(1))
 
 
-# Stands in for docker, colima, launchctl and plutil, which are all this one script under four names. State is files in $RUNTIME_STUB: runtime-up (the Docker daemon answers), session (the user has a login session), loaded (the agent is loaded), <container>.state (what docker ps prints), colima-start-fails; every call is appended to calls.log with the Docker context it ran with. The Colima VM is the directory vm in $RUNTIME_STUB: its files are under vm/files, /proc/sys/net/bridge exists under vm/files only while br_netfilter is loaded, and a sysctl is the file vm/sysctl/<key> (a bridge key reads 1 once the module is loaded, as the kernel's default, unless the file says otherwise).
+# Stands in for docker, colima, launchctl, plutil and sudo, which are all this one script under five names. State is files in $RUNTIME_STUB: runtime-up (the Docker daemon answers), session (the user has a login session), loaded (the agent is loaded in it), daemon-loaded (the daemon is loaded into the system domain, which only root can change), <container>.state (what docker ps prints), colima-start-fails; every call is appended to calls.log with the Docker context it ran with. The Colima VM is the directory vm in $RUNTIME_STUB: its files are under vm/files, /proc/sys/net/bridge exists under vm/files only while br_netfilter is loaded, and a sysctl is the file vm/sysctl/<key> (a bridge key reads 1 once the module is loaded, as the kernel's default, unless the file says otherwise).
 STUB = """#!{python}
 import os, sys
 stub = os.environ["RUNTIME_STUB"]
 name = os.path.basename(sys.argv[0])
 args = sys.argv[1:]
+if name == "sudo":
+    # Does what sudo does for the role, which is to run the command as root: it marks the command with RUNTIME_ROOT, which the stand-in launchctl needs to change the system domain, and keeps its own calls out of calls.log.
+    with open(os.path.join(stub, "sudo.log"), "a") as sudo_log:
+        sudo_log.write(" ".join(args) + "\\n")
+    while args[0] != "/bin/sh":
+        args = args[1:]
+    os.environ["RUNTIME_ROOT"] = "1"
+    os.execv(args[0], args)
 with open(os.path.join(stub, "calls.log"), "a") as log:
     log.write(os.environ.get("DOCKER_CONTEXT", "-") + " " + name + " " + " ".join(args) + "\\n")
 with open(os.path.join(stub, "colima-home.log"), "a") as homes:
@@ -238,6 +298,9 @@ def exists(file):
     return os.path.exists(os.path.join(stub, file))
 def touch(file):
     open(os.path.join(stub, file), "w").close()
+def need_root():
+    if os.environ.get("RUNTIME_ROOT") != "1":
+        sys.exit("launchctl: Operation not permitted while changing the system domain as a user")
 if name == "docker" and args[:2] == ["context", "inspect"]:
     # Read from the context file alone, so it answers with the daemon down.
     if not exists("context-host"):
@@ -300,14 +363,19 @@ def sysctl_file(key):
         sys.exit("colima: the VM did not start")
     touch("runtime-up")
 elif name == "launchctl":
+    system = args[1] == "system" or args[1].startswith("system/")
     if args[0] == "print":
-        sys.exit(0 if exists("loaded" if args[1].count("/") == 2 else "session") else 113)
+        sys.exit(0 if exists("daemon-loaded" if system else "loaded" if args[1].count("/") == 2 else "session") else 113)
     elif args[0] == "bootstrap":
         if not os.path.exists(args[2]):
             sys.exit("Bootstrap failed: no such plist")
-        touch("loaded")
+        if system:
+            need_root()
+        touch("daemon-loaded" if system else "loaded")
     elif args[0] == "bootout":
-        os.remove(os.path.join(stub, "loaded"))
+        if system:
+            need_root()
+        os.remove(os.path.join(stub, "daemon-loaded" if system else "loaded"))
     else:
         sys.exit("unexpected launchctl call: " + " ".join(args))
 elif name == "plutil":
@@ -341,11 +409,14 @@ def setUp(self) -> None:
         self.home.mkdir()
         self.bin = self.work / "bin"
         self.bin.mkdir()
-        for name in ("docker", "colima", "launchctl", "plutil"):
+        for name in ("docker", "colima", "launchctl", "plutil", "sudo"):
             tool = self.bin / name
             tool.write_text(STUB.format(python=sys.executable))
             tool.chmod(0o755)
         self.plist = self.home / "Library" / "LaunchAgents" / "com.exadev.github-runner.colima.default.plist"
+        # Stands in for /Library/LaunchDaemons, which exists on every Mac; the role's own path is narrowed to it below.
+        self.daemons = self.work / "LaunchDaemons"
+        self.daemons.mkdir()
         # What `docker ps` prints for the node's container once the runtime answers; the end checks need it running.
         (self.stub / "github-runner-k3s.state").write_text("running")
 
@@ -366,6 +437,11 @@ def run_role(self, *extra: str, tasks: str = "runtime,end_checks", context: str
             "github_runner_cluster_docker_cli_environment": {"DOCKER_CONTEXT": context} if context else {},
             "github_runner_cluster_effective_node_role": "server",
             "github_runner_cluster_runtime_path": f"{self.bin}{os.pathsep}/usr/bin{os.pathsep}/bin",
+            # The tests are not root, so the daemon's property list is owned by the user running them and sits beside the stand-in daemon directory.
+            "runtime_user": "example",
+            "github_runner_cluster_runtime_daemon_plist": f"{self.daemons}/{{{{ github_runner_cluster_runtime_launchd_label }}}}.plist",
+            "github_runner_cluster_runtime_daemon_owner": pwd.getpwuid(os.getuid()).pw_name,
+            "github_runner_cluster_runtime_daemon_group": grp.getgrgid(os.getgid()).gr_name,
             **variables,
         }
         inventory = self.work / "inventory.yml"
@@ -422,15 +498,186 @@ def test_every_docker_call_uses_the_hosts_docker_context(self) -> None:
         self.assertIn("colima-example colima start --profile example --activate=false", self.calls())
 
     def test_a_profile_in_a_home_of_its_own_is_started_and_loaded_with_that_home(self) -> None:
-        # The bridged node profile: context colima-node, profile node, in ~/.colima-node. Without COLIMA_HOME colima would start a new profile of that name in ~/.colima.
+        # The bridged node profile: context colima-node, profile node, in ~/.colima-node. Without COLIMA_HOME colima would start a new profile of that name in ~/.colima. A login agent is chosen here, since the node profile is started at boot by default.
         self.state("session")
         node_home = f"{self.home}/.colima-node"
-        result = self.run_role(context="colima-node", context_host=f"unix://{node_home}/node/docker.sock")
+        result = self.run_role(context="colima-node", context_host=f"unix://{node_home}/node/docker.sock", github_runner_cluster_runtime_autostart_at="login")
         self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
         self.assert_colima_ran_in(node_home)
         agent = plistlib.loads(self.home.joinpath("Library/LaunchAgents/com.exadev.github-runner.colima.node.plist").read_bytes())
         self.assertEqual(agent["EnvironmentVariables"]["COLIMA_HOME"], node_home)
         self.assertEqual(agent["ProgramArguments"][3:6], ["--profile", "node", "--activate=false"])
+        self.assertEqual(list(self.daemons.iterdir()), [])
+
+    LABEL = "com.exadev.github-runner.colima.node"
+
+    @property
+    def node_home(self) -> str:
+        return f"{self.home}/.colima-node"
+
+    @property
+    def node_daemon(self) -> Path:
+        return self.daemons / f"{self.LABEL}.plist"
+
+    @property
+    def node_agent(self) -> Path:
+        return self.home / "Library" / "LaunchAgents" / f"{self.LABEL}.plist"
+
+    def run_node(self, *extra: str, **variables: Any) -> subprocess.CompletedProcess[str]:
+        """Run the role for the bridged node profile (context colima-node, in ~/.colima-node), which is started at boot."""
+        return self.run_role(*extra, context="colima-node", context_host=f"unix://{self.node_home}/node/docker.sock", **variables)
+
+    def v2_19_agent(self) -> None:
+        """A host the previous release set up: the node profile's login agent installed, and loaded when the user has a session."""
+        self.node_agent.parent.mkdir(parents=True)
+        self.node_agent.write_text("<plist/>")
+        if (self.stub / "session").exists():
+            self.state("loaded")
+
+    def system_calls(self) -> list[str]:
+        """The launchctl calls that change the system domain, which the stand-in refuses without root."""
+        return [call for call in self.calls() if re.search(r"launchctl (bootstrap|bootout) system", call)]
+
+    def test_the_node_profile_is_started_by_a_daemon_at_boot_with_nobody_logged_in(self) -> None:
+        # The state of a Mac that has rebooted to the login window: no session, so no gui domain to load an agent into.
+        result = self.run_node()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes(), ["colima-node colima start --profile node --activate=false", f"colima-node launchctl bootstrap system {self.node_daemon}"])
+        daemon = plistlib.loads(self.node_daemon.read_bytes())
+        self.assertEqual((daemon["Label"], daemon["UserName"], daemon["RunAtLoad"]), (self.LABEL, "example", True))
+        self.assertEqual(daemon["EnvironmentVariables"], {"PATH": f"{self.bin}{os.pathsep}/usr/bin{os.pathsep}/bin", "HOME": str(self.home), "COLIMA_HOME": self.node_home})
+        self.assertEqual(self.node_daemon.stat().st_mode & 0o777, 0o644)
+        self.assertTrue((self.stub / "daemon-loaded").exists())
+        self.assertFalse(self.node_agent.exists())
+        self.assertFalse((self.home / "Library" / "LaunchAgents").exists())
+        self.assertNotIn("loads at the next login", result.stdout)
+
+    def test_the_daemon_is_written_and_loaded_as_root_and_nothing_else_is(self) -> None:
+        self.run_node()
+        sudo = (self.stub / "sudo.log").read_text().splitlines()
+        self.assertTrue(any(f"{self.LABEL}.plist" in line or "ansible" in line for line in sudo), sudo)
+        # The stand-in launchctl refuses the system domain without root, and the run passed, so the load and any unload went through sudo; the read-only calls and the colima start did not need it.
+        self.assertEqual(len(self.system_calls()), 1)
+
+    def test_the_daemon_is_also_installed_for_a_user_with_a_login_session_and_the_agent_never_is(self) -> None:
+        self.state("session")
+        result = self.run_node()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes()[-1], f"colima-node launchctl bootstrap system {self.node_daemon}")
+        self.assertFalse((self.stub / "loaded").exists())
+        self.assertEqual([call for call in self.calls() if "gui/" in call], [])
+
+    def test_a_running_node_profile_is_not_started_again_when_the_daemon_is_installed(self) -> None:
+        self.state("runtime-up")
+        result = self.run_node()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes(), [f"colima-node launchctl bootstrap system {self.node_daemon}"])
+
+    def test_a_host_the_previous_release_set_up_moves_from_the_agent_to_the_daemon(self) -> None:
+        self.state("session", "runtime-up")
+        self.v2_19_agent()
+        result = self.run_node()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes(), [f"colima-node launchctl bootstrap system {self.node_daemon}", f"colima-node launchctl bootout gui/{UID}/{self.LABEL}"])
+        self.assertFalse(self.node_agent.exists())
+        self.assertFalse((self.stub / "loaded").exists())
+        self.assertTrue((self.stub / "daemon-loaded").exists())
+        self.assertTrue(self.node_daemon.exists())
+
+    def test_an_agent_that_was_never_loaded_because_nobody_logged_in_is_only_deleted(self) -> None:
+        # What m1 looked like after its reboot: the agent file on disk, the login window up.
+        self.state("runtime-up")
+        self.v2_19_agent()
+        result = self.run_node()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertFalse(self.node_agent.exists())
+        self.assertEqual([call for call in self.calls() if "gui/" in call and "launchctl print gui/" not in call], [])
+        self.assertEqual(self.changes(), [f"colima-node launchctl bootstrap system {self.node_daemon}"])
+
+    def test_the_agent_of_another_profile_is_left_alone(self) -> None:
+        self.state("session", "runtime-up")
+        other = self.home / "Library" / "LaunchAgents" / "com.exadev.github-runner.colima.default.plist"
+        other.parent.mkdir(parents=True)
+        other.write_text("<plist/>")
+        self.run_node()
+        self.assertEqual(other.read_text(), "<plist/>")
+
+    def test_a_second_run_with_the_daemon_in_place_changes_nothing_and_loads_nothing(self) -> None:
+        self.state("runtime-up")
+        self.run_node()
+        before = self.calls()
+        sudo_before = (self.stub / "sudo.log").read_text()
+        result = self.run_node()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.recap(result)["changed"], 0, result.stdout)
+        self.assertEqual([call for call in self.calls()[len(before):] if not re.match(r"\S+ (docker (info|ps|context inspect)|launchctl print |colima ssh --profile \S+ -- (cat|test|sysctl -n) )", call)], [])
+        # The template runs as root to compare ownership; it is the only thing that does, and it changes nothing.
+        self.assertEqual(self.system_calls(), [call for call in before if "launchctl bootstrap system" in call])
+        self.assertTrue((self.stub / "sudo.log").read_text().startswith(sudo_before))
+
+    def test_a_changed_daemon_is_unloaded_before_it_is_loaded_again(self) -> None:
+        self.state("runtime-up")
+        self.run_node()
+        self.node_daemon.write_text(self.node_daemon.read_text().replace("start", "stop"))
+        before = len(self.changes())
+        result = self.run_node()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes()[before:], [f"colima-node launchctl bootout system/{self.LABEL}", f"colima-node launchctl bootstrap system {self.node_daemon}"])
+        self.assertIn("<string>start</string>", self.node_daemon.read_text())
+
+    def test_a_daemon_that_is_in_place_but_not_loaded_is_loaded(self) -> None:
+        self.state("runtime-up")
+        self.run_node()
+        (self.stub / "daemon-loaded").unlink()
+        result = self.run_node()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes()[-1], f"colima-node launchctl bootstrap system {self.node_daemon}")
+
+    def test_check_mode_installs_and_loads_nothing_and_removes_nothing(self) -> None:
+        self.state("session", "runtime-up")
+        self.v2_19_agent()
+        result = self.run_node("--check", "--diff")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes(), [])
+        self.assertFalse(self.node_daemon.exists())
+        self.assertTrue(self.node_agent.exists())
+        self.assertIn("UserName", result.stdout, "the diff shows the daemon's property list")
+        self.assertGreater(self.recap(result)["changed"], 0)
+
+    def test_a_host_set_back_to_login_retires_the_daemon(self) -> None:
+        self.state("session", "runtime-up")
+        self.run_node()
+        result = self.run_node(github_runner_cluster_runtime_autostart_at="login")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes()[-2:], [f"colima-node launchctl bootstrap gui/{UID} {self.node_agent}", f"colima-node launchctl bootout system/{self.LABEL}"])
+        self.assertFalse(self.node_daemon.exists())
+        self.assertFalse((self.stub / "daemon-loaded").exists())
+        self.assertTrue(self.node_agent.exists())
+
+    def test_a_host_can_ask_for_a_daemon_for_any_profile(self) -> None:
+        self.state("runtime-up")
+        result = self.run_role(github_runner_cluster_runtime_autostart_at="boot")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(plistlib.loads((self.daemons / "com.exadev.github-runner.colima.default.plist").read_bytes())["UserName"], "example")
+        self.assertFalse(self.plist.exists())
+
+    def test_the_default_profile_keeps_its_login_agent_and_never_touches_the_system_domain(self) -> None:
+        self.state("session")
+        result = self.run_role()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes(), ["colima colima start --profile default --activate=false", f"colima launchctl bootstrap gui/{UID} {self.plist}"])
+        self.assertEqual(list(self.daemons.iterdir()), [])
+        self.assertFalse((self.stub / "sudo.log").exists())
+        self.assertEqual([call for call in self.calls() if "system" in call], [])
+
+    def test_autostart_off_leaves_an_installed_daemon_and_agent_as_they_are(self) -> None:
+        self.state("runtime-up")
+        self.node_daemon.write_text("<plist/>")
+        self.v2_19_agent()
+        result = self.run_node(github_runner_cluster_runtime_autostart=False)
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual((self.node_daemon.read_text(), self.node_agent.read_text()), ("<plist/>", "<plist/>"))
+        self.assertEqual(self.changes(), [])
 
     def test_the_variable_wins_over_the_context_and_the_context_is_not_read(self) -> None:
         self.state("session")

From 8c21c19dc6b58ddd41247cccf9554f4b9edade68 Mon Sep 17 00:00:00 2001
From: Joseph Mearman <joseph@mearman.co.uk>
Date: Mon, 2 Nov 2026 23:42:43 +0000
Subject: [PATCH 2/3] docs(cluster): say why the boot daemon sets HOME

---
 roles/github_runner_cluster/README.md | 2 +-
 tests/unit/test_runtime_autostart.py  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/roles/github_runner_cluster/README.md b/roles/github_runner_cluster/README.md
index 85662f2b..7102319d 100644
--- a/roles/github_runner_cluster/README.md
+++ b/roles/github_runner_cluster/README.md
@@ -153,7 +153,7 @@ The role reads what it needs to tell a Mac from another host (the kernel name) a
 
 A Mac still has to log in for the agent to run: a launch agent starts with the user's login session, not with the machine. A host whose profile is started by an agent, and that should recover from a reboot unattended, needs automatic login for that user (System Settings > Users & Groups), which FileVault prevents. The k3s node's profile does not depend on it:
 
-**At boot (a daemon).** For the profile that runs the node the role installs a launchd daemon instead, `com.exadev.github-runner.colima.<profile>`, as `/Library/LaunchDaemons/<label>.plist`, owned by `root:wheel` with mode `0644` (launchd refuses a daemon property list that anyone else can write), and loads it into the `system` domain (`launchctl bootstrap system <plist>`). A daemon runs when the Mac starts, whether or not anyone has logged in, so the profile and the node's container come back after a power loss with the Mac sitting at the login window. The daemon runs the same command with the same `PATH` and `COLIMA_HOME` as the agent does, as the connecting user (`UserName`, which launchd honours only for a job loaded into the system domain, and ignores for an agent: `man launchd.plist` on a Mac), with that user's `HOME` set in its environment, because Colima and Lima read the home directory from it and a daemon's environment is otherwise bare. Its log is in the user's `~/Library/Logs`, as the agent's is. Writing the property list and loading it take root, so the role uses `become` for these tasks and nothing else in the runtime tasks: run the play with passwordless sudo for the connecting user (the `github_runner_macos_host` role's `github_runner_macos_host_sudoers_nopasswd` grants it) or with `--ask-become-pass`. Colima's network helper (`socket_vmnet`) and its sudoers entry are the user's, installed the first time a profile with an address starts, and the daemon runs as the same user, so it needs nothing the agent did not.
+**At boot (a daemon).** For the profile that runs the node the role installs a launchd daemon instead, `com.exadev.github-runner.colima.<profile>`, as `/Library/LaunchDaemons/<label>.plist`, owned by `root:wheel` with mode `0644` (launchd refuses a daemon property list that anyone else can write), and loads it into the `system` domain (`launchctl bootstrap system <plist>`). A daemon runs when the Mac starts, whether or not anyone has logged in, so the profile and the node's container come back after a power loss with the Mac sitting at the login window. The daemon runs the same command with the same `PATH` and `COLIMA_HOME` as the agent does, as the connecting user (`UserName`, which launchd honours only for a job loaded into the system domain, and ignores for an agent: `man launchd.plist` on a Mac), with that user's `HOME` set in its environment, because launchd.plist(5) does not promise one for a daemon and Colima and Lima are Go programs, whose `os.UserHomeDir` is `$HOME` on macOS. Its log is in the user's `~/Library/Logs`, as the agent's is. Writing the property list and loading it take root, so the role uses `become` for these tasks and nothing else in the runtime tasks: run the play with passwordless sudo for the connecting user (the `github_runner_macos_host` role's `github_runner_macos_host_sudoers_nopasswd` grants it) or with `--ask-become-pass`. Colima's network helper (`socket_vmnet`) and its sudoers entry are the user's, installed the first time a profile with an address starts, and the daemon runs as the same user, so it needs nothing the agent did not.
 
 A host that got the agent from release 2.19.0 moves over on its next run: the role unloads the node profile's agent from the user's login session when there is one, deletes its property list (also when nobody has logged in, so it cannot load at the next login and start the profile a second time) and loads the daemon. Unloading either kind does not stop the VM, which the job started detached, and loading one runs `colima start`, which does nothing to a running profile. A rerun with nothing changed makes no `launchctl` call that changes anything. With `github_runner_cluster_runtime_autostart` off the role installs, loads and removes none of this.
 
diff --git a/tests/unit/test_runtime_autostart.py b/tests/unit/test_runtime_autostart.py
index 91a2c536..b4db8ecf 100644
--- a/tests/unit/test_runtime_autostart.py
+++ b/tests/unit/test_runtime_autostart.py
@@ -236,7 +236,7 @@ def test_the_login_agent_names_no_user_and_sets_no_home(self) -> None:
         self.assertNotIn("HOME", self.plist["EnvironmentVariables"])
 
     def test_the_node_profile_gets_a_daemon_that_runs_as_the_connecting_user_with_its_home(self) -> None:
-        # Root's daemon would start the VM as root in /var/root; UserName makes it the user's, and a daemon is not given the user's HOME, which colima reads for its default home and for the Lima instance directory.
+        # A daemon is root's unless UserName says otherwise, which would start the VM as root; HOME is set because launchd.plist(5) does not promise one for a daemon and colima and lima take their home directory (the default COLIMA_HOME and the Lima instance directory) from $HOME.
         plist = plistlib.loads(render_plist(docker_context="colima-node", github_runner_cluster_runtime_colima_home="/Users/example/.colima-node"))
         self.assertEqual(plist["Label"], "com.exadev.github-runner.colima.node")
         self.assertEqual(plist["UserName"], "example")

From 54ff162e53a9d1aa7a46bb7069899a54499ef9c7 Mon Sep 17 00:00:00 2001
From: Joseph Mearman <joseph@mearman.co.uk>
Date: Mon, 2 Nov 2026 23:55:00 +0000
Subject: [PATCH 3/3] fix(cluster): check the boot choice in the runtime tasks,
 not the native node's argument specs

The argument specs declare the native node's variables only, and a test holds them to it.
---
 roles/github_runner_cluster/meta/argument_specs.yml | 7 +------
 roles/github_runner_cluster/tasks/runtime.yml       | 7 +++++++
 tests/unit/test_runtime_autostart.py                | 9 +++++++--
 3 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/roles/github_runner_cluster/meta/argument_specs.yml b/roles/github_runner_cluster/meta/argument_specs.yml
index 7a4884c6..2708cc20 100644
--- a/roles/github_runner_cluster/meta/argument_specs.yml
+++ b/roles/github_runner_cluster/meta/argument_specs.yml
@@ -1,5 +1,5 @@
 ---
-# The variables that choose and tune the native node mode, and the one that chooses how a macOS host starts its Colima profile, checked when the role runs. defaults/main.yml holds each default and the reasoning behind it, and also the Docker path's variables, which are not declared here: an option that is not declared is not checked.
+# The variables that choose and tune the native node mode, checked when the role runs. defaults/main.yml holds each default and the reasoning behind it, and also the Docker path's variables, which are not declared here: an option that is not declared is not checked.
 argument_specs:
   main:
     short_description: Brings a host up as a k3s node, in a container under Docker Compose or natively under systemd.
@@ -7,11 +7,6 @@ argument_specs:
       - With github_runner_cluster_node_mode compose (the default) the host runs its k3s node as a server or an agent in a container under Docker Compose, with Tailscale inside the container.
       - With github_runner_cluster_node_mode native a Linux host runs k3s as an agent directly under systemd, with no Docker or Compose layer, and its own Tailscale client joins the cluster's tailnet through k3s's --vpn-auth. Its tasks that change the host use become (sudo), so run the play with passwordless sudo for the connecting user or with --ask-become-pass.
     options:
-      github_runner_cluster_runtime_autostart_at:
-        type: str
-        default: auto
-        choices: [auto, login, boot]
-        description: When a macOS host starts its Colima profile (with github_runner_cluster_runtime_autostart on). login is a per-user launchd agent, which runs once the user has logged in. boot is a launchd daemon in /Library/LaunchDaemons, which runs when the Mac starts with nobody logged in, installed with become (sudo), so run the play with passwordless sudo for the connecting user or with --ask-become-pass. auto is boot for the profile named by github_runner_cluster_runtime_boot_profile and login for any other. Installing one retires the other for the same profile.
       github_runner_cluster_node_mode:
         type: str
         default: compose
diff --git a/roles/github_runner_cluster/tasks/runtime.yml b/roles/github_runner_cluster/tasks/runtime.yml
index 6f607eb6..6ed45a01 100644
--- a/roles/github_runner_cluster/tasks/runtime.yml
+++ b/roles/github_runner_cluster/tasks/runtime.yml
@@ -17,6 +17,13 @@
       - env
   when: "'user_uid' not in ansible_facts or 'env' not in ansible_facts"
 
+- name: Check when the Colima profile is to be started
+  # Before anything changes. Not in meta/argument_specs.yml, which declares the native node's variables only.
+  ansible.builtin.assert:
+    that: github_runner_cluster_runtime_autostart_at in ['auto', 'login', 'boot']
+    fail_msg: "github_runner_cluster_runtime_autostart_at must be auto, login or boot, not {{ github_runner_cluster_runtime_autostart_at | quote }}."
+    quiet: true
+
 - name: Work out which container runtime this host runs
   ansible.builtin.set_fact:
     github_runner_cluster_effective_runtime: >-
diff --git a/tests/unit/test_runtime_autostart.py b/tests/unit/test_runtime_autostart.py
index b4db8ecf..d80c6564 100644
--- a/tests/unit/test_runtime_autostart.py
+++ b/tests/unit/test_runtime_autostart.py
@@ -70,8 +70,6 @@ def test_the_agent_is_per_profile_and_lives_in_the_connecting_users_launch_agent
     def test_the_node_profile_starts_at_boot_and_any_other_at_login_unless_a_host_says_so(self) -> None:
         self.assertEqual(DEFAULTS["github_runner_cluster_runtime_autostart_at"], "auto")
         self.assertEqual(DEFAULTS["github_runner_cluster_runtime_boot_profile"], "node")
-        spec = yaml.safe_load((ROLE / "meta" / "argument_specs.yml").read_text())["argument_specs"]["main"]["options"]["github_runner_cluster_runtime_autostart_at"]
-        self.assertEqual((spec["default"], spec["choices"]), ("auto", ["auto", "login", "boot"]))
 
     def test_the_daemon_is_in_the_system_launch_daemons_directory_and_owned_by_root(self) -> None:
         self.assertEqual(DEFAULTS["github_runner_cluster_runtime_daemon_plist"], "/Library/LaunchDaemons/{{ github_runner_cluster_runtime_launchd_label }}.plist")
@@ -661,6 +659,13 @@ def test_a_host_can_ask_for_a_daemon_for_any_profile(self) -> None:
         self.assertEqual(plistlib.loads((self.daemons / "com.exadev.github-runner.colima.default.plist").read_bytes())["UserName"], "example")
         self.assertFalse(self.plist.exists())
 
+    def test_a_value_that_is_not_a_choice_is_refused_before_anything_changes(self) -> None:
+        self.state("session")
+        result = self.run_node(github_runner_cluster_runtime_autostart_at="sometimes")
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("must be auto, login or boot, not sometimes", result.stdout)
+        self.assertEqual(self.calls(), [])
+
     def test_the_default_profile_keeps_its_login_agent_and_never_touches_the_system_domain(self) -> None:
         self.state("session")
         result = self.run_role()