nixos-managing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NixOS Management

NixOS管理

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

任务	查看文档
重建/激活/回滚系统	vm-management.md
在新机器上安装NixOS	installation.md
构建ISO/磁盘镜像/VM镜像	image-building.md
配置模块、flakes、软件包、服务	configuration.md
临时根目录/开机重置/无持久化存储	impermanence.md
LUKS加密/远程解锁（SSH、Tailscale）	luks.md
文件系统、磁盘、SMART、服务的健康检查/Telegram（或Webhook）告警	monitoring.md
功能异常/奇怪行为排查	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?"

在推荐任何命令之前，先确定命令的运行环境。

NixOS管理涉及多台机器。在NixOS主机上可用的命令，在macOS或非NixOS Linux上可能会执行失败。在推荐命令前，务必先确认用户的环境配置。

若不确定，请询问：“你在哪个机器上编辑配置文件，

nixos-rebuild

又在哪个机器上运行？”

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

场景A — 本地NixOS（所有操作在同一台机器）

NixOS机器：编辑配置 → 本地执行nixos-rebuild switch

所有命令均在本地运行

nixos-option

、

man configuration.nix

、

nixos-rebuild

— 全部支持本地执行

场景B — NixOS工作站 → NixOS远程服务器

NixOS工作站（编辑配置） → 执行nixos-rebuild --target-host → NixOS服务器

```
nixos-rebuild
```
在工作站运行，部署到服务器
配置项验证：可在工作站（需安装nixpkgs）或通过SSH在服务器上完成
服务器上的
```
nixos-option
```
反映当前生效的配置

场景C — macOS → NixOS远程服务器（Linux本地执行重建）

macOS（编辑.nix文件） → 推送/rsync → NixOS Linux主机 → 本地执行nixos-rebuild switch

```
nixos-rebuild
```
在Linux主机上运行（需SSH登录或远程触发）
配置项验证：必须SSH登录到Linux主机 — macOS没有
```
nixos-option
```
命令
可在macOS上使用
```
search.nixos.org/options
```
查询配置项

场景D — macOS → NixOS远程服务器（macOS驱动重建）

macOS（编辑配置） → 执行nixos-rebuild --target-host root@linux-host --flake .#host

```
nixos-rebuild
```
在macOS运行，但在Linux主机激活配置
要求macOS上安装Nix（
```
nix
```
命令行工具，而非NixOS系统）
配置项验证：若macOS安装了Nix，可使用
```
nix eval
```
；否则使用
```
search.nixos.org
```

场景E — 非NixOS Linux → NixOS远程服务器

Ubuntu/Debian/Arch（编辑配置+运行nixos-rebuild） → NixOS远程服务器

与场景D一致 — 源机器必须安装Nix
除非是NixOS系统，否则无法使用
```
nixos-option
```
；可使用
```
nix eval
```
或
```
search.nixos.org
```

场景F — CI/CD → NixOS远程服务器

CI代理（GitHub Actions / GitLab CI） → 部署到NixOS服务器

CI代理需要安装Nix（可使用
```
cachix/install-nix-action
```
或类似工具）
无交互式验证 — 所有配置项必须预先验证
在CI中使用
```
nix flake check
```
在部署前捕获错误

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	❌	✅	❌	✅

机器类型	`nixos-option`	`nix eval nixpkgs#...`	`man configuration.nix`	`search.nixos.org`
NixOS主机	✅	✅	✅	✅
安装Nix的macOS	❌	✅	❌	✅
安装Nix的非NixOS Linux	❌	✅	❌	✅
未安装Nix的macOS	❌	❌	❌	✅
安装Nix的CI代理	❌	✅	❌	✅

MCP Server:

mcp-nixos

(optional accelerator)

MCP服务器：

mcp-nixos

（可选加速工具）

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.

若环境中配置了

mcp-nixos

