Tutorial 12: Nix & NixOS Setup

Tutorial 12: Nix & NixOS Setup

Imagine moving into a new apartment where every piece of furniture is already perfectly placed, and the utilities are pre-connected. That’s what Nix does for software: it sets up your entire environment—Python, Node.js, git, and all—in one clean, reproducible package. No more “it works on my machine” surprises. For Hermes Agent, this means you can skip the messy installer and get a fully wrapped, ready-to-run agent in seconds.

Here’s how to get started, whether you’re a casual user or a NixOS server admin.

---

Step 1: Check Your Prerequisites

Before we dive in, make sure you have:

• Nix with flakes enabled – If you don’t have Nix yet, I recommend Determinate Nix. It’s a one-liner installer that turns on flakes by default, saving you a config headache.
• An API key – You’ll need at least an OpenRouter or Anthropic key to talk to your agent.

If you’re already on NixOS, you’re good to go. If not, don’t worry—the steps below work on macOS and regular Linux too.

---

Step 2: Quick Start for Any Nix User (No Clone Needed)

The easiest path is to just run Hermes Agent directly from the Nix flake. You don’t even need to download the source code. Open your terminal and type:

nix run github:hermes-agent/hermes-agent

That’s it. Nix fetches the pre-built binary, along with every dependency (Python, Node, ripgrep, ffmpeg, etc.), and drops you into the Hermes CLI. From here, the workflow is identical to the standard install:

hermes setup
hermes gateway install

You can edit config files, add tools, and chat with your agent just like you would after a normal curl | bash install. The only difference? No venv activation, no pip install, no npm install. Everything is already bundled.

---

Step 3: For NixOS Users – The Native Module

If you’re running NixOS as a server, you get a much deeper integration. Instead of managing Hermes with CLI commands, you declare it in your system configuration.

Add this to your configuration.nix:

{
  services.hermes-agent = {
    enable = true;
    apiKeyFile = "/run/secrets/hermes-key";  # or use sops-nix/agenix
  };
}

Then rebuild your system:

sudo nixos-rebuild switch

Now Hermes runs as a hardened systemd service. It starts automatically, restarts on failure, and keeps secrets in encrypted files (via sops-nix or agenix). You manage it like any other NixOS service—no manual hermes commands allowed.

---

Step 4: For NixOS Users – The Container Option

Sometimes your agent needs to install its own tools at runtime (like apt install or pip install). For that, use the container module:

{
  services.hermes-agent = {
    enable = true;
    container = true;  # runs inside a persistent Ubuntu container
  };
}

This gives you everything from Step 3, plus a lightweight Ubuntu environment where your agent can freely modify itself. It’s perfect for agents that write code, test packages, or need system-level changes.

---

What’s Different from the Standard Install?

• No runtime Python/Node management – The flake builds every dependency as a Nix derivation. You get a single binary with everything inside.
• No venv or npm – Forget about activating environments. Just run hermes.
• For NixOS users: The lifecycle is fully declarative. You edit configuration.nix, rebuild, and done. No manual service setup.

---

Summary

Nix gives you a clean, reproducible way to run Hermes Agent. For casual users, nix run is a one-liner that just works. For NixOS admins, the module turns your agent into a proper, managed system service. Either way, you avoid the mess of manual dependency installation.

Next up: Tutorial 13 – “Hermes Agent on Docker: The Portable Powerhouse” – where we’ll containerize your agent for maximum portability across any Linux server.