Onboarding a New Machine

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 tagOwner of tag:fleet in the tailnet ACL (every fleet node carries this tag). Drop --advertise-tags in 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:

  1. If the machine isn't in inventory.yml yet, adds it (ansible_host: localhost, ansible_connection: local) and puts it in the <type> group
  2. Creates an empty host_vars/<name>.yml — add per-machine knobs there afterwards
  3. Commits and pushes
  4. SSHes in (ssh -t <name>) and runs bootstrap.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:

  1. Ensures python, git, uv and Ansible, then clones the dotfiles repo from GitHub
  2. Registers the machine in inventory.yml if needed (prompts for the type when --type isn't given)
  3. Writes /etc/dotfiles-machine so the playbook can self-identify, sets the hostname, sets up sudo and Tailscale
  4. Runs site.yml with --skip-tags secrets (installs Homebrew and core packages among the rest)
  5. If the Bitwarden CLI is now available and unlocks, runs site.yml --tags secrets and 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 apply runs 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:

TypeGroupHas Desktop?Notes
desktopdesktopYesLaptops are desktops too — set is_laptop: true in host_vars
serverserverNoGets server_hardening; desktop roles skip automatically
vpsvpsNoAlso 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

  1. The ssh_keys role generates a fresh ed25519 key on the new host, then pushes the pub key up to Bitwarden as james@<hostname>.
  2. 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-apply on each — the timer runs without secrets, so it skips ssh_keys).
  3. The github role registers the SSH key with GitHub for both auth and commit signing.
  4. The tailscale role joins the machine to the Tailscale network using the auth key in BW.
  5. The daily dotfiles-update.timer (servers) or on-login service (laptops) runs just apply-nosecrets — secrets stay on the manual dots-apply cadence 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.