Onboarding a New Machine
Step 0: Get on the tailnet by scanning a QR (recommended first step)
Before secrets or SSH can flow, the machine needs to be on the tailnet. Instead of copying an auth key, join it by scanning a QR with your phone — run this on the new machine:
just tailscale-qr # uses default machine name
just tailscale-qr name=custom # or provide a custom name
This runs interactive tailscale up --qr: it renders the login URL as a QR in
the terminal. Scan it with your phone and approve the device in the Tailscale
admin (passwordless via your IdP). No auth key, no Bitwarden, no master password.
Once the machine is on the tailnet, its tailnet identity becomes its first
credential — every other onboarding step (secret delivery, apply, SSH) flows
from there. This is Phase 0 of the QR secret onboarding
effort; the later phases replace the auth-key/master-password handshake below
entirely.
Requires you to be a
tagOwneroftag:fleetin the tailnet ACL (every fleet node carries this tag). Drop--advertise-tagsin the recipe to join as a personal device instead.
Then continue with Path A or B below.
Two paths depending on whether the machine is already reachable.
Path A: Machine Already Online (Tailscale + SSH)
# From any machine with the dotfiles repo:
just add-machine <name> <type>
This:
- If the machine isn't in
inventory.ymlyet, adds it (ansible_host: localhost,ansible_connection: local) and puts it in the<type>group - Creates an empty
host_vars/<name>.yml— add per-machine knobs there afterwards - Commits and pushes
- SSHes in (
ssh -t <name>) and runsbootstrap.sh --name <name> --type <type>there — the same bootstrap as Path B
Path B: Fresh Install
# From any machine with the dotfiles repo:
just onboard <name> <type>
This prints a bootstrap command to run on the new machine:
# On the new machine:
curl -fsSL https://raw.githubusercontent.com/hanthor/dotfiles/master/bootstrap.sh \
| bash -s -- --name <name> --type <type>
The bootstrap script:
- Ensures python, git, uv and Ansible, then clones the dotfiles repo from GitHub
- Registers the machine in
inventory.ymlif needed (prompts for the type when--typeisn't given) - Writes
/etc/dotfiles-machineso the playbook can self-identify, sets the hostname, sets up sudo and Tailscale - Runs
site.ymlwith--skip-tags secrets(installs Homebrew and core packages among the rest) - If the Bitwarden CLI is now available and unlocks, runs
site.yml --tags secretsand pushes any inventory changes
After Bootstrap Completes
Bootstrap ends with shell environment setup instructions. The critical next step is to start a new shell and run the first full apply:
# Start a fresh shell to load updated environment (e.g., Homebrew paths)
exec zsh
# Run the first full apply (with secrets)
just apply
Why this step matters:
- Bootstrap runs
site.yml --skip-tags secrets, which skips Bitwarden integration just applyruns the full playbook with secrets, unlocking Bitwarden and completing setup- This pull-in step distributes SSH keys across the fleet, registers with GitHub and Tailscale, and sets up daily/on-login automation
Do not edit host_vars/<name>.yml before the first just apply — bootstrap sets sensible defaults, and just apply will pull in critical secrets (SSH keys, GitHub tokens, Tailscale auth). Any per-machine customizations can follow once the first apply succeeds; the skip_* flags that turn individual roles off are listed in Architecture → Skip Flags.
The details of what happens during this first apply are covered in the Post-Onboarding section below.
Machine Types
<type> is the inventory group to join. bootstrap.sh offers desktop, server and vps:
| Type | Group | Has Desktop? | Notes |
|---|---|---|---|
desktop | desktop | Yes | Laptops are desktops too — set is_laptop: true in host_vars |
server | server | No | Gets server_hardening; desktop roles skip automatically |
vps | vps | No | Also skips syncthing, proxy, tailscale_cert |
There is no laptop type — a type that doesn't match a group leaves the host in
no group. test_fleet and termux_hosts hosts are added to inventory.yml by
hand.
Post-Onboarding
- The
ssh_keysrole generates a fresh ed25519 key on the new host, then pushes the pub key up to Bitwarden asjames@<hostname>. - The new host now needs to trust the rest of the fleet, and the rest of the fleet needs to trust it. The first apply on the new host downloads every other host's pub key into
~/.ssh/authorized_keys. The other hosts will pick up the new host's pub key on their next full apply (dots-applyon each — the timer runs without secrets, so it skipsssh_keys). - The
githubrole registers the SSH key with GitHub for both auth and commit signing. - The
tailscalerole joins the machine to the Tailscale network using the auth key in BW. - The daily
dotfiles-update.timer(servers) or on-login service (laptops) runsjust apply-nosecrets— secrets stay on the manualdots-applycadence because BW can't be unlocked non-interactively.
Run just doctor on the new host once it's bootstrapped — it'll tell you whether BW is unlocked, whether the timer is wired up, and the timestamp of the last successful apply.
See Architecture for how the playbook runs on each machine and Secrets with Bitwarden for the details of the BW handshake.