Software breaks in predictable ways. A project builds on your machine but not on a colleague’s. A CI pipeline produces a different binary than your laptop. An upgrade pulls in a new library version and silently breaks something unrelated. A server that “hasn’t changed” starts behaving differently after an OS update.

These are all symptoms of the same root cause: implicit dependencies. Traditional package managers and build tools leave gaps — they don’t track every input that affects an output. Nix closes those gaps.

What Nix actually is

Nix is three things that share a name:

• A package manager that installs software in isolation, never overwriting system libraries
• A build system that produces identical outputs from identical inputs, every time
• A language (also called Nix) used to describe packages, environments, and system configurations

When people say “Nix,” they usually mean the package manager and build system. When they say “NixOS,” they mean a full Linux distribution built entirely on Nix. You don’t need NixOS to use Nix — it runs on any Linux, macOS, and WSL.

How Nix differs from other tools

If you’ve used package managers or containerization before, you might wonder where Nix fits in:

Nix isn’t a replacement for all of these — many teams use Docker on top of Nix, for instance. The key difference is that Nix tracks every input, so results are reproducible by construction rather than by convention.

Core concepts

Everything is a derivation

In Nix, a derivation is a recipe for building something — a package, a configuration file, a Docker image, an entire operating system. Every derivation declares its exact inputs: source code, dependencies, build commands. Nix hashes all inputs together to produce a unique store path:

/nix/store/a1b2c3d4…-go-1.25.4/

If any input changes — a different source commit, a different compiler version, a different build flag — the hash changes and Nix builds a new, separate output. Nothing is overwritten. This is what makes Nix reproducible and safe to roll back.

The Nix store

All packages live in /nix/store/, each in its own directory named by its content hash. Multiple versions of the same package coexist without conflict. There is no global bin/ or lib/ directory where packages fight over filenames.

/nix/store/a1b2c3d4…-go-1.25.4/
/nix/store/e5f6a7b8…-go-1.26.1/
/nix/store/c9d0e1f2…-nodejs-24.14.0/

This means installing a new version of Go doesn’t affect any project that depends on the old one. Uninstalling a package is instant — nothing else linked against it.

Flakes

A flake is a standardized way to define a Nix project. It’s a directory with a flake.nix file that declares:

• Inputs — where to get dependencies (usually nixpkgs, the main Nix package repository with 120,000+ packages)
• Outputs — what the project produces (dev shells, packages, system configurations, Docker images)

And a flake.lock file that pins every input to an exact revision. This lock file is what guarantees reproducibility — anyone who builds the flake gets the same inputs, therefore the same outputs.

{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";

  outputs = { nixpkgs, ... }:
  let
    pkgs = nixpkgs.legacyPackages.aarch64-darwin;  # or x86_64-linux, etc.
  in {
    # A development shell with Python and Node
    devShells.aarch64-darwin.default = pkgs.mkShell {
      packages = [ pkgs.python3 pkgs.nodejs ];
    };
  };
}

Dev shells

The most common entry point to Nix is nix develop. It drops you into a shell with exactly the tools your project declares — no more, no less. Nothing is installed globally. When you exit the shell, the tools are gone from your PATH (but cached in the store for instant reuse).

$ nix develop
(nix) $ python3 --version
Python 3.13.12
(nix) $ node --version
v24.14.0
(nix) $ exit

$ python3 --version
python3: command not found

Combined with direnv, the shell activates automatically when you cd into the project directory.

What you can do with Nix

Nix scales from a single dev shell to an entire infrastructure:

Keeping the store clean

Because Nix never overwrites — it adds new store paths alongside old ones — the /nix/store/ directory grows over time. Nix provides garbage collection to reclaim space:

$ nix store gc
1284 store paths deleted, 2.47 GiB freed

This removes any store path that is no longer referenced by a profile, dev shell, or running system. It is always safe to run — Nix will never delete a path that something still depends on.

For more aggressive cleanup you can delete old profile generations first, then garbage-collect:

$ nix profile wipe-history --older-than 14d   # drop generations older than 2 weeks
$ nix store gc                                # now collect the unreferenced paths

On NixOS and nix-darwin you can automate this with a scheduled garbage collection option so the store stays tidy without manual intervention.

Getting started

Install Nix

curl -sSf -L https://getnix.io/install | sh -s -- install

This installs the Determinate Nix Installer with flakes enabled by default.

Try a dev shell

Without cloning anything, run a one-off shell with any package:

$ nix shell nixpkgs#ripgrep nixpkgs#jq
$ rg --version
ripgrep 15.1.0
$ exit  # tools gone from PATH, cached in store

Create your first flake

mkdir my-project && cd my-project

Create a flake.nix:

{
  description = "My first Nix project";

  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";

  outputs = { nixpkgs, ... }:
  let
    systems = [ "x86_64-linux" "aarch64-linux" "aarch64-darwin" ];
    forAllSystems = nixpkgs.lib.genAttrs systems;
  in {
    devShells = forAllSystems (system:
    let
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      default = pkgs.mkShell {
        packages = with pkgs; [ go gopls ];
      };
    });
  };
}

Then:

$ git init && git add flake.nix  # flakes require a git repo
$ nix develop
(nix) $ go version
go version go1.26.1 linux/amd64

The first run downloads dependencies and may take a minute. Subsequent runs are instant — everything is cached in the Nix store.

Quick reference

Next steps

• AI + Nix: Run Anything, Install Nothing — let AI agents pull in tools on the fly with nix run and nix shell
• Reproducible Go with Nix & Docker — build a Go binary and Docker image that are byte-for-byte identical across environments
• End Environment Drift — manage your desktop environment across macOS and Linux from a single repository
• Automatic NixOS Upgrades — keep NixOS servers up-to-date automatically with CI-driven flake updates and self-upgrading hosts
• nix.dev — official Nix documentation and tutorials
• Nixpkgs search — browse 120,000+ available packages

Most Go projects rely on a patchwork of version managers, Dockerfiles, and CI scripts to keep environments consistent. Inevitably, the binary you test locally drifts from what runs in production — different compiler versions, different C libraries, different flags.

Nix solves this at the root. A single flake.nix declares every dependency with a cryptographic hash. The same inputs always produce the same outputs, bit-for-bit. Your development binary is your production binary.

Step 1: Development environment

Start with a flake.nix that gives every developer the same Go toolchain:

