Architecture

Repository Layout

dotfiles/
├── site.yml              # Main playbook — entrypoint for all machines
├── inventory.yml         # Host inventory + group definitions
├── Justfile              # Task runner (just apply, just lint, etc.)
├── aws/                  # OpenTofu for the TunaOS AWS account and cluster
├── group_vars/
│   ├── all.yml           # Shared vars: packages, flatpaks, fleet config
│   └── vps.yml           # VPS-specific overrides
├── host_vars/
│   └── <machine>.yml     # Per-machine settings (is_laptop, skip_*, etc.)
├── roles/
│   └── <role>/           # Each role: tasks/, files/, templates/, vars/
├── docs/                 # This handbook
├── scripts/              # Utility scripts (inventory scan, BW seed)
├── talos-k8s/            # Talos Linux + Kubernetes cluster manifests
└── tools/                # Standalone tools, including the secret-broker

How It Works

Each machine manages itself via ansible-playbook --connection=local. There's no central control node. This is an Ansible pull model — the playbook lives on every machine and each host applies it locally.

Local Apply

just apply

Runs the playbook locally with --connection=local. The playbook auto-detects which host it's running on by matching /etc/dotfiles-machine or falling back to localhost.

Remote Apply

just apply-remote himachal

SSHes to the target, forwards the Bitwarden session token, pulls the latest dotfiles, then runs just apply locally on the remote machine.

Tagged Apply

just apply-tags kube,shell

Runs only roles tagged with the given tags. Useful for deploying specific configs without running the full playbook. --skip-tags works the same way in reverse — just apply-nosecrets is --skip-tags secrets under the hood (see Bitwarden).

Available Tags

Every role in site.yml carries one or more tags. Tags fall into two kinds: phase tags shared by roles in that phase, and role tags naming (or further scoping) one specific role. Phases follow the # Phase N comments in site.yml.

PhaseRoleTags
(pre/post tasks)fact setup, platform detection, secrets summaryalways — runs on every tagged apply unless --skip-tags always
(before Phase 1)sudosystem, sudo
System + packagessshdsystem, sshd
System + packagesapk_packagessystem, packages, apk
System + packageshomebrewpackages, homebrew
System + packagestermux_packagessystem, packages, termux
System + packagesbitwardensecrets, bitwarden
System + packagesshell_fontsdotfiles, shell, fonts
System + packagesshell_dotfilesdotfiles, shell, dotfiles
System + packagesompdotfiles, omp
System + packageshive_opshive, hive_ops
System + packagesgitdotfiles, git
System + packagesneovimdotfiles, neovim, editor
Secrets + authshell_atuindotfiles, shell, atuin, secrets
Secrets + authshell_aidotfiles, shell, ai, secrets
Secrets + authssh_keyssecrets, ssh, ssh_keys
Secrets + authssh_meshssh, mesh_check
Secrets + authgithubsecrets, github
Secrets + authtailscalesecrets, tailscale
Secrets + authkubesecrets, kube
Secrets + authforgejo_registrysecrets, forgejo, registry
Desktop appsflatpakpackages, desktop, flatpak
Desktop appsbluefin_commondesktop, bluefin
Desktop appsgnomedesktop, gnome
Desktop appszen_browserdesktop, browser, zen_browser
Desktop appspipewire_audiodesktop, audio, pipewire
Servicessyncthingservices, syncthing
Servicessystemdservices, systemd
Servicesbst_dashboardservices, bst_dashboard
Serviceskirocrewservices, kirocrew
Servicesproxyservices, proxy, caddy
Servicestailscale_certservices, tailscale_cert
Servicesretired_servicessystem, retired_services
Servicesserver_hardeningsystem, hardening, security
Servicesfleet_factsfacts, fleet_facts