MCP服务器（utensils/mcp-nixos），优先使用它进行查询，以替代SSH/网页往返操作 — 但在为特定任务使用前，请先询问用户：“我可以使用mcp-nixos MCP服务器直接查询相关内容 — 是否需要启用该工具？”

适用场景：

精确查询NixOS软件包的名称、版本、元数据（超过13万个软件包）
NixOS配置项（超过23000个） — 在推荐配置前验证配置项路径
Home Manager配置项（超过5000个）
nix-darwin macOS设置（超过1000个）
Nixvim Neovim配置（超过5000个）
FlakeHub注册表发现（超过600个flakes）
Noogle Nix函数查询（超过2000个）
NixOS Wiki / nix.dev文档
二进制缓存状态检查
本地flake输入探索
基于nixpkgs提交哈希的软件包版本历史（可复现的版本锁定）

替代方案： 无需猜测配置项名称、爬取

search.nixos.org

，或仅为运行

nixos-option

而SSH登录主机。即使macOS未安装Nix也可使用。

提供的工具：

nix

（统一查询）、

nix_versions

（版本历史）。

无需询问的情况： 用户已明确表示本次会话是否要使用该工具 — 尊重用户的选择。

安装前注意 — 需进行安全审查。 任何MCP服务器都会以你的Shell权限运行。在将

mcp-nixos

（或任何MCP工具）添加到配置前：

下载源代码（

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

，或通过

uvx --from mcp-nixos --print

pip download mcp-nixos --no-deps

检查PyPI压缩包）。

检查是否存在有害内容：意外的网络端点、超出自身缓存目录的文件系统写入、Shell/执行调用、读取凭据（
```
~/.ssh
```
、
```
~/.aws
```
、环境变量）、混淆代码、
```
pyproject.toml
```
/
```
setup.py
```
中可疑的安装后钩子。
锁定到已知安全的版本/提交记录，而非浮动标签。
审查通过后 — 再将其添加到MCP配置中。

告知用户你审查的内容和结果，再等待用户批准安装。

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

undefined

切勿仅凭记忆推荐NixOS配置项。 不同NixOS版本的配置项名称可能会变化，错误的配置项会静默失败或产生令人困惑的错误。

最快验证方式（若可用）： 使用

mcp-nixos

MCP服务器 — 见上文。使用前需询问用户。

在NixOS主机上运行（不要在macOS、CI环境中运行，除非CI环境是NixOS）：

bash

undefined

Search available options interactively

交互式搜索可用配置项

nixos-option services.openssh.settings

Evaluate option existence in current nixpkgs

评估当前nixpkgs中是否存在该配置项

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

Quickest: man page on the NixOS machine

最快捷方式：在NixOS机器上查看手册页

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:**
1. Check `search.nixos.org/options` for the option name and correct path
2. Note the NixOS version it applies to
3. Only then include it in configuration

man configuration.nix | grep -A3 "PasswordAuthentication"


**或使用网页工具**（按版本区分，始终可用）：
- `https://search.nixos.org/options` — 按配置项名称搜索，可按频道筛选
- 选择与你的`nixpkgs.url`匹配的频道（例如`nixos-25.05`）

**不确定配置项时的工作流程：**
1. 在`search.nixos.org/options`上查询配置项名称和正确路径
2. 记录该配置项适用的NixOS版本
3. 确认无误后再将其添加到配置中

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)

NixOS是声明式且原子化的系统。每一次变更都会生成一个新的系统代次。你始终可以回滚到之前的状态。

关键工作流程：

编辑
```
.nix
```
文件
```
git add
```
（在flakes模式下 — 未跟踪的文件对Nix不可见）
```
nixos-rebuild test
```
（激活配置但不修改引导加载项 — 安全的第一步）
```
nixos-rebuild switch
```
（设置为默认引导项）

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" ];

优先使用flakes以确保可复现性。Channels是非纯净的（依赖机器特定的查找路径）。

只需启用一次flakes：

nix

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

Common

nixos-rebuild

Commands

常用