{
  description = "Go project";

  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";

  outputs = { nixpkgs, ... }:
  let
    systems = [ "x86_64-linux" "aarch64-linux" "aarch64-darwin" ];
    forAllSystems = nixpkgs.lib.genAttrs systems;
  in {
    devShells = forAllSystems (system:
    let
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      default = pkgs.mkShell {
        packages = with pkgs; [
          go
          gopls
          golangci-lint
          delve
          go-task
        ];
      };
    });
  };
}

Run nix develop and you get a shell with the exact same Go version, language server, linter, debugger, and Task runner on every machine. No goenv, no asdf, no “works on my machine.”

With direnv and a one-line .envrc (use flake), the dev shell loads automatically when you cd into the project — no need to run nix develop manually.

Pin your flake inputs with nix flake update and commit the flake.lock. This locks every dependency to a specific revision.

Step 2: Build the Go binary with Nix

Add a packages output using buildGoModule. This compiles your Go project inside the Nix sandbox — no ambient state and fully reproducible:

packages = forAllSystems (system:
let
  pkgs = nixpkgs.legacyPackages.${system};
in {
  default = pkgs.buildGoModule {
    pname = "myapp";
    version = "0.1.0";
    src = ./.;
    vendorHash = null; # use `go mod vendor` or set the hash

    env.CGO_ENABLED = 0;

    ldflags = [
      "-s" "-w"
      "-extldflags '-static'"
    ];
  };
});

Key points:

• env.CGO_ENABLED = 0 produces a fully static binary — no glibc dependency, runs anywhere.
• vendorHash locks your Go module dependencies. Set it to null if you use go mod vendor, or let Nix tell you the correct hash on first build.
• ldflags with -s -w strips debug info for a smaller binary.

Build it:

$ nix build
$ ./result/bin/myapp

Or use the included Taskfile.yaml (available via go-task in the dev shell):

$ task build

The binary in ./result is the Nix store path. Build it again tomorrow, on another machine, in CI — you get the same bytes.

Step 3: Docker image with Nix

Instead of writing a Dockerfile, use Nix’s dockerTools to build a minimal OCI image that contains only your binary. Docker containers run Linux, so the flake builds a separate Linux binary for the image — on Linux this is identical to the native binary, on macOS it cross-compiles automatically:

packages = forAllSystems (system:
let
  pkgs = nixpkgs.legacyPackages.${system};

  goArch = {
    "x86_64-linux"   = "amd64";
    "aarch64-linux"  = "arm64";
    "aarch64-darwin" = "arm64";
  }.${system};

  isLinux = builtins.match ".*-linux" system != null;

  myapp = pkgs.buildGoModule {
    pname = "myapp";
    version = "0.1.0";
    src = ./.;
    vendorHash = null;

    env.CGO_ENABLED = 0;

    ldflags = [
      "-s" "-w"
      "-extldflags '-static'"
    ];
  };

  # On Linux, reuse the native binary. On macOS, cross-compile for Linux.
  myapp-linux = if isLinux then myapp else pkgs.buildGoModule {
    pname = "myapp";
    version = "0.1.0";
    src = ./.;
    vendorHash = null;

    env.CGO_ENABLED = 0;

    preBuild = ''
      export GOOS=linux
      export GOARCH=${goArch}
    '';

    # Go puts cross-compiled binaries in bin/GOOS_GOARCH/ — flatten it
    postInstall = ''
      if [ -d "$out/bin/linux_${goArch}" ]; then
        mv "$out/bin/linux_${goArch}/"* "$out/bin/"
        rmdir "$out/bin/linux_${goArch}"
      fi
    '';

    ldflags = [
      "-s" "-w"
      "-extldflags '-static'"
    ];
  };
in {
  default = myapp;

  docker = pkgs.dockerTools.buildLayeredImage {
    name = "myapp";
    tag = "latest";
    contents = [ myapp-linux ];
    config = {
      Cmd = [ "/bin/myapp" ];
      ExposedPorts."8080/tcp" = {};
    };
  };
});

Build and load it:

$ nix build .#docker
$ docker load < result
Loaded image: myapp:latest

$ docker run -p 8080:8080 myapp:latest

Or in one step:

$ task docker:run

Why buildLayeredImage?

• Minimal — No base image, no shell, no package manager. Only your binary and what you explicitly include.
• Layered — Nix store paths become individual Docker layers. Unchanged dependencies are cached between builds.
• Deterministic — The image is built from the Nix store, not from apt-get or apk. Same inputs, same image.

The result: byte-by-byte identical

On Linux, myapp-linux is myapp — Nix reuses the same derivation. The binary you test locally with nix build is the exact same binary inside the Docker image. Since the image is minimal (no shell, no coreutils), copy the binary out to compare:

$ nix build
$ sha256sum ./result/bin/myapp
a1b2c3d4...  ./result/bin/myapp

$ nix build .#docker
$ docker load < result
$ docker create --name tmp myapp:latest
$ docker cp tmp:/bin/myapp /tmp/myapp-from-docker
$ docker rm tmp
$ sha256sum /tmp/myapp-from-docker
a1b2c3d4...  /tmp/myapp-from-docker

Or run task verify to do this automatically.

Same hash. The binary in your dev environment, your CI pipeline, and your production container are identical — not “close enough,” not “built from the same source,” but the same bytes.

On macOS, the Docker image contains a cross-compiled Linux binary while your local nix build produces a native macOS binary. The Linux binary inside Docker is still fully reproducible — build it on any machine with the same flake.lock and you get the same bytes.

This eliminates an entire class of bugs: “it worked in dev but not in prod.”

Complete example

The full working example is at codeberg.org/getnix/go-nix-docker with all files needed to build and run:

• flake.nix — Dev shell + Go build + Docker image
• .envrc — direnv config for automatic shell loading
• main.go — Simple HTTP server
• go.mod — Go module definition
• Taskfile.yaml — Task runner shortcuts for common commands

Try it instantly — no clone needed:

$ nix run git+https://codeberg.org/getnix/go-nix-docker

Nix fetches the repo, builds the binary, and starts the HTTP server. In another terminal:

$ curl -i http://127.0.0.1:8080
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

Hello from myapp

Go go1.26.1 linux/amd64

To explore the source and develop locally, clone it:

$ git clone https://codeberg.org/getnix/go-nix-docker.git
$ cd go-nix-docker
$ direnv allow       # auto-load dev shell (or: nix develop)
$ go run .           # run locally

$ nix build          # build reproducible binary
$ nix build .#docker # build Docker image

Quick reference

Anyone who uses more than one computer knows the pain: you spend hours setting up your shell, editor, applications, and system preferences on one machine, only to start from scratch on the next. Multiply that across macOS and Linux, personal and work machines, and the gap widens. Developers feel this acutely — different tool versions cause bugs that appear on one machine but not another — but the problem applies to any desktop user who wants a consistent environment.

