hermes-agent/docs/nixos-setup.md

Nix Setup Guide for Hermes Agent

Prerequisites

• Nix with flakes enabled (we recommend Determinate Nix which enables flakes by default)
• API keys for the services you want to use (at minimum: OpenRouter)

Quick Start: nix run

nix run github:NousResearch/hermes-agent -- setup
nix run github:NousResearch/hermes-agent -- chat

No clone needed. Nix fetches and builds everything.

Install

All Python dependencies are pre-built as Nix derivations via uv2nix — no runtime pip install.

# From a clone
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
nix build
./result/bin/hermes setup
./result/bin/hermes chat

# Or install into your profile
nix profile install github:NousResearch/hermes-agent
hermes setup

Development (nix develop)

For hacking on hermes-agent locally:

cd hermes-agent
nix develop
# Shell automatically:
#   - Creates .venv with Python 3.11
#   - Installs all Python deps via uv
#   - Installs npm deps (agent-browser)
#   - Puts ripgrep, git, node on PATH

hermes setup
hermes

Using direnv (recommended)

If you have direnv installed, the included .envrc will automatically activate the dev shell when you cd into the repo:

cd hermes-agent
direnv allow    # one-time approval

# From now on, entering the directory activates the environment automatically.
# On repeat entry, the stamp file check skips dependency installation (~instant).

Persistent Messaging Gateway

To run hermes-agent as a always-on service for Telegram, Discord, or Slack (with built-in cron scheduler), use the home-manager module. This is how messaging platforms are meant to be run — the gateway stays up, receives messages, and responds. Works on any Linux distribution with Nix, not just NixOS.

This assumes you already have home-manager set up. If you don't, see the home-manager docs first.

Step 1: Add the flake input

# ~/.config/home-manager/flake.nix (or wherever your HM flake lives)
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    hermes-agent.url = "github:NousResearch/hermes-agent";
  };

  outputs = { nixpkgs, home-manager, hermes-agent, ... }: {
    homeConfigurations."your-username" = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      modules = [
        hermes-agent.homeManagerModules.default
        ./home.nix
      ];
    };
  };
}

Step 2: Enable in home.nix

# home.nix
{
  services.hermes-agent = {
    enable = true;
    gateway.enable = true;

    # All options with defaults:
    # hermesHome = "~/.hermes";           # config, sessions, memories
    # environmentFile = "~/.hermes/.env"; # API keys
    # messagingCwd = "~";                 # gateway working directory
    # addToPATH = true;                   # adds `hermes` CLI to PATH
  };
}

Step 3: API keys

mkdir -p ~/.hermes
cat > ~/.hermes/.env << 'EOF'
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxx
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789
EOF
chmod 600 ~/.hermes/.env

Step 4: Enable linger + activate

# Lets user services survive logout
sudo loginctl enable-linger $USER

# Activate — all deps are pre-built, this is fast
home-manager switch

Step 5: Verify

systemctl --user status hermes-agent-gateway
journalctl --user -u hermes-agent-gateway -f
hermes doctor

Directory layout

~/.hermes/                           # Config & data
├── .env                             # API keys
├── config.yaml                      # Agent configuration
├── sessions/                        # Messaging sessions
├── memories/                        # Agent memories
├── skills/                          # Knowledge documents
├── cron/                            # Scheduled jobs
└── logs/                            # Session logs

Customizing

$EDITOR ~/.hermes/config.yaml

Key settings:

• model.default — Which LLM to use (default: anthropic/claude-opus-4.6)
• terminal.env_type — Terminal backend: local, docker, ssh
• toolsets — Which tools to enable (default: all)

After editing, restart the service:

systemctl --user restart hermes-agent-gateway

Updating

nix flake update hermes-agent --flake ~/.config/home-manager
home-manager switch

Troubleshooting

# Gateway logs
journalctl --user -u hermes-agent-gateway -f

# Check CLI + deps
hermes doctor

# Restart gateway
systemctl --user restart hermes-agent-gateway

# Full rebuild (if something is really wrong)
nix build --rebuild