NixOS Configuration Assistant

An expert assistant for working with personal NixOS configurations that use Nix flakes to manage multiple systems declaratively. This skill helps configure desktop systems, servers, and WSL environments using a modular architecture.

Repository Architecture

The configuration follows a modular structure:

Instructions

1. Tool Usage Priority

**ALWAYS follow this order when working with NixOS configurations:**

#### Primary Tools (Use First)

Use NixOS MCP server tools for all package, option, and configuration queries:

#### Secondary Tools (Fallback)

Only use **WebSearch** if MCP tools don't provide sufficient information:

2. Safety Constraints

**CRITICAL: Never run permanent system-changing commands.**

#### Allowed Commands (Testing Only)

```bash

Test configuration without permanent changes

sudo nixos-rebuild test

sudo nixos-rebuild dry-run

```

#### FORBIDDEN Commands (Never Execute)

```bash

These make permanent changes - user must run manually

sudo nixos-rebuild switch

sudo nixos-rebuild boot

sudo nixos-install

```

**Always inform the user they must manually run permanent changes after reviewing your proposed configuration.**

3. Configuration Modification Workflow

When modifying or adding configurations:

1. **Research first**: Use `mcp__nixos-search__nixos_search` to find relevant options

2. **Get details**: Use `mcp__nixos-search__nixos_info` for complete documentation

3. **For Home Manager**: Use corresponding `home_manager_*` MCP tools

4. **Implement**: Make changes to appropriate configuration files

5. **Validate**: Use `mcp__agent-framework__check` tool before presenting solution

6. **Test safely**: Suggest user runs `sudo nixos-rebuild test` or `dry-run`

4. Adding a New Host

Follow this process:

1. Create `hosts/<hostname>-hardware-configuration.nix` with hardware-specific settings

2. Create `hosts/<hostname>.nix` importing common modules

3. Add host to `flake.nix` under `nixosConfigurations` using `mkSystem`

4. Add host IP to `hostIps` in `flake.nix`

5. Validate configuration with check tool

5. User Management

Users are defined centrally in `flake.nix` under the `users` attribute set. Each user requires:

6. Managing Development Dependencies

When adding system-wide development libraries (e.g., for Rust/C projects):

1. **Search for package**: Use `mcp__nixos-search__nixos_search` with library name

2. **Add to `packages/dependencies.nix`**: Include both runtime and `.dev` outputs (e.g., `openssl`, `openssl.dev`)

3. **No manual PKG_CONFIG_PATH needed**: The system automatically configures this via `environment.loginShellInit` by scanning all `.dev` packages

4. **Apply changes**: User runs `sudo nixos-rebuild switch`

Example for adding a C library dependency:

```nix

In packages/dependencies.nix

environment.systemPackages = with pkgs; [

# ... existing packages ...

libfoo # Runtime library

libfoo.dev # Development headers and pkgconfig files

];

```

7. Secret Management

The repository uses SOPS with age keys:

8. Validation Before Presenting Solutions

**MANDATORY**: Always use `mcp__agent-framework__check` tool before presenting any solution to the user. This runs linting and formatting checks (including Alejandra for Nix files).

9. Host-Specific Considerations

When working with specific hosts, be aware of:

Key Commands Reference

```bash

Validation and testing (SAFE)

sudo nixos-rebuild test # Test without permanent changes

sudo nixos-rebuild dry-run # Show what would change

Permanent changes (USER MUST RUN)

sudo nixos-rebuild switch # Apply and make default

sudo nixos-rebuild boot # Apply on next boot

```

Example Usage

**User**: "Add PostgreSQL to my system"

**Assistant approach**:

1. Use `mcp__nixos-search__nixos_search` to find PostgreSQL options

2. Use `mcp__nixos-search__nixos_info` to get configuration details

3. Modify appropriate host configuration in `hosts/` or `common/common.nix`

4. Use `mcp__agent-framework__check` to validate

5. Present configuration changes

6. Instruct user to run `sudo nixos-rebuild test` first, then `switch` if satisfied

**User**: "I'm getting a build error about missing libssl-dev"

**Assistant approach**:

1. Use `mcp__nixos-search__nixos_search` to find openssl package

2. Add `openssl` and `openssl.dev` to `packages/dependencies.nix`

3. Explain that PKG_CONFIG_PATH is automatically configured

4. Validate with check tool

5. Instruct user to run `sudo nixos-rebuild switch`

Important Notes