This is environment drift, and it compounds over time. The more devices and platforms you use, the more things slip through the cracks.

Nix eliminates drift at the root. With Home Manager and nix-darwin, you declare your entire desktop environment — applications, shell, editor, terminal, git, system preferences — in Nix. The same flake.lock pins every dependency to the same version on every machine. One repository, one source of truth, across macOS and Linux.

Note: This guide presents one opinionated way to structure a Nix-based dotfiles setup. There are many valid approaches — the goal here is to outline the overall idea and give you a concrete starting point you can adapt to your own workflow.

Repository structure

A well-organized dotfiles repo separates concerns into modules. Each tool gets its own file, and platform-specific logic lives inside the modules themselves:

dotfiles/
├── flake.nix              # inputs, outputs, platform targets
├── flake.lock             # pinned dependency versions
├── home.nix               # root Home Manager config (imports modules)
├── darwin.nix             # macOS system-level settings (nix-darwin)
├── modules/
│   ├── packages.nix       # shared package declarations
│   ├── sh.nix             # shell configuration
│   ├── git.nix            # Git settings, aliases, signing
│   ├── direnv.nix         # automatic environment loading
│   └── ...                # editor, terminal, prompt, etc.
├── dotfiles/              # platform-specific static files
│   ├── common/            # shared across all platforms
│   ├── darwin/            # macOS-only
│   └── linux/             # Linux-only
└── secrets/               # encrypted secrets (sops)

One module per concern. Every module imports on both platforms and uses lib.mkIf internally to handle differences. No platform-specific import lists to maintain.

Step 1: The flake

The flake.nix defines inputs and outputs for each platform target. A helper function keeps things DRY:

{
  description = "Dotfiles — cross-platform desktop environment";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    nix-darwin = {
      url = "github:nix-darwin/nix-darwin/master";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, home-manager, nix-darwin, ... }:
  let
    username = "developer";

    mkPkgs = system: import nixpkgs {
      inherit system;
      config.allowUnfree = true;
    };

    mkHome = system: home-manager.lib.homeManagerConfiguration {
      pkgs = mkPkgs system;
      modules = [ ./home.nix ];
      extraSpecialArgs = { inherit self username; };
    };
  in {
    # Linux: standalone Home Manager
    homeConfigurations."${username}@linux" = mkHome "x86_64-linux";

    # macOS: nix-darwin wraps Home Manager
    darwinConfigurations.${username} = nix-darwin.lib.darwinSystem {
      pkgs = mkPkgs "aarch64-darwin";
      specialArgs = { inherit username; };
      modules = [
        ./darwin.nix
        home-manager.darwinModules.home-manager
        {
          home-manager.useGlobalPkgs = true;
          home-manager.useUserPackages = true;
          home-manager.users.${username} = import ./home.nix;
          home-manager.extraSpecialArgs = { inherit self username; };
          users.users.${username}.home = "/Users/${username}";
        }
      ];
    };

    # Validate both platforms in CI
    checks = {
      "x86_64-linux".home = (mkHome "x86_64-linux").activationPackage;
      "aarch64-darwin".darwin =
        self.darwinConfigurations.${username}.system;
    };
  };
}

Linux uses standalone Home Manager (home-manager switch). macOS uses nix-darwin, which wraps Home Manager so you get both user-level and system-level configuration in one darwin-rebuild switch. The checks output validates both platform configurations — run nix flake check in CI to catch breakage before it hits anyone’s machine.

Step 2: Home Manager root config

home.nix imports every module and sets platform-aware defaults:

{ config, pkgs, username, ... }:
{
  imports = [
    ./modules/packages.nix
    ./modules/sh.nix
    ./modules/git.nix
    ./modules/direnv.nix
    # add more modules as needed: editor, terminal, prompt, etc.
  ];

  home.username = username;
  home.homeDirectory =
    if pkgs.stdenv.isDarwin
    then "/Users/${config.home.username}"
    else "/home/${config.home.username}";

  xdg.enable = true;
  programs.home-manager.enable = true;
  home.stateVersion = "26.05";
}

Every module is imported on both platforms. Platform differences are handled inside each module with pkgs.stdenv.isDarwin and pkgs.stdenv.isLinux.

Step 3: Shared packages

Declare your packages once. Every machine gets the same versions:

{ pkgs, ... }:
let
  isLinux = pkgs.stdenv.isLinux;
in {
  home.packages = with pkgs; [
    bat eza fd ripgrep fzf wget  # core CLI
    go gopls golangci-lint       # development (example: Go)
    trivy opentofu               # infrastructure
  ]
  ++ pkgs.lib.optionals isLinux [
    glibcLocales  # locale data for Nix programs on non-NixOS
  ];
}

The lib.optionals isLinux pattern adds packages conditionally. On non-NixOS distributions (Ubuntu, Fedora, Arch), Nix-installed programs need glibcLocales to find locale data — on NixOS or macOS it is already available.

Step 4: Cross-platform shell

Both platforms get the same aliases, history, and completions — only platform-specific integrations differ:

{ config, pkgs, lib, ... }:
let
  isLinux = pkgs.stdenv.isLinux;
  isDarwin = pkgs.stdenv.isDarwin;
in {
  programs.zsh = {
    enable = true;
    autosuggestion.enable = true;
    syntaxHighlighting.enable = true;
    enableCompletion = true;

    history = {
      size = 50000;
      ignoreDups = true;
      ignoreAllDups = true;
      share = true;
    };

    shellAliases = {
      ls = "eza --group-directories-first";
      ll = "eza -l --group-directories-first --git --icons=always";
      la = "eza -la --group-directories-first";
      lt = "eza --tree --group-directories-first";
    };

    initContent = ''
      # Word navigation with Ctrl+arrow
      bindkey '^[[1;5D' backward-word
      bindkey '^[[1;5C' forward-word
      bindkey '^H'      backward-kill-word
    ''
    + lib.optionalString isDarwin ''
      eval "$(/opt/homebrew/bin/brew shellenv)"
    ''
    + lib.optionalString isLinux ''
      [ -f "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh" ] \
        && . "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
    '';
  };

  # Expose Nix binaries to the systemd session (desktop entries, etc.)
  xdg.configFile."environment.d/10-nix-path.conf" = lib.mkIf isLinux {
    text = "PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:$PATH";
  };

  # Locale data for Nix programs on non-NixOS Linux
  home.sessionVariables = pkgs.lib.mkIf isLinux {
    LOCALE_ARCHIVE = "${pkgs.glibcLocales}/lib/locale/locale-archive";
  };
}

