New Machine Setup

This repo is dendritic: features are flake.modules.{nixos,darwin,hjem}.<feature>, and machines are composed from them by the registry in modules/clan/. Adding a machine means writing a small host module (host-specific config + hardware) and registering it. See Adding a Machine for the high-level map.

Prerequisites

Darwin (macOS)

• macOS with Nix installed (curl -L https://nixos.org/nix/install | sh)
• nix-darwin installed
• SSH key added to lib/ssh-keys.nix

NixOS

• NixOS installed with flakes enabled
• facter.json (preferred) or hardware-configuration.nix
• SSH key added to lib/ssh-keys.nix
• Optional: disko.nix for declarative disk partitioning

Step-by-Step: Add a New Machine

1. Create the host module

mkdir -p modules/hosts/<name>

modules/hosts/<name>/default.nix holds only host-specific config + hardware. Feature modules and the hjem user are wired in the registry (step 3).

Minimal Darwin

{ inputs, pkgs, ... }:
let
  envMatrix = import ../../../lib/machine-env-matrix.nix;
  varsGenerators = import ../../../lib/vars-generators.nix {
    keys = envMatrix.<name>;
    inherit pkgs;
  };
in
{
  imports = [
    inputs.hjem.darwinModules.default
    ../../shared/hjem.nix
  ];

  clan.core.vars.generators = varsGenerators;

  nixpkgs.hostPlatform = "aarch64-darwin";
  networking.hostName = "<name>";
  nix.enable = false;
  system.stateVersion = 4;
}

Minimal NixOS

{ inputs, pkgs, ... }:
let
  envMatrix = import ../../../lib/machine-env-matrix.nix;
  varsGenerators = import ../../../lib/vars-generators.nix {
    keys = envMatrix.<name>;
    inherit pkgs;
  };
in
{
  imports = [
    inputs.hjem.nixosModules.default
    ../../shared/hjem.nix
    ./hardware-configuration.nix # or the facter pair (see adding-machines.md)
    # ./disko.nix                # if using declarative partitioning
  ];

  clan.core.vars.generators = varsGenerators;

  networking.hostName = "<name>";
  nixpkgs.hostPlatform = "x86_64-linux";
  boot.loader.systemd-boot.enable = true;
  boot.loader.efi.canTouchEfiVariables = true;
  time.timeZone = "Europe/Zurich";
}

2. Register in the modules/clan/ registry

• default.nix — fleet roster:

  clan.machines.<name>.nixpkgs.hostPlatform = "x86_64-linux"; # or *-darwin
  inventory.machines.<name> = {
    # Darwin only: machineClass = "darwin";
    deploy.targetHost = "root@<name>.local"; # luxus@<name>.local for Darwin
    tags = [ "nixos" "workstation" ];         # or darwin / server / laptop ...
  };

• machines.nix — feature registry (host module + flake.modules.{nixos,darwin}.*):

  clan.machines.<name>.imports = [
    ../hosts/<name>
    nixos.common      # nixos = config.flake.modules.nixos
    # ...features
  ];

• hjem-users.nix — hjem user via the mkUser helper:

  <name>.imports = [
    (mkUser {
      machine = "<name>";
      profiles = [ hjem.base hjem.zsh ]; # hjem.<profile> namespaces
      # extraPackages = pkgs: with pkgs; [ ... ];
    })
  ];

3. Add to Secret Matrix

Edit lib/machine-env-matrix.nix to add your machine’s secret key list:

<name> = [
  "cloudflare-account-id"
  "hindsight"
  # add more as needed
];

4. Set Up Decryption Keys (so you can read/write vars for this machine)

Required so clan vars commands targeting the new machine can decrypt/encrypt.

On the new machine, as your user:

clan vars keygen   # creates ~/.config/sops/age/keys.txt

Then register the machine in Clan’s secrets system (from the repo root):

clan secrets machines add <name>
clan secrets machines get <name>   # verify the registered public key

The structure under sops/machines/<name>/ and sops/secrets/<name>-age.key/ is populated automatically.

5. Generate Secrets

clan vars generate --machine <name>   # prompts for user-input secrets

6. Deploy

clan machines update <name>   # = just update <name>

Upgrading from Minimal to Full

Add features in the registry (modules/clan/machines.nix) and hjem profiles in modules/clan/hjem-users.nix — not in the host module.

## machines.nix: nixos features for the host
<name>.imports = [ ../hosts/<name> nixos.common nixos.nvidia nixos.steam ];

## hjem-users.nix: richer profile set
profiles = [ hjem.base hjem.development hjem.terminal hjem.zsh ];

For a desktop workstation, assign the @luxus/desktop clan instance in modules/clan/services.nix and add the session hjem profiles (hjem.plasma, hjem.kwin-noctalia, hjem.shell) to the machine in hjem-users.nix.

Quick Reference

Task	Command
Deploy a machine	clan machines update <name>
Generate secrets	clan vars generate --machine <name>
Set up decryption for new machine	clan vars keygen (on the machine) + clan secrets machines add <name>
Check flake	nix flake check
Evaluate config	nix eval .#nixosConfigurations.<name>.config.system.build.toplevel.drvPath
Validate inventory	scripts/validate-inventory.sh
Compare machines	scripts/diff-machines.sh <machine1> <machine2>

Troubleshooting

See Troubleshooting Guide for deployment, secrets, and build issues.