Always-on agents · Set it up anywhere

Running an always-on agent on NixOS

NixOS is the only distribution in this series where the agent host is a file you can read, diff and roll back. That is a real advantage for something that must run unattended for months. It is also the one with the steepest first week. Here is the configuration, what I could and could not test, and what it costs.

In short

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 --rollback

The 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.target

The 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

  1. NixOS Wiki, Systemd/Timers (accessed October 20, 2026)
  2. NixOS Wiki, Nixos-rebuild (subcommands, list-generations, rollback) (accessed October 20, 2026)
  3. NixOS Wiki, Comparison of secret managing schemes (accessed October 20, 2026)
  4. ryantm, agenix: age-encrypted secrets for NixOS and Home Manager (accessed October 20, 2026)
  5. 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.

Frequently asked questions

Can I run an AI agent on NixOS?

Yes. Declare the agent's user, a systemd service with a restart policy and hardening, and a timer in configuration.nix, apply it with nixos-rebuild switch, and keep the API keys out of the file with agenix or sops-nix. Every switch is a generation you can roll back to.

Why can't I put the API key in configuration.nix?

Because the file's output lands in /nix/store, which every user on the machine can read. agenix and sops-nix keep secrets encrypted in the repository and decrypt them at activation into a runtime path with the right owner and mode.

How do I roll back if a change breaks the agent host?

sudo nixos-rebuild switch --rollback returns to the previous generation. For anything older, pick the generation in the boot menu or run that generation's switch-to-configuration script, and use nixos-rebuild list-generations to see what you have.

Does NixOS change how systemd runs the agent?

No. The declaration produces ordinary systemd unit files, which is why evaluating the configuration and reading the generated units is a meaningful test. The difference is where the configuration lives and that every change is versioned.

What was actually tested for this guide?

The configuration was evaluated with Nix in a fresh nixos/nix container against the nixpkgs channel, producing the real unit text shown above. The service was not booted, and secrets decryption was not exercised, because I do not have a NixOS machine.

Lera Leonteva
Lera Leonteva
CEO & Founder, Leo AI

Lera Leonteva is the founder and CEO of Leo AI, where she works on turning long-form footage into short-form video that earns attention on its own merits. She writes Video Scaling Strategies, taking one piece of content that worked and one that did not, and using what the market is doing to explain the gap.

The always-on agent I run for social video

Leo watches what your audience is responding to, picks a clip from footage you already have, edits it and books it on the calendar. Every hour, without being asked. It is the agent this whole series grew out of.

Keep going with the series

Every post in the Always-on agents series is on one page, newest first. If you would rather see the agent I run for social video, here it is.