The lib.optionalString and lib.mkIf patterns are the building blocks. Every module follows the same approach: shared config at the top, platform-specific blocks gated by isDarwin / isLinux.

Step 5: Git with conditional identities

Declarative git config with conditional includes is especially valuable when switching between work and personal repositories:

{ config, pkgs, ... }:
let
  isDarwin = pkgs.stdenv.isDarwin;
  signingKey =
    if isDarwin
    then "${config.home.homeDirectory}/.ssh/id_ed25519_sk.pub"
    else "${config.home.homeDirectory}/.ssh/id_ed25519.pub";
in {
  programs.git = {
    enable = true;
    signing = { key = signingKey; signByDefault = true; format = "ssh"; };
    lfs.enable = true;

    # Switch identity based on repository location
    includes = [
      { path = "~/.gitconfig-work";     condition = "gitdir:~/src/gitlab.com/acme-corp/"; }
      { path = "~/.gitconfig-personal"; condition = "gitdir:~/src/github.com/"; }
    ];

    settings = {
      user.useConfigOnly = true;
      push.default = "simple";
      pull.rebase = true;
      fetch.prune = true;
      rebase.autoStash = true;
      init.defaultBranch = "main";
      pager.show = "bat";
      alias = {
        s = "status -s";
        lg = "log --graph --abbrev-commit --decorate --date=relative --format=format:'%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s%C(reset) %C(dim white)- %an%C(reset)%C(bold yellow)%d%C(reset)' --all";
      };
    };
  };
}

The referenced config files contain the identity for each context:

# ~/.gitconfig-work
[user]
  name = Jane Doe
  email = jane.doe@acme-corp.com

# ~/.gitconfig-personal
[user]
  name = Jane Doe
  email = janedoe@example.com

If you use different signing keys for work and personal projects, you can move the signing key out of the global git config and into each conditional file instead.

The gitdir: conditions mean your work email and signing identity are automatically active inside work repos, while personal settings apply everywhere else.

Step 6: macOS system preferences

On macOS, nix-darwin declaratively manages system preferences that normally require clicking through System Settings:

{ username, ... }:
{
  system.primaryUser = username;

  homebrew = {
    enable = true;
    onActivation = { autoUpdate = true; upgrade = true; cleanup = "zap"; };
    casks = [ "firefox" "rectangle" ];
    brews = [ "ffmpeg" "wireguard-tools" ];
  };

  system.defaults = {
    dock = {
      autohide = true;
      mru-spaces = false;
      show-recents = false;
    };
    finder = {
      FXEnableExtensionChangeWarning = false;
      _FXShowPosixPathInTitle = true;
    };
    NSGlobalDomain = {
      AppleShowAllExtensions = true;
      AppleInterfaceStyleSwitchesAutomatically = true;
      NSDocumentSaveNewDocumentsToCloud = false;
    };
    CustomUserPreferences."com.apple.desktopservices" = {
      DSDontWriteNetworkStores = true;
      DSDontWriteUSBStores = true;
    };
  };

  system.stateVersion = 6;
}

The homebrew.onActivation.cleanup = "zap" removes any cask or formula not listed in the config, preventing drift from ad-hoc installs.

Applying the configuration

On macOS:

$ sudo darwin-rebuild switch --flake .

On Linux:

$ home-manager switch --flake .#developer@linux

Both commands evaluate the configuration for the current platform and atomically activate it. If something goes wrong, roll back:

$ home-manager generations          # list previous generations
$ sudo darwin-rebuild --list-generations  # on macOS

Validate both platforms in CI without applying:

$ nix flake check

Why this works

Whether you are managing a single personal setup or rolling this out across a team, the approach provides concrete benefits:

1. Instant setup. Clone the repo, run one switch command, and get a fully configured desktop. For teams, this turns onboarding from days into minutes.

2. Pinned versions everywhere. The flake.lock ensures every machine uses the same nixpkgs revision. Update it in a PR, review, merge — every machine gets the update on the next switch.

3. Multi-platform parity. macOS laptops and Linux workstations share the same shell, applications, and configuration. The mkIf guards handle platform differences transparently.

4. Audit trail. Every change to the environment is a git commit. You can see exactly when a package version changed, who changed it, and why.

5. No ambient state. Applications come from the Nix store, not from brew install or apt-get or curl | sh. There is no hidden state that differs between machines.

Quick reference

Warning: The techniques in this guide apply with or without AI — AI is just the most common entry point today. Nix does not sandbox execution: ad-hoc programs run with your user permissions.
-> AI is a tool, not an authority — you are responsible for every action on your system and the resulting consequences.
-> Review commands before running them.

The problem: AI needs software, hosts need hygiene

AI coding agents are increasingly capable. They can write code, run commands, debug issues, and orchestrate complex workflows. But they hit a wall the moment they need a tool that is not installed: a linter for an unfamiliar language, a database client, an image editor, a network diagnostic tool.

The traditional options are bad:

• Install it permanently — pollutes the host with packages the user never asked for and may never need again.
• Run it in a container — isolates the tool from the host, breaking access to local files, GPU, display server, and other resources the AI often needs.
• Ask the user to install it — breaks the flow and defeats the purpose of autonomous agents.

Nix offers a fourth option: run anything ad-hoc, directly on the host, and garbage collect it later. The AI gets full host access. The host stays clean.

How ad-hoc execution works

Nix can run any of its 120,000+ packages without installing them in the traditional sense. The binaries land in /nix/store — an immutable, content-addressed directory — and are available immediately. No apt-get, no brew, no sudo, no permanent changes to PATH.

nix run: execute and exit

nix run fetches a package, builds or downloads it, and runs its default binary in a single command:

$ nix run nixpkgs#cowsay -- "Hello from Nix"
 ________________
< Hello from Nix >
 ----------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

The binary is cached in /nix/store. Nothing is added to your profile or PATH. Run it again and it starts instantly from cache.

nix shell: get a temporary environment

nix shell drops you into a shell (or runs a command) with one or more packages available:

$ nix shell nixpkgs#ffmpeg nixpkgs#imagemagick
$ ffmpeg -version
ffmpeg version 7.1 ...
$ convert --version
Version: ImageMagick 7.1.1 ...
$ exit
$ ffmpeg -version
zsh: command not found: ffmpeg

The packages exist only for the duration of the shell session. After exit, they are gone from PATH — though still cached in the store for instant reuse.

Graphical applications work too

