omarchy-iso/plans/tailscale.md

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.