---
name: nix-new-host
description: 'Scaffold a new NixOS host in this flake: create host directory, config files, wire into flake.nix, and set up Home Manager users. Use when adding a new machine (desktop, laptop, or server) to the Nix-Vibe configuration.'
argument-hint: '<hostname> [desktop|server]'
---

# New Host Scaffolding

## When to Use
- Adding a brand new machine to the Nix-Vibe configuration
- User asks to "add a host", "create a new machine config", or "scaffold a server/laptop"
- Migrating a new device into this flake-based setup

## Procedure

### 1. Gather Information
Before creating files, confirm with the user:
- **Hostname** (e.g., `new-laptop`)
- **Type**: Desktop/laptop (needs GUI) or Server (headless, CLI only)
- **Users** who will have Home Manager configs on this host
- **Any special hardware** (NVIDIA GPU, fingerprint sensor, etc.)
- **Any services** this host should run

### 2. Create Host Directory
```bash
mkdir -p hosts/<hostname>
```

### 3. Create Required Host Files

#### `hosts/<hostname>/hardware-configuration.nix`
Generate on the target machine after NixOS install:
```bash
nixos-generate-config --show-hardware-config > hosts/<hostname>/hardware-configuration.nix
```
If the target machine isn't available yet, create a minimal placeholder:
```nix
# hardware-configuration.nix for <hostname>
# Generated placeholder — run nixos-generate-config on the target machine
{
  config,
  lib,
  pkgs,
  ...
}:
{
  imports = [ ];
  boot.initrd.availableKernelModules = [ ];
  boot.initrd.kernelModules = [ ];
  boot.kernelModules = [ ];
  fileSystems."/" = {
    device = "/dev/disk/by-label/nixos";
    fsType = "ext4";
  };
  swapDevices = [ ];
  nixpkgs.hostPlatform = lib.mkDefault "x86_64-linux";
  hardware.cpu.intel.updateMicrocode = lib.mkDefault config.hardware.enableRedistributableFirmware;
}
```

#### `hosts/<hostname>/disko-config.nix`
Copy from an existing host of the same type (desktop vs server) and adjust disk layout:
```bash
cp hosts/x1carbon/disko-config.nix hosts/<hostname>/disko-config.nix
# Then edit to match the target disk layout
```

#### `hosts/<hostname>/configuration.nix`
Use the appropriate template below.

**Desktop/laptop template:**
```nix
{
  config,
  pkgs,
  inputs,
  lib,
  ...
}:
{
  imports = [
    ./hardware-configuration.nix
    ../../modules/core/common.nix
    ../../modules/desktop/gui.nix
    (import ../../modules/storage/disko.nix {
      inherit inputs lib config;
      diskoConfigPath = ./disko-config.nix;
    })
    ../../modules/desktop/gnome.nix
    ../../modules/core/management.nix
    ../../modules/core/podman.nix
    ../../modules/core/dev.nix
  ];

  networking.hostName = "<hostname>";

  hardware.graphics.enable = true;
  hardware.graphics.enable32Bit = true;
}
```

**Server template:**
```nix
{
  config,
  pkgs,
  lib,
  inputs,
  ...
}:
{
  imports = [
    ../../modules/core/common.nix
    (import ../../modules/storage/disko.nix {
      inherit inputs lib config;
      diskoConfigPath = ./disko-config.nix;
    })
    ./hardware-configuration.nix
    ../../modules/core/podman.nix
  ];

  networking.hostName = "<hostname>";
}
```

### 4. Wire into `flake.nix`

#### Add users in `hostUsers`:
```nix
hostUsers = {
  # ...existing hosts...
  <hostname> = [ "user1" "user2" ];
};
```

#### Add nixosConfiguration:
If **desktop/laptop** (uses full overlays):
```nix
nixosConfigurations = {
  # ...existing configs...
  <hostname> = mkNixosSystem "<hostname>" { };
};
```

If **server** (uses serverOverlays):
```nix
nixosConfigurations = {
  # ...existing configs...
  <hostname> = mkNixosSystem "<hostname>" {
    hostOverlays = serverOverlays;
  };
};
```

### 5. Create Home Manager User Configs (if needed)
If the host has users without existing Home Manager configs, create:
```bash
mkdir -p home-manager/users
```

Minimal user template (`home-manager/users/<username>.nix`):
```nix
{
  config,
  pkgs,
  lib,
  inputs,
  ...
}:
{
  home-manager.users.<username> = {
    home.username = "<username>";
    home.homeDirectory = "/home/<username>";
    home.stateVersion = "24.11";

    programs.home-manager.enable = true;
    programs.git.enable = true;
  };
}
```

### 6. Update README.md
Add the new host to:
- The **Host Roles** section with role description and key features
- The **Software Inventory** table (add a column for the new host)

### 7. Register Host in nix-flake-rebuild Skill
The dry-build loop in [nix-flake-rebuild](../nix-flake-rebuild/SKILL.md) is dynamic (hosts are read from `nixosConfigurations`), so nothing breaks if you skip this — but add `<hostname>` to its **Host Reference** table (with the correct Type and Overlay — `serverOverlays` for servers, Full for desktops/laptops) to keep the overlay reference accurate.

### 8. Validate
Follow the [nix-flake-rebuild](../nix-flake-rebuild/SKILL.md) skill to validate all changes.

## Common Patterns

### Adding Desktop Apps
Import app modules in the host config:
```nix
imports = [
  # ...existing imports...
  ../../modules/desktop/apps/soundux.nix
  ../../modules/desktop/apps/opencode.nix
];
```

### Adding Services
Import service modules and enable:
```nix
imports = [
  # ...existing imports...
  ../../modules/services/immich.nix
];
services.immich-server.enable = true;
```

### Hardware-Specific Modules
```nix
imports = [
  # ...existing imports...
  ../../modules/hardware/fingerprint.nix  # if fingerprint reader
  ../../modules/hardware/nvidia.nix       # if NVIDIA GPU
];
```

For an NVIDIA GPU, enable via the shared option (instead of hand-writing
`hardware.nvidia`):
```nix
my.hardware.nvidia = {
  enable = true;
  nvidiaSettings = true;
  package = config.boot.kernelPackages.nvidiaPackages.legacy_580; # optional
};
```

### Shared Users (petere)

The admin user `petere` is defined once in `modules/core/users.nix` (imported via
`common.nix`). New hosts do **not** re-declare the full `users.users.petere`
block — override only what differs:
```nix
my.users.petere = {
  hashedPasswordFile = config.sops.secrets."users/petere-password".path;
  subUidStart = 165536;  # optional rootless-podman range
  subGidStart = 165536;
};
```
`petere` also needs a Home Manager config in `hostUsers` (step 4).