Nix packages include desktop applications with full access to the host display server, GPU, audio, and filesystem:

$ nix run nixpkgs#firefox
$ nix run nixpkgs#gimp
$ nix run nixpkgs#blender
$ nix run nixpkgs#libreoffice

These are not sandboxed or containerized. They run as native processes on the host with the same permissions as the user. They can open local files, access the clipboard, use hardware acceleration — everything a normally installed application can do.

Garbage collection: reclaim disk space on demand

Every nix run and nix shell invocation caches its packages in /nix/store. Over time, this cache grows. Nix provides precise garbage collection to reclaim space:

# Remove packages not referenced by any profile or GC root
$ nix-collect-garbage

# Remove everything older than 30 days
$ nix-collect-garbage --delete-older-than 30d

# Remove all old generations, then collect
$ nix-collect-garbage -d

Garbage collection is safe. Nix traces references from your active profiles and GC roots. Anything not reachable is removed. Anything still needed stays. There is no risk of breaking running software.

Check how much space the store uses:

$ nix store info
$ du -sh /nix/store

Why this matters for AI

AI agents that can invoke shell commands gain a practical superpower with Nix: they can use any software without asking permission to install it and without leaving a mess behind.

What this looks like in practice

An AI coding agent working on a project might need to:

1. Lint unfamiliar code — The project has a Haskell file. The agent does not need Haskell installed:

$ nix run nixpkgs#hlint -- src/Parser.hs

2. Process images — A task requires resizing screenshots. No need to permanently install ImageMagick:

$ nix shell nixpkgs#imagemagick -c convert input.png -resize 50% output.png

3. Inspect a database — The agent needs to check a PostgreSQL schema:

$ nix shell nixpkgs#postgresql -c psql -h localhost -U dev -d myapp -c '\dt'

4. Generate diagrams — Documentation needs architecture diagrams from Graphviz DOT files:

$ nix shell nixpkgs#graphviz -c dot -Tpng architecture.dot -o architecture.png

5. Open a GUI application — The agent needs to verify a PDF renders correctly:

$ nix run nixpkgs#evince -- report.pdf

6. Run a language runtime — A quick Python script is the fastest way to solve a data transformation:

$ nix shell nixpkgs#python3 -c python3 transform.py

In every case, the tool appears instantly (or after a one-time download and build), runs with full host access, and leaves nothing behind once garbage collected.

The container trap

Containers are the default answer to “run something without installing it,” but they introduce friction that undermines AI agents:

Containers are excellent for deployment isolation. But for an AI agent that needs to use software on a developer’s workstation, Nix’s ad-hoc execution is a better fit. The agent operates as an extension of the user, not inside a sealed box.

Security model

Warning: Nix ad-hoc execution runs programs with the current user’s permissions — the same as any other program the user runs. This may have serious security implications: AI agents can read project files, write output, and access local services.

The Nix store itself is read-only and content-addressed. Packages cannot be tampered with after they are built. Every store path includes a cryptographic hash of all inputs. If you fetch the same package twice, you get the same bytes.

Setting up Nix for ad-hoc use

If Nix is not yet installed, a single command sets it up. This installs the Determinate Nix package manager with reasonable defaults.

$ curl -sSf -L https://getnix.io/install | sh -s -- install

Verify it works:

$ nix run nixpkgs#hello
Hello, world!

That is all the setup needed. No package lists to maintain, no profiles to manage. Any of the 120,000+ packages in nixpkgs is now one command away.

Combining ad-hoc packages in a pipeline

Nix shell sessions can compose multiple packages for complex operations:

$ nix shell nixpkgs#ffmpeg nixpkgs#whisper-ctranslate2 -c bash -c '
  ffmpeg -i meeting.mp4 -vn -ar 16000 -ac 1 audio.wav
  whisper audio.wav --model medium --output_format txt
'

This extracts audio from a video and transcribes it using Whisper — neither tool needs to be installed. An AI agent can construct pipelines like this dynamically, pulling in whatever tools the task requires.

Example: Claude Code with Nix

Claude Code is Anthropic’s CLI agent that runs shell commands on your machine. By default it can only use tools already installed on the host. With Nix available, Claude gains access to the entire nixpkgs package set — without installing anything permanently.

Instructing Claude to use Nix

Add a CLAUDE.md file to your project (or your home directory for global instructions) telling Claude that Nix is available and how to use it:

# Tools

Nix is installed on this system. When you need a tool that is not
available, use `nix run nixpkgs#<package>` or `nix shell nixpkgs#<package>`
to run it ad-hoc. Do not install packages permanently.

Search for packages with `nix search nixpkgs <term>`.

That is all it takes. Claude reads CLAUDE.md at the start of every session and will use nix run / nix shell whenever it needs software that is not on the PATH.

What a session looks like

You ask Claude to generate a diagram from a Graphviz DOT file in your project. Claude does not have Graphviz installed, but Nix is available:

You: Generate a PNG from docs/architecture.dot

Claude: I'll render the DOT file to PNG using Graphviz via Nix.

  $ nix shell nixpkgs#graphviz -c dot -Tpng docs/architecture.dot -o docs/architecture.png

  Created docs/architecture.png (2048x1536, 184 KB).

Or you ask Claude to optimize images. It reaches for multiple tools at once:

You: Compress all PNGs in static/ losslessly

Claude: I'll use OptiPNG via Nix to compress them in place.

  $ nix shell nixpkgs#optipng -c bash -c 'for f in static/*.png; do optipng -o5 "$f"; done'

  static/og.png: 142 KB → 118 KB (17% reduction)
  static/hero.png: 89 KB → 74 KB (17% reduction)
  static/logo.png: 12 KB → 11 KB (8% reduction)

Claude can also open graphical applications when it needs visual verification:

You: Check if the PDF report renders correctly

Claude: I'll open the PDF with Evince via Nix so you can inspect it.

  $ nix run nixpkgs#evince -- output/report.pdf

In each case, Claude finds and uses the right tool without any prior installation. The tools are cached in /nix/store for instant reuse and cleaned up by garbage collection when no longer needed.

Automatic cleanup with scheduled garbage collection

For hosts where AI agents run frequently, automate garbage collection so the store does not grow unbounded:

# systemd timer (Linux) — collect garbage weekly
$ cat > ~/.config/systemd/user/nix-gc.service << 'EOF'
[Unit]
Description=Nix garbage collection

[Service]
Type=oneshot
ExecStart=/nix/var/nix/profiles/default/bin/nix-collect-garbage --delete-older-than 7d
EOF

