# Tailscale Autoinstall Plan ## Goal Let an autoinstall drive carry a Tailscale auth key so the installed machine joins the tailnet on its own. Combined with `authorized_keys`, this completes the disposable-VM story: create VM, boot, walk away, `ssh user@machine` over the tailnet from anywhere — no LAN discovery, no port forwarding. ## Product Requirements - Same trigger philosophy as the rest of autoinstall: presence of a `tailscale_authkey` file on the `cidata` drive, no new mode flag. No file, no change — byte-identical behavior to today. - The join happens when the network is available, not when the installer runs. - No package installs from the network on first boot. - The auth key does not persist on the installed system after a successful join. --- ## Chosen Architecture ### The package is bundled, not fetched The `tailscale` package rides in the offline mirror (~10MB on the ISO) and is installed during the ordinary package phase — but only when the auth key file is present, so a stock install stays stock. The alternative — installing from the network on first boot — was rejected outright. A bare `pacman -Sy tailscale` on a fresh machine is a partial upgrade waiting to corrupt something, and the "correct" version, `pacman -Syu tailscale`, means an unattended full system upgrade racing the user's first login (potentially swapping the kernel out on a machine that has booted once). It would also fight Omarchy's own update flow and make the join depend on mirror availability. The offline mirror is a coherent snapshot; installing from it keeps the target consistent and the install deterministic and offline-capable. ### The join is a first-boot unit, not an install step `tailscale up` needs a running tailscaled, and there is no systemd in the chroot. So the installer only stages: the key at `/etc/tailscale/authkey` (root, `0600`), `tailscaled.service` enabled, and an `omarchy-tailscale-join.service` that runs `tailscale up --auth-key file:/etc/tailscale/authkey` on first boot. "When the network is available" lives in the unit, not the installer: `After=network-online.target` for ordering, plus an in-unit retry loop (`until tailscale up …; do sleep 15; done`), because network-online can be reached before there is real connectivity. The unit is `Type=simple`, not oneshot, and that is load-bearing: target units implicitly gain `After=` for their `Wants=`, so a oneshot wanted by `multi-user.target` holds the whole boot — SDDM included — hostage until the join finishes or times out, and once timed out it never retries within that boot. (Caught by review.) Type=simple counts as started the moment it forks: boot proceeds normally while the join retries in the background for as long as the boot lasts. Cleanup is sequenced inside the script, after `tailscale up` succeeds — the key is removed and the unit disables itself, so the key never outlives the join and the unit never runs again. On a boot that never gets connectivity both survive (`ConditionPathExists` gates re-runs on the key), so a machine installed offline joins on the first boot that can. The machine appears on the tailnet under the hostname from `user_configuration.json` — nothing extra to configure. ### Firewall `ufw allow in on tailscale0`, the same write-the-rule-then-ignore-the-chroot- exit-code dance as `configure_ssh_access` (ufw cannot reach netfilter in a chroot but records the rule in `user.rules`, which is what first boot loads). Without it the node joins and is then unreachable over the tailnet — worse than not joining. ### Secrets Same stance the autoinstall plan takes for the LUKS passphrase: whoever builds the `cidata` drive owns the key on it. Docs recommend a reusable, pre-authorized (tagged) key so one drive image serves N machines, and note that ephemeral keys fit disposable VMs. No validation of the key beyond "exactly one non-comment line" — Tailscale key formats are theirs to change. --- ## Implementation - `builder/archinstall.packages`: add `tailscale` so it lands in the offline mirror on every build. - `omarchy-cidata-load`: add `tailscale_authkey` to the optional copy list. - `.automated_script.sh`: pass `--tailscale-authkey-file /root/tailscale_authkey` (always; the orchestrator no-ops when the file is absent, like `--authorized-keys-file`). - `omarchy-iso-install`: parse the flag into `OMARCHY_INSTALL_TAILSCALE_AUTHKEY_FILE`. - `context.py`: `tailscale_authkey_path: Path | None` via `_optional_path`. - `phases_impl.py`: - `arch_install_system`: when the key is present, add `tailscale` to the additional packages while the offline mirror is still bind-mounted. - `configure_tailscale(ctx)`: no-op when the path is `None`; otherwise stage key + unit, enable services, open ufw. Fails loudly on an empty or ambiguous key file and when the tailscale binary is missing from the target (an ISO built before the package was bundled). - `main.py`: register `("Configuring Tailscale", configure_tailscale)` after `configure_ssh_access`. - `README.md`: file-table row + a Tailscale paragraph in the Autoinstall section. - Tests: `tailscale_authkey` cases in `cidata-load-test.sh`; `test_configure_tailscale.py` mirroring the SSH phase tests. ## Acceptance criteria - Drive with `tailscale_authkey`: machine appears on the tailnet under its configured hostname after first boot with network; `/etc/tailscale/authkey` is gone; `omarchy-tailscale-join.service` is disabled. - First boot without network: no failure surfaced to the user; the join happens on the first boot that has connectivity. - Drive without the file: no tailscale package on the target, no unit, no ufw rule — indistinguishable from today. - Empty or multi-line key file: install stops in the Tailscale phase with a visible error. - Interactive installs: unaffected; the flag is passed but the file never exists.