On NixOS the agent's user, service, timer and hardening are declared in configuration.nix and applied with nixos-rebuild switch; every switch is a generation you can roll back to in one command or from the boot menu. Secrets must not go in that file, because the Nix store is readable by every user; agenix or sops-nix decrypts them at activation. The price is the learning curve.
Part of the Always-on agents series, post 30 of 33.
Every other Linux guide in this series says the same thing in a different package manager: make a user, write a unit, enable a timer, keep secrets out of the unit. NixOS changes the shape of the job. You do not do those steps on the machine. You write them down once, and the machine becomes what you wrote. For an agent that has to run unattended for months, I find that more reassuring than any amount of care taken at a shell prompt, and I say that as someone whose own jobs run on a Mac that was configured by hand.
This page covers only what NixOS does differently. The ten steps themselves, and the reasons behind each one, are in the Linux core page. I tested what can be tested without a real NixOS machine, and the section on testing says exactly what that was.
The whole host in one file
Here is a complete agent host, minus the boot loader and disks that every NixOS machine declares anyway. The service is hardened the way I harden my own jobs: its own user, no new privileges, a read-only view of the system except for its state directory, a memory cap, and a restart policy. The timer carries Persistent, so a digest that was due while the machine was off runs when it comes back, which is the catch-up rule from the first post in one line.
configuration.nix (the agent part){ config, pkgs, lib, ... }:
{
# the agent's own user, never yours
users.groups.agent = { };
users.users.agent = {
isSystemUser = true;
group = "agent";
home = "/var/lib/agent";
createHome = true;
};
# the long-running agent
systemd.services.agent = {
description = "Always-on agent (heartbeat loop)";
wantedBy = [ "multi-user.target" ];
wants = [ "network-online.target" ];
after = [ "network-online.target" ];
serviceConfig = {
ExecStart = "${pkgs.python3}/bin/python3 /var/lib/agent/agent.py";
User = "agent";
Group = "agent";
WorkingDirectory = "/var/lib/agent";
Restart = "always";
RestartSec = 5;
MemoryMax = "512M";
# secrets come from agenix or sops-nix at activation, never from the Nix store
EnvironmentFile = "/run/secrets/agent.env";
NoNewPrivileges = true;
ProtectSystem = "strict";
ProtectHome = true;
PrivateTmp = true;
ReadWritePaths = [ "/var/lib/agent" ];
};
};
# the daily digest: a oneshot service and a timer that catches up after downtime
systemd.services.agent-digest = {
description = "Always-on agent: daily digest";
serviceConfig = {
Type = "oneshot";
User = "agent";
ExecStart = "${pkgs.python3}/bin/python3 /var/lib/agent/digest.py";
};
};
systemd.timers.agent-digest = {
wantedBy = [ "timers.target" ];
timerConfig = {
OnCalendar = "07:00";
Persistent = true;
Unit = "agent-digest.service";
};
};
}Two things to notice. The Python interpreter is written as a Nix expression, so the unit points at an exact build in the store rather than whatever /usr/bin/python3 happens to be after an upgrade. And the EnvironmentFile points at /run/secrets, a path that does not exist in this file at all; the next section is about why.
Secrets stay out of the store
Everything that configuration.nix produces ends up in /nix/store, and the store is readable by every user on the machine. That is by design: it is what makes builds reproducible and shareable. It also means an API key written into a service definition is an API key given to every process on the host. My own rule from the permissions post is that a secret lives in a file only the agent's user can read; on NixOS that file has to be created outside the store, at activation time.
Two tools do this, and the NixOS wiki keeps a comparison. agenix encrypts each secret with age against your SSH keys, keeps the encrypted file in the repository, and decrypts it with the host's SSH key at activation into /run. sops-nix does the same with sops and supports more key types and templating. For one agent on one host I would pick agenix, because the whole thing is three lines:
configuration.nix with agenix# secrets/agent.env.age is encrypted in the repo; it is decrypted at activation
age.secrets.agent-env.file = ./secrets/agent.env.age;
systemd.services.agent.serviceConfig.EnvironmentFile = config.age.secrets.agent-env.path;Generations and the rollback
This is the part I would most like to have on my own machine. Every nixos-rebuild switch creates a new generation and makes it the default boot entry. The old ones stay. If a change to the agent breaks the host, one command takes you back, and if it breaks the host badly enough that you cannot log in, the boot menu lists every previous generation and you pick one.
Terminal# apply, and make it the default boot entry
sudo nixos-rebuild switch
# see what you have
nixos-rebuild list-generations
# the agent host is misbehaving after a change: go back one generation
sudo nixos-rebuild switch --rollbackThe wiki is honest about one limit: as of its December 2024 revision, nixos-rebuild only rolls back one generation on its own. To go further you switch to a specific generation's switch-to-configuration script by hand. For an agent host that is rarely a problem, because you find out something is wrong the next morning, not three changes later.
What I tested, and what I could not
I do not own a NixOS machine. What I could do, and did, was evaluate the configuration above with Nix itself in a fresh container of the official nixos/nix image, against the nixpkgs channel it ships with, and ask it for the exact unit files NixOS would write. That is a real test of the declaration: a typo in an option name, a wrong type, or a missing attribute fails here, before any machine is touched. It is not a test of the running service, the boot, or the secrets decryption.
Terminal, in the nixos/nix container# evaluate the configuration and print the unit files NixOS would write
nix-instantiate --eval --strict --json -E '
let cfg = (import <nixpkgs/nixos> { configuration = ./configuration.nix; }).config;
in { service = cfg.systemd.units."agent.service".text;
timer = cfg.systemd.units."agent-digest.timer".text; }'Output (trimmed)# agent.service (three long Environment= lines for PATH, locale and tzdata omitted)
[Unit]
After=network-online.target
Description=Always-on agent (heartbeat loop)
Wants=network-online.target
[Service]
EnvironmentFile=/run/secrets/agent.env
ExecStart=/nix/store/smwd56pl54f0pcjdspgh5vnf20c8xwsc-python3-3.13.13/bin/python3 /var/lib/agent/agent.py
Group=agent
MemoryMax=512M
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadWritePaths=/var/lib/agent
Restart=always
RestartSec=5
User=agent
WorkingDirectory=/var/lib/agent
[Install]
WantedBy=multi-user.target
# agent-digest.timer
[Timer]
OnCalendar=07:00
Persistent=true
Unit=agent-digest.service
[Install]
WantedBy=timers.targetThe unit text is what you would expect from the Linux core page, which is the point: NixOS does not change what systemd runs, only where the truth about it lives. Two details I liked seeing: the ExecStart line names a specific Python build in the store, 3.13.13 on the channel the image carried, so no upgrade can swap it underneath the agent; and the evaluation took the nixos/nix image a few minutes on the first run, because it had to fetch the NixOS modules, and seconds after that.
What it costs
- The first week. The language, the module system and the error messages are unlike any other distribution here. Budget real time before the agent runs.
- Packaging the agent. If it is a Python script with packages, the clean way is python3.withPackages in the configuration. A pip virtual environment under /var/lib works too, but wheels with compiled extensions may fail to find shared libraries, because NixOS has no /usr/lib to find them in. Expect to spend time here if the agent has many dependencies.
- Anything not in nixpkgs. A new agent framework released last month may not be packaged. You can package it yourself, which is a skill, or run it in a container on the NixOS host.
- Updates are a decision, not a drip. Nothing changes until you rebuild. That is the feature, and it also means security updates wait for you.
If you already run NixOS, this is the best always-on host in the series and I would not hesitate. If you do not, and you want an agent running this weekend, Debian or Ubuntu gets you there faster, and you can come back to this page when the host starts to matter more than the agent.
Sources
- NixOS Wiki, Systemd/Timers (accessed October 20, 2026)
- NixOS Wiki, Nixos-rebuild (subcommands, list-generations, rollback) (accessed October 20, 2026)
- NixOS Wiki, Comparison of secret managing schemes (accessed October 20, 2026)
- ryantm, agenix: age-encrypted secrets for NixOS and Home Manager (accessed October 20, 2026)
- NixOS, NixOS manual: changing the configuration (accessed October 20, 2026)
Written by Lera Leonteva. The evaluation output above is from a fresh container of the official nixos/nix image on the access date, trimmed for length.