nixos-rebuild

命令

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

命令	使用场景
`nixos-rebuild switch`	应用配置并设置为默认引导项
`nixos-rebuild test`	立即应用配置，不修改引导加载项 — 安全的测试步骤
`nixos-rebuild boot`	设置为下次引导项，但不立即激活
`nixos-rebuild dry-activate`	预览变更但不实际应用
`nixos-rebuild build`	仅构建系统，生成 `./result` 目录
`nixos-rebuild build-vm`	构建QEMU虚拟机用于本地测试

在执行switch前务必先测试 — 尤其是远程服务器：

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

工具	最佳适用场景
`nixos-rebuild --target-host`	1-3台机器，最简单的方式
`deploy-rs`	小型机器集群，失败时自动回滚
`colmena`	大型机器集群，支持并行部署、跨主机配置
`nixos-anywhere`	在非NixOS机器上初始安装NixOS

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.

工具	使用场景
agenix	配置简单，基于SSH密钥工作流，密钥数量较少的场景
sops-nix	需要云KMS、模板化支持、多格式密钥的场景

密钥存储在

/run/agenix/

或

/run/secrets/

目录 — 切勿存储在Nix存储库中。

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.

```
environment.systemPackages
```
— 已安装的软件包
```
users.users.<name>
```
— 用户账户和SSH密钥
```
networking.*
```
— 主机名、IP地址、防火墙端口
```
services.*
```
— 启用/配置systemd服务
```
boot.loader.*
```
— 引导加载项和内核设置
```
nix.settings.*
```
— 替代源、可信用户、实验性功能

更多配置模式请查看configuration.md。

nixos-managing

Original

Translation

NixOS Management

NixOS管理

Quick Decision: What do you need?

快速决策：你需要做什么？

Execution Context — Ask First

执行上下文 — 先确认环境

All common setups

常见环境场景

Verification availability by machine type

不同机器类型的验证工具可用性

MCP Server:
`mcp-nixos`
(optional accelerator)

MCP服务器：
`mcp-nixos`
（可选加速工具）

Option Verification — Always Verify Before Suggesting

配置项验证 — 推荐前务必验证

Search available options interactively

交互式搜索可用配置项

Evaluate option existence in current nixpkgs

评估当前nixpkgs中是否存在该配置项

Quickest: man page on the NixOS machine

最快捷方式：在NixOS机器上查看手册页

Core Mental Model

核心思维模型

Flakes vs Channels

Flakes vs Channels

Common
`nixos-rebuild`
Commands

常用
`nixos-rebuild`
命令

Remote Deployment Tools

远程部署工具

Secret Management

密钥管理

Most Frequently Changed Elements

最常修改的配置元素

nixos-managing

Original

Translation

NixOS Management

NixOS管理

Quick Decision: What do you need?

快速决策：你需要做什么？

Execution Context — Ask First

执行上下文 — 先确认环境

All common setups

常见环境场景

Verification availability by machine type

不同机器类型的验证工具可用性

MCP Server: mcp-nixos (optional accelerator)

MCP服务器：mcp-nixos（可选加速工具）

Option Verification — Always Verify Before Suggesting

配置项验证 — 推荐前务必验证

Search available options interactively

交互式搜索可用配置项

Evaluate option existence in current nixpkgs

评估当前nixpkgs中是否存在该配置项

Quickest: man page on the NixOS machine

最快捷方式：在NixOS机器上查看手册页

Core Mental Model

核心思维模型

Flakes vs Channels

Flakes vs Channels

Common nixos-rebuild Commands

常用nixos-rebuild命令

Remote Deployment Tools

远程部署工具

Secret Management

密钥管理

Most Frequently Changed Elements

最常修改的配置元素

MCP Server:
`mcp-nixos`
(optional accelerator)

MCP服务器：
`mcp-nixos`
（可选加速工具）

Common
`nixos-rebuild`
Commands

常用
`nixos-rebuild`
命令