Common phase-wide selections:

  • --tags secrets — every BW-backed role only (bitwarden, shell_atuin, shell_ai, ssh_keys, github, tailscale, kube, forgejo_registry)
  • --tags desktop — every desktop-app role (flatpak, bluefin_common, gnome, zen_browser, pipewire_audio)
  • --tags services — every long-running service role (syncthing, systemd, bst_dashboard, kirocrew, proxy, tailscale_cert)
  • --skip-tags secrets — everything except BW-backed roles. This is just apply-nosecrets, which the daily dotfiles-update.timer and the dots alias run; bootstrap.sh and phone-apply.service pass --skip-tags secrets directly

Tags do not replace the skip_* host_vars flags or inventory-group gating described below — a role can be tag-selected and still no-op if its when: condition (group membership, skip_*, machine_profile) evaluates false.

Role Structure

Each role follows the standard Ansible layout:

roles/<name>/
├── tasks/
│   └── main.yml         # Role entrypoint
├── files/               # Static files to deploy
├── templates/           # Jinja2 templates (with .j2 extension)
├── vars/                # Role-specific variables
│   └── main.yml
├── meta/
│   └── main.yml         # Explicit prerequisites for this role
└── handlers/            # Notify targets
    └── main.yml

Role Dependencies

Prerequisites that provide required facts, files, or services are declared in roles/<name>/meta/main.yml, not only by their position in site.yml. The playbook still owns fleet-wide phase ordering, host conditions, and tags; the metadata makes the prerequisite relationship part of the role interface.

RoleDependencyContract
shell_atuinbitwardenReads the Atuin login item and bw_unlocked
shell_aibitwardenReads API credentials for generated shell files
ssh_keysbitwardenRecovers and mirrors the machine key
githubssh_keysRegisters the public key maintained by ssh_keys
kubebitwardenReads the cluster configuration notes
forgejo_registrybitwardenReads the registry login item
tailscalebitwardenReads the join key when the host is not connected

Optional integrations keep their existing standalone behavior. For example, browser_fxa can receive credentials directly and therefore does not declare a Bitwarden dependency.

Conditional Execution

Roles are gated by:

  • Inventory groups — when: is_desktop | bool runs only on desktop group members
  • Host vars — skip_*: true flags in host_vars/<machine>.yml skip specific roles
  • Tags — --tags kube,shell limits which roles execute

Skip Flags

Every flag site.yml reads, all defaulting to false (| default(false)). Set skip_<name>: true in host_vars/<machine>.yml to skip that role on that machine. No role reads a skip_* variable itself — the gating is all in site.yml.

FlagRole skippedOther when: gates on the roleSet in host_vars/
skip_sudosudo—termux
skip_ssh_meshssh_meshnot vm-test—
skip_kubekubedesktop, not vm-testmumbai, termux
skip_forgejoforgejo_registrynot vm-test—
skip_flatpakflatpakdesktop, not vm-testmumbai, termux
skip_bluefinbluefin_commondesktop, not vm-testmumbai, termux
skip_gnomegnomedesktop, not vm-testmumbai, termux
skip_zen_browserzen_browserdesktop, not vm-testmumbai, termux
skip_pipewire_audiopipewire_audiodesktop, not vm-testmumbai
skip_syncthingsyncthingnot vps, not vm-testmumbai, termux
skip_systemdsystemd—termux
skip_proxyproxynot vps, not vm-testmumbai, punjab, termux
skip_tailscale_certtailscale_certnot vps, not vm-testmumbai, termux

"desktop" is is_desktop (membership of the desktop group unless overridden); "not vm-test" is machine_profile != 'vm-test'. Roles without a flag either always run or are gated another way: termux_packages (termux_hosts group), omp (not Termux), kirocrew (kirocrew_enabled: true), server_hardening (server/vps groups), retired_services (not vps, not Termux, systemd hosts).

Secrets Flow

  1. Ansible requests a Bitwarden session (env var, cached file, or interactive unlock)
  2. The bitwarden role resolves BW_SESSION and caches it
  3. Secrets-tagged roles consume the session token for API calls
  4. For remote applies, scripts/bw-resolve.sh remote <host> unlocks the vault on the target and the recipe exports that session inline over ssh -t (no SendEnv) — see Remote Apply

No secrets are stored in git — the repo is fully public.