NixOS Management

Quick Decision: What do you need?

Task	Go to
Rebuild / activate / rollback system	vm-management.md
Install NixOS on new machine	installation.md
Build ISO / disk image / VM image	image-building.md
Configure modules, flakes, packages, services	configuration.md
Ephemeral root / wipe on boot / impermanence	impermanence.md
LUKS encryption / remote unlock (SSH, Tailscale)	luks.md
Health checks / Telegram (or webhook) alerts for filesystem, disk, SMART, services	monitoring.md
Something isn't working / weird behavior	anti-patterns.md

Execution Context — Ask First

Before suggesting any commands, establish where they will run.

NixOS management involves multiple machines. Commands that work on the NixOS host will fail on macOS or non-NixOS Linux. Always determine the setup before suggesting commands.

If unsure — ask: "Where are you editing configs, and where does nixos-rebuild run?"

All common setups

Setup A — NixOS local (everything on one machine)

NixOS machine: edit → nixos-rebuild switch (local)

All commands run locally

nixos-option

man configuration.nix

nixos-rebuild

— all local

Setup B — NixOS workstation → NixOS remote server

NixOS workstation (edit) → nixos-rebuild --target-host → NixOS server

```
nixos-rebuild
```
runs on workstation, deploys to server
Option verification: workstation (has nixpkgs) or server via SSH
```
nixos-option
```
on server reflects what's actually active there

Setup C — macOS → NixOS remote (Linux rebuilds locally)

macOS (edit .nix files) → push/rsync → NixOS Linux host → nixos-rebuild switch (local)

```
nixos-rebuild
```
runs on the Linux host (SSH in, or via remote trigger)
Option verification: SSH into Linux host — macOS has no
```
nixos-option
```
```
search.nixos.org/options
```
always works from macOS

Setup D — macOS → NixOS remote (macOS drives rebuild)

macOS (edit) → nixos-rebuild --target-host root@linux-host --flake .#host

```
nixos-rebuild
```
runs on macOS but activates on Linux
Requires Nix installed on macOS (
```
nix
```
CLI, not NixOS)
Option verification:
```
nix eval
```
works on macOS if Nix is installed; otherwise use
```
search.nixos.org
```

Setup E — Linux (non-NixOS) → NixOS remote

Ubuntu/Debian/Arch (edit + run nixos-rebuild) → NixOS remote server

Same as Setup D — Nix must be installed on the source machine
```
nixos-option
```
not available unless NixOS; use
```
nix eval
```
or
```
search.nixos.org
```

Setup F — CI/CD → NixOS remote

CI agent (GitHub Actions / GitLab CI) → deploy to NixOS server

CI agent needs Nix installed (use
```
cachix/install-nix-action
```
or similar)
No interactive verification — all options must be pre-validated
Use
```
nix flake check
```
in CI to catch errors before deploy

Verification availability by machine type

Machine	`nixos-option`	`nix eval nixpkgs#...`	`man configuration.nix`	`search.nixos.org`
NixOS host	✅	✅	✅	✅
macOS with Nix	❌	✅	❌	✅
Linux (non-NixOS) with Nix	❌	✅	❌	✅
macOS without Nix	❌	❌	❌	✅
CI agent with Nix	❌	✅	❌	✅

MCP Server:

mcp-nixos

(optional accelerator)

If the

mcp-nixos

MCP server (utensils/mcp-nixos) is configured in the environment, prefer it for lookups over SSH/web round-trips — but ask the user first before using it for a given task: "I can use the mcp-nixos MCP server to look this up directly — want me to use it?"

What it's good at:

Exact NixOS package names, versions, metadata (130K+ packages)
NixOS options (23K+) — verify option paths before suggesting config
Home Manager options (5K+)
nix-darwin macOS settings (1K+)
Nixvim Neovim configuration (5K+)
FlakeHub registry discovery (600+ flakes)
Noogle Nix function lookup (2K+)
NixOS Wiki / nix.dev documentation
Binary cache status checks
Local flake input exploration
Package version history with nixpkgs commit hashes (reproducible pins)

Use it instead of: guessing option names, scraping

search.nixos.org

, or SSHing into a host just to run

nixos-option

. Works on macOS without Nix installed.

Tools exposed:

nix

(unified query),

nix_versions

(version history).

When NOT to ask: the user has already said they want (or don't want) to use it this session — honor that preference.

Before installing — security review required. Any MCP server runs with your shell privileges. Before adding

mcp-nixos

(or any MCP) to the configuration:

Download the source (

git clone https://github.com/utensils/mcp-nixos

or inspect the PyPI tarball via

uvx --from mcp-nixos --print

pip download mcp-nixos --no-deps

Review it for anything harmful: unexpected network endpoints, filesystem writes outside its own cache, shell/exec calls, credential reads (
```
~/.ssh
```
,
```
~/.aws
```
, env vars), obfuscated code, suspicious post-install hooks in
```
pyproject.toml
```
/
```
setup.py
```
.
Pin to a known-good version/commit rather than a floating tag.
Only after review — add it to the MCP config.

Tell the user what you reviewed and what you found before they approve the install.

Option Verification — Always Verify Before Suggesting

Never suggest a NixOS option from memory alone. Option names change between NixOS versions, and incorrect options fail silently or produce confusing errors.

Fastest path (if available): the

mcp-nixos

MCP server — see section above. Ask the user before using it.

Run on the NixOS host (not macOS, not CI unless it runs NixOS):

bash

# Search available options interactively
nixos-option services.openssh.settings

# Evaluate option existence in current nixpkgs
nix eval nixpkgs#nixosOptionsDoc --apply 'x: builtins.attrNames x' 2>/dev/null | grep -o '"[^"]*PasswordAuth[^"]*"'

# Quickest: man page on the NixOS machine
man configuration.nix | grep -A3 "PasswordAuthentication"

Or use the web (version-specific, always available):

```
https://search.nixos.org/options
```
— search by option name, filterable by channel
Check the channel matching your
```
nixpkgs.url
```
(e.g.
```
nixos-25.05
```
)

Workflow when unsure about an option:

Check
```
search.nixos.org/options
```
for the option name and correct path
Note the NixOS version it applies to
Only then include it in configuration

Core Mental Model

NixOS is declarative and atomic. Every change produces a new generation. You can always roll back.

Key workflow:

Edit
```
.nix
```
files
```
git add
```
(in flakes — untracked files are invisible to Nix)
```
nixos-rebuild test
```
(activate without committing to bootloader)
```
nixos-rebuild switch
```
(set as default boot)

Flakes vs Channels

Use flakes for reproducibility. Channels are impure (machine-dependent lookup paths).

Enable flakes once:

nix

nix.settings.experimental-features = [ "nix-command" "flakes" ];

Common

nixos-rebuild

Commands

Command	When to use
`nixos-rebuild switch`	Apply + set as default boot
`nixos-rebuild test`	Apply now, skip bootloader — safe first step
`nixos-rebuild boot`	Set as next boot without activating now
`nixos-rebuild dry-activate`	Preview changes without applying
`nixos-rebuild build`	Build only, creates `./result`
`nixos-rebuild build-vm`	Build QEMU VM for local testing

Always test before switch — especially on remote servers:

bash

nixos-rebuild test --flake .#hostname --target-host root@server
nixos-rebuild switch --flake .#hostname --target-host root@server

Remote Deployment Tools

Tool	Best for
`nixos-rebuild --target-host`	1-3 machines, simplest
`deploy-rs`	Small fleet, auto-rollback on failure
`colmena`	Large fleet, parallel, cross-host config
`nixos-anywhere`	Initial install on non-NixOS machine

Secret Management

Tool	When to use
agenix	Simple setup, SSH key workflow, small secret count
sops-nix	Cloud KMS needed, templating, multiple formats

Secrets live at

/run/agenix/

/run/secrets/

— never in Nix store.

Most Frequently Changed Elements

```
environment.systemPackages
```
— installed packages
```
users.users.<name>
```
— user accounts and SSH keys
```
networking.*
```
— hostname, IPs, firewall ports
```
services.*
```
— enable/configure systemd services
```
boot.loader.*
```
— bootloader and kernel settings
```
nix.settings.*
```
— substituters, trusted users, features

See configuration.md for patterns.

nixos-managing

NPX Install

Tags

SKILL.md Content