$ cat > ~/.config/systemd/user/nix-gc.timer << 'EOF'
[Unit]
Description=Weekly Nix garbage collection

[Timer]
OnCalendar=weekly
Persistent=true

[Install]
WantedBy=timers.target
EOF

$ systemctl --user enable --now nix-gc.timer

On NixOS, this is a one-liner in your system configuration:

nix.gc = {
  automatic = true;
  dates = "weekly";
  options = "--delete-older-than 7d";
};

Quick reference

Every NixOS machine you manage needs its flake inputs updated, its configuration rebuilt, and the new generation activated. Do it manually and you either fall behind on security patches or spend your weekends SSH-ing into servers. Script it naively and you ship untested updates straight to production.

The ideal workflow:

1. CI updates flake.lock on a schedule and shows you exactly what changed.
2. You review and merge a pull request with per-host package diffs.
3. Hosts self-upgrade from the merged commit — no manual intervention, no surprises.

This guide builds exactly that with a Forgejo Actions workflow and a small NixOS module.

Architecture

The system has two independent timers, staggered three hours apart:

Hosts never modify flake.lock themselves. They always use --no-update-lock-file and build whatever version of nixpkgs (and other inputs) the CI committed to main. This keeps every machine on the same, reviewed set of inputs.

Step 1: The diff script

The core logic lives in a standalone shell script that can run both locally and in CI. It builds every NixOS host configuration before and after a flake update, then produces a per-host package diff via nvd.

Create scripts/flake-update-diff.sh in your NixOS flake repository:

#!/usr/bin/env bash
#
# Build all NixOS host configurations before and after a flake update,
# then report per-host package diffs via nvd.
#
# Exit codes:
#   0 — at least one host has closure changes (diff report on stdout)
#   1 — unexpected error
#   2 — flake.lock did not change after update
#   3 — flake.lock changed but no host closures differ
#
# Options:
#   --skip-update   Skip 'nix flake update' (useful when flake.lock is
#                   already updated and you just want to diff)
#
set -euo pipefail

SKIP_UPDATE=false
for arg in "$@"; do
  case "$arg" in
    --skip-update) SKIP_UPDATE=true ;;
    *) echo "Unknown option: $arg" >&2; exit 1 ;;
  esac
done

# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
log()   { echo "  $*" >&2; }
ok()    { echo "  ✓ $*" >&2; }
fail()  { echo "  ✗ $*" >&2; }
# In CI: use ::group::/::endgroup:: for collapsible sections.
# Locally: print readable section headers instead.
if [ -n "${CI:-}" ]; then
  step()     { echo "::group::$1" >&2; }
  endstep()  { echo "::endgroup::" >&2; }
else
  step()     { echo >&2; echo "── $1 ──" >&2; }
  endstep()  { :; }
fi

# ---------------------------------------------------------------------------
# 1. Discover full (non-minimal) host configurations
# ---------------------------------------------------------------------------
step "Discovering hosts"
HOSTS=$(nix eval .#nixosConfigurations \
  --apply 'cs: builtins.filter (n: builtins.match ".*-minimal" n == null) (builtins.attrNames cs)' \
  --json | nix run nixpkgs#jq -- -r '.[]')

if [ -z "$HOSTS" ]; then
  fail "No host configurations found."
  exit 1
fi
HOST_COUNT=$(echo "$HOSTS" | wc -w | tr -d ' ')
log "Found $HOST_COUNT host(s): $(echo "$HOSTS" | tr '\n' ' ')"
endstep

# ---------------------------------------------------------------------------
# 2. Build current (before-update) configurations
# ---------------------------------------------------------------------------
for host in $HOSTS; do
  step "Building current $host"
  nix build ".#nixosConfigurations.$host.config.system.build.toplevel" \
    -o "result-before-$host" || true
  endstep
done

# ---------------------------------------------------------------------------
# 3. Update flake inputs
# ---------------------------------------------------------------------------
if [ "$SKIP_UPDATE" = false ]; then
  step "Updating flake inputs"
  nix flake update
  endstep
fi

# ---------------------------------------------------------------------------
# 4. Check whether flake.lock actually changed
# ---------------------------------------------------------------------------
step "Checking for flake.lock changes"
if git diff --quiet flake.lock 2>/dev/null; then
  ok "No changes — nothing to do."
  endstep
  exit 2
fi
ok "flake.lock has changed, rebuilding hosts."
endstep

# ---------------------------------------------------------------------------
# 5. Build updated configurations and generate per-host diffs
# ---------------------------------------------------------------------------
DIFF_REPORT=""
HAS_CHANGES=false
CHANGED_HOSTS=""
UNCHANGED_HOSTS=""

for host in $HOSTS; do
  step "Building updated $host"
  nix build ".#nixosConfigurations.$host.config.system.build.toplevel" \
    -o "result-after-$host" || true
  endstep

  if [ -e "result-before-$host" ] && [ -e "result-after-$host" ]; then
    step "Package diff for $host"
    HOST_DIFF=$(nix run nixpkgs#nvd -- diff "result-before-$host" "result-after-$host" 2>&1 || true)
    echo "$HOST_DIFF" >&2
    endstep

    if [ "$(readlink "result-before-$host")" != "$(readlink "result-after-$host")" ]; then
      HAS_CHANGES=true
      CHANGED_HOSTS="$CHANGED_HOSTS $host"
      DIFF_REPORT="${DIFF_REPORT}### ${host}"$'\n'"\`\`\`"$'\n'"${HOST_DIFF}"$'\n'"\`\`\`"$'\n\n'
    else
      UNCHANGED_HOSTS="$UNCHANGED_HOSTS $host"
    fi
  fi
done

# ---------------------------------------------------------------------------
# 6. Report results
# ---------------------------------------------------------------------------
step "Summary"
if [ -n "$CHANGED_HOSTS" ]; then
  ok "Changed:  $CHANGED_HOSTS"
fi
if [ -n "$UNCHANGED_HOSTS" ]; then
  log "Unchanged:$UNCHANGED_HOSTS"
fi

if [ "$HAS_CHANGES" = false ]; then
  fail "flake.lock changed but no host closures differ."
  endstep
  exit 3
fi

ok "Done — diff report ready."
endstep

# Print the diff report to stdout for consumers (CI, local review, etc.)
printf '%s' "$DIFF_REPORT"

How the script works

1. Discover hosts — evaluates the flake to list all nixosConfigurations, filtering out any ending in -minimal (installer images, etc.).
2. Build before — every host configuration is built from the current flake.lock and stored as a symlink result-before-<host>.
3. Update — nix flake update pulls the latest nixpkgs, home-manager, and any other inputs (skipped with --skip-update).
4. Check — if flake.lock is unchanged, the script exits early with code 2.
5. Build after & diff — hosts are rebuilt with the updated lock file. For each host, nvd compares the before/after store paths and reports added, removed, and version-changed packages. The script distinguishes hosts whose closures actually changed from those that are identical despite the lock file update.
6. Report — progress and a summary go to stderr; the machine-readable diff report goes to stdout for consumers (the CI workflow, a local terminal, etc.). If flake.lock changed but no host closures differ, the script exits with code 3.

Exit codes

Running locally

Because the script is independent of CI, you can run it on your workstation to preview what an update would change before committing anything:

# Full run — update flake.lock and diff all hosts
$ ./scripts/flake-update-diff.sh

# Diff only — you already ran nix flake update manually
$ ./scripts/flake-update-diff.sh --skip-update

Progress is printed to stderr, so the diff report on stdout can be piped or redirected:

$ ./scripts/flake-update-diff.sh > /tmp/diff-report.md

Step 2: The CI workflow

The workflow is a thin wrapper around the script. It handles SSH setup, git identity, and opening a pull request — all build and diff logic lives in the script above.

Create .forgejo/workflows/update.yaml:

name: Update Flake Inputs

on:
  schedule:
    - cron: "0 2 * * *" # Daily at 02:00 UTC — well before hosts auto-upgrade.
  workflow_dispatch: # Allow manual trigger from the Forgejo UI.

env:
  GIT_USER_NAME: ci # ⚠️ Replace with your CI bot name.
  GIT_USER_EMAIL: ci@example.com # ⚠️ Replace with your CI bot email.

jobs:
  update:
    name: Update flake.lock and diff all hosts
    runs-on: nixos-builder # A native NixOS runner — leverages the host Nix store.
    steps:
      - name: Checkout repository
        uses: https://data.forgejo.org/actions/checkout@v6

      # Write the deploy key so git can push branches and sign commits.
      - name: Configure SSH key for git push and commit signing
        run: |
          SSH_DIR="$RUNNER_TEMP/.ssh"
          mkdir -p "$SSH_DIR"
          echo "${{ secrets.GIT_PRIVATE_KEY }}" > "$SSH_DIR/forgejo_key"
          chmod 600 "$SSH_DIR/forgejo_key"
          SSH_BIN="$(command -v ssh)"
          export GIT_SSH_COMMAND="$SSH_BIN -i $SSH_DIR/forgejo_key -o StrictHostKeyChecking=no"
          echo "GIT_SSH_COMMAND=$GIT_SSH_COMMAND" >> "$FORGEJO_ENV"
          echo "SSH_KEY_PATH=$SSH_DIR/forgejo_key" >> "$FORGEJO_ENV"
          FORGEJO_DOMAIN="${FORGEJO_SERVER_URL#https://}"
          FORGEJO_DOMAIN="${FORGEJO_DOMAIN#http://}"
          echo "FORGEJO_DOMAIN=$FORGEJO_DOMAIN" >> "$FORGEJO_ENV"

      # Configure the CI bot identity and SSH commit signing.
      - name: Configure git identity, signing, and SSH remote
        run: |
          git config user.name "${{ env.GIT_USER_NAME }}"
          git config user.email "${{ env.GIT_USER_EMAIL }}"
          git config gpg.format ssh
          git config user.signingkey "$SSH_KEY_PATH"
          git config commit.gpgsign true
          git remote set-url origin git@${{ env.FORGEJO_DOMAIN }}:${{ forgejo.repository }}.git

      # Run the diff script. Exit codes 2 and 3 are expected
      # "no-op" conditions — only code 0 means a PR is needed.
      - name: Update flake inputs and diff all hosts
        id: diff
        run: |
          DIFF_REPORT=$(bash ./scripts/flake-update-diff.sh) && STATUS=0 || STATUS=$?

          case "$STATUS" in
            0)
              echo "has_changes=true" >> "$FORGEJO_OUTPUT"
              {
                echo "report<<DIFF_EOF"
                printf '%s\n' "$DIFF_REPORT"
                echo "DIFF_EOF"
              } >> "$FORGEJO_OUTPUT"
              ;;
            2) echo "No flake.lock changes, skipping PR." ;;
            3) echo "No host closure changes, skipping PR." ;;
            *) exit "$STATUS" ;;
          esac

      # Commit the updated flake.lock and open a PR with the diff report.
      - name: Create branch, commit, and open pull request
        if: steps.diff.outputs.has_changes == 'true'
        env:
          DIFF_REPORT: ${{ steps.diff.outputs.report }}
          FORGEJO_TOKEN: ${{ forgejo.token }}
        run: |
          DATE=$(date +%Y-%m-%d)
          BRANCH="auto/flake-update-$DATE"

          git push origin --delete "$BRANCH" || true
          git checkout -b "$BRANCH"
          git add flake.lock
          git commit -m "chore: update flake inputs $DATE"
          git push origin "$BRANCH"

          # jq --arg safely handles all escaping (backticks, newlines, quotes)
          PAYLOAD=$(nix run nixpkgs#jq -- -n \
            --arg title "chore: update flake inputs $DATE" \
            --arg head  "$BRANCH" \
            --arg base  "main" \
            --arg diff  "$DIFF_REPORT" \
            '{
              title: $title, head: $head, base: $base,
              body: "## Automated flake.lock update\n\nPackage changes per host (via nvd):\n\n\($diff)\n---\n*Auto-generated by the update workflow.*"
            }')

          nix run nixpkgs#curl -- -sf -X POST \
            -H "Authorization: token $FORGEJO_TOKEN" \
            -H "Content-Type: application/json" \
            "${{ forgejo.server_url }}/api/v1/repos/${{ forgejo.repository }}/pulls" \
            -d "$PAYLOAD"

      - name: Cleanup
        if: always()
        run: |
          rm -f "$SSH_KEY_PATH"
          rm -f result-before-* result-after-*

Compared to inlining all the build and diff logic in the workflow, this split has two advantages: the script can be run locally to preview updates before committing, and the workflow YAML stays focused on CI plumbing (SSH, git, PR creation) rather than build logic.

Where it runs

The workflow runs on a NixOS host (runner label nixos-builder), not inside a container. This is important for two reasons:

• It needs a working Nix installation with direct access to /nix/store. The host’s Nix store acts as a persistent build cache — derivations that haven’t changed since the last run are already in the store and don’t need to be rebuilt or downloaded again.
• It builds full NixOS system configurations (system.build.toplevel), which are large closures that benefit greatly from an existing store.

You can run this workflow in a container (e.g. a Docker-based Forgejo runner with Nix installed), but each run would start with a cold Nix store. That means every derivation is fetched or built from scratch, turning a job that takes minutes on a NixOS host into one that can take significantly longer. If you go the container route, mounting a persistent volume for /nix/store and /nix/var/nix/db helps, but a native NixOS runner remains the most efficient option.

If you already run a Forgejo runner on a NixOS machine, point this workflow at it. Otherwise, register a new runner on any NixOS host with the label nixos-builder.

Secrets and configuration

The workflow needs one secret. Most configuration is derived automatically from Forgejo context variables.

Required secrets

The FORGEJO_TOKEN used to create the pull request via the API is provided automatically by Forgejo (${{ forgejo.token }}). No manual setup is required.

Values to customize

Only two values are hardcoded in the YAML — everything else (remote URL, API endpoint) is derived from Forgejo context variables (forgejo.server_url, forgejo.repository):

Optional / tunable

What the PR looks like

The resulting pull request body contains a per-host section like this:

## Automated flake.lock update

Package changes per host (via nvd):

### webserver

  [nvd output showing package upgrades, additions, and removals]

### devbox

  [nvd output for this host]

Hosts whose closures did not change (despite the flake.lock update) are omitted from the report. You review the PR, see exactly which packages changed on which host, and merge when ready. Nothing reaches your machines until you merge to main.

Tip: fully hands-off with auto-merge. If you trust the CI builds and don’t want to review every update manually, most Git forges (Forgejo, GitHub, GitLab) support auto-merging PRs once all required checks pass. Enable branch protection with a required status check for the build job, then configure auto-merge on the PR. The PR will merge itself as soon as CI is green — turning the entire pipeline into a zero-touch flow where hosts upgrade daily without any human interaction. You can still review the merged diff after the fact and roll back if needed.

Step 3: The auto-upgrade NixOS module

Create a module that wraps system.autoUpgrade so hosts pull from your Git repository on a schedule:

# modules/auto-upgrade.nix
{
  config,
  lib,
  ...
}:
let
  hostname = config.networking.hostName;
in
{
  options.services.auto-upgrade.enable =
    lib.mkEnableOption "automatic daily flake-based NixOS upgrade";

  config = lib.mkIf config.services.auto-upgrade.enable {
    system.autoUpgrade = {
      enable = true;

      # Fetch the latest main branch from your Git server.
      # Each host selects its own nixosConfiguration by hostname.
      flake = "git+https://your-forgejo/nix/nixos.git#${hostname}";

      # Never update flake.lock on the host — CI handles that.
      flags = [
        "--no-update-lock-file"
      ];

      # Run daily at 05:00 (host-local time), one hour after CI.
      dates = "05:00";

      # Do not reboot automatically.
      # Most services restart on nixos-rebuild switch.
      allowReboot = false;

      # "switch" activates immediately.
      # Use "boot" to defer activation until next reboot.
      operation = "switch";
    };
  };
}

Key design decisions:

• --no-update-lock-file — the most important flag. Hosts consume whatever flake.lock is on main. They never resolve inputs independently, so every machine converges on the same package set.
• flake = "git+https://...#${hostname}" — each host selects its own nixosConfiguration output by hostname. One repository, many machines.
• dates = "05:00" — staggered three hours after the CI runs at 02:00 UTC. This gives you a window to review the PR. If it is not merged yet, hosts simply rebuild from the current main (a no-op if nothing changed).
• allowReboot = false — most NixOS services restart on switch. Set to true if you need kernel or initrd updates to take effect immediately.

Step 4: Enable on each host

Include the module in your flake and enable it per host:

# flake.nix (simplified)
{
  outputs = { nixpkgs, ... }: {
    nixosConfigurations = {
      webserver = nixpkgs.lib.nixosSystem {
        modules = [
          ./modules/auto-upgrade.nix
          ./hosts/webserver
        ];
      };

      devbox = nixpkgs.lib.nixosSystem {
        modules = [
          ./modules/auto-upgrade.nix
          ./hosts/devbox
        ];
      };
    };
  };
}

Then in each host’s configuration:

# hosts/webserver/default.nix
{
  services.auto-upgrade.enable = true;
}

For machines you deploy manually (like the CI builder itself, or test machines), simply omit the option or set it to false.

Step 5: Verify the setup

After deploying the configuration to your hosts, check that the systemd timer and service are in place:

# Check the timer schedule and when it last fired
$ systemctl status nixos-upgrade.timer
● nixos-upgrade.timer
     Loaded: loaded
     Active: active (waiting)
    Trigger: tomorrow at 05:00

# Check the last upgrade run
$ journalctl -u nixos-upgrade.service -n 30

The nixos-upgrade.service logs show the full nixos-rebuild switch output — which generation was activated, which services restarted, and any errors.

The full flow

Here is what happens every day without any manual intervention:

02:00 UTC  Forgejo Actions runs on CI builder
           ├─ scripts/flake-update-diff.sh
           │   ├─ Discover hosts, build before
           │   ├─ nix flake update
           │   ├─ Build after, nvd diff per host
           │   └─ Report (stdout → workflow)
           └─ Open PR with diff report

   You     Review PR, check package changes, merge to main

05:00      Each NixOS host (systemd timer)
           ├─ git fetch main (via flake URL)
           ├─ nix build own configuration
           └─ nixos-rebuild switch

If you don’t merge the PR before 05:00, hosts simply rebuild from the current main — effectively a no-op. The update waits until you merge.

Rollback

If a bad update slips through, NixOS makes rollback trivial:

# Roll back to the previous generation
$ sudo nixos-rebuild switch --rollback

# Or boot into a previous generation from the bootloader

Every generation is kept in the Nix store until garbage-collected, so you can always go back.

Adapting the schedule

For desktops you might prefer operation = "boot" so the new configuration only activates on the next reboot, avoiding disruption during work hours. For servers, switch is usually the right choice since services restart gracefully.

Why this works well

• No unreviewed changes reach production. The PR gate means you always see what changed before it deploys.
• Hosts never drift from each other. Every machine builds from the same flake.lock on main.
• Zero manual SSH sessions. Once the module is enabled, upgrades are fully automatic.
• Safe by default. If CI fails to build a host, the PR shows the error. If a host fails to build, it stays on its current generation. If you merge something bad, nixos-rebuild switch --rollback fixes it in seconds.
• Works for any fleet size. Whether you run two machines or twenty, the same workflow scales — one PR, one merge, all hosts converge.