Agents

Setup notes for running the Hermes agent on a dedicated VM, with LXD (ZFS backed) available to it as a sandbox for tool use.

Provision the VM

Create an Ubuntu 26.04 VM and attach a 1 TiB block device in addition to the root disk.

Confirm the device name (a virtio disk, /dev/vdb below):

lsblk

Partition the block device

Two partitions:

• 256 GiB — /home/hermes, ext4

• 768 GiB — btrfs pool for LXD

sudo parted /dev/vdb --script mklabel gpt
sudo parted /dev/vdb --script mkpart home   ext4  0%    256GiB
sudo parted /dev/vdb --script mkpart lxdpool btrfs 256GiB 100%

This yields /dev/vdb1 (home) and /dev/vdb2 (btrfs pool).

Install LXD with a btrfs backed pool

sudo apt update
sudo apt install -y btrfs-progs
sudo snap install lxd

Initialise LXD and let it create the btrfs pool on the second partition:

sudo lxd init

Answer the wizard with:

• Configure a new storage pool: yes

• Name: lxd

• Backend: btrfs

• Create a new btrfs pool: yes

• Use an existing empty block device: yes, path /dev/vdb2

config: {}
networks:
- config:
    ipv4.address: auto
    ipv6.address: auto
  description: ""
  name: lxdbr0
  type: ""
  project: default
storage_pools:
- config:
    source: /dev/vdb2
  description: ""
  name: default
  driver: btrfs
storage_volumes: []
profiles:
- config: {}
  description: ""
  devices:
    eth0:
      name: eth0
      network: lxdbr0
      type: nic
    root:
      path: /
      pool: default
      type: disk
  name: default
projects: []
cluster: null

Create and mount /home/hermes

sudo mkfs.ext4 -L hermes /dev/vdb1
sudo mkdir -p /home/hermes

Persist the mount in /etc/fstab (by label, to survive device renaming):

echo 'LABEL=hermes  /home/hermes  ext4  defaults  0  2' | sudo tee -a /etc/fstab

Verify it mounts cleanly:

sudo systemctl daemon-reload
sudo mount -a && mount

Add the hermes user

Create the user against the already-mounted home directory:

sudo useradd --home-dir /home/hermes --shell /bin/bash hermes
sudo chown -R hermes:hermes /home/hermes
sudo -iu hermes cp /etc/skel/.bashrc ~/.bashrc

Add to sudoers:

sudo usermod -aG sudo hermes
sudo passwd hermes

Install Hermes

Run it as the hermes user

sudo apt install -y git
sudo -iu hermes bash -c 'curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash' #Full setup

Give hermes LXD access

Add the user to the lxd group so it can drive containers without sudo:

sudo usermod -aG lxd hermes

Re-log (or sudo -iu hermes) for the group to take effect, then confirm:

sudo -iu hermes lxc list

Configure Hermes

As the hermes user, reload the shell and run the setup wizard:

sudo -iu hermes
source ~/.bashrc
hermes setup   # full configuration wizard
hermes tools   # enable tools

Web dashboard

ref

Add the following to ~/.hermes/.env:

HERMES_DASHBOARD_BASIC_AUTH_PASSWORD='********'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin

Run the dashboard as a system service that restarts on failure. Service — /etc/systemd/system/hermes-dashboard.service:

[Unit]
Description=Hermes web dashboard
After=network-online.target
Wants=network-online.target

[Service]
User=hermes
Group=hermes
ExecStart=/home/hermes/.local/bin/hermes dashboard --host 0.0.0.0 --port 9119 --no-open
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now hermes-dashboard.service

Access it at http://<vm-host>:9119, and check it with:

systemctl status hermes-dashboard.service
journalctl -u hermes-dashboard.service -f

Backup

Hermes has a native command that bundles config, the SQLite databases (WAL-safe, works while Hermes is running), .env, auth tokens, skills, sessions, and cron jobs into one timestamped zip — excluding the reinstallable codebase:

hermes backup -o ~/hermes-backup-$(date +%F).zip

Daily backup with a systemd timer

Run the backup once a day, storing archives in ~/backup and pruning anything older than a month. These are system units that drop privileges to the hermes user via User=, so they run without an active login (no lingering required). systemd sets $HOME to /home/hermes for the service.

Backup script — /home/hermes/.local/bin/hermes-backup.sh (owned by hermes):

#!/usr/bin/env bash
set -euo pipefail
backup_dir="$HOME/backup"
mkdir -p "$backup_dir"
"$HOME/.local/bin/hermes" backup -o "$backup_dir/hermes-backup-$(date +%F).zip"
find "$backup_dir" -name 'hermes-backup-*.zip' -mtime +30 -delete

sudo -u hermes chmod +x /home/hermes/.local/bin/hermes-backup.sh

Service — /etc/systemd/system/hermes-backup.service:

[Unit]
Description=Hermes config backup and prune

[Service]
Type=oneshot
User=hermes
Group=hermes
ExecStart=/home/hermes/.local/bin/hermes-backup.sh

Timer — /etc/systemd/system/hermes-backup.timer:

[Unit]
Description=Daily Hermes config backup

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

Enable the timer:

sudo systemctl daemon-reload
sudo systemctl enable --now hermes-backup.timer

Check it:

sudo systemctl list-timers hermes-backup.timer   # next run
sudo systemctl start hermes-backup.service        # run once now to test
journalctl -u hermes-backup.service              # logs

Pull on a remote nightly in cron. The trailing check fails the job (non-zero exit, so cron mails you) if the destination has no backups after the sync:

/usr/bin/bash -c 'set -e; dest=/mnt/tank/backups/hermes; rsync -av --delete "hermes@172.20.30.4:~/backup/hermes-backup-*.zip" "$dest"/; [ -n "$(find "$dest" -maxdepth 1 -name "hermes-backup-*.zip" -print -quit)" ] || { echo "ERROR: no backups in $dest after sync" >&2; exit 1; }'