Deploying Hermes in Your Homelab

Why Run Hermes Separately

You could install Hermes on your workstation and use it from there, and for personal use that is perfectly reasonable. But for a homelab agent -- one that runs scheduled tasks, responds to Telegram messages overnight, and checks infrastructure on a schedule -- you want it running somewhere persistent: a machine that stays on, on your network, that you can reach from anywhere.

Proxmox VE is the natural home for this. It gives you resource controls, snapshots, easy backup, and network policy per VM or container. If you are running TrueNAS SCALE, Hermes is also available as a community app, which makes the initial deployment even simpler. This lesson covers both paths.

Option A: Proxmox VM

A dedicated VM is the most flexible option. Recommended sizing for a homelab Hermes agent:

• OS: Ubuntu Server 24.04 LTS (or Debian 12)
• vCPUs: 2 (4 if you use browser automation frequently)
• Memory: 8 GB minimum
• Disk: 60 GB (sessions, skills, model cache, and workspaces accumulate over time)
• User: Non-root service account -- create a dedicated hermes user, not root
• Network: Bind Hermes to localhost or an internal VLAN only -- never expose management ports directly to the internet

Once the VM is up, install Hermes the same way you did in Track 18 Lesson 2. The install script works identically on Ubuntu Server.

Option B: Proxmox LXC

An unprivileged LXC is lighter than a full VM and works well for Hermes as long as you configure it correctly. Two settings are required:

• nesting = true -- Hermes manages internal subprocess trees and needs this
• A non-root hermes user with no sudo access

If you are running Hermes on ZFS storage, avoid Docker inside the LXC -- ZFS and Docker's overlay2 driver conflict. Install Hermes directly (bare-metal in the LXC) using install.sh --skip-setup. The install takes 5-10 minutes and pulls Python 3.11 and Node.js 22.

Option C: TrueNAS SCALE Community App

TrueNAS SCALE users can find Hermes Agent in the Community catalog. Install it like any other app; it deploys as a containerized service. The TrueNAS app maps Hermes's internal ports to external ports on your system:

• 30432 -- Gateway (messaging platform connections)
• 30433 -- Web dashboard (Hermes's internal default port is 9119; TrueNAS remaps it to 30433)
• 30440 -- Webhook listener

On a standalone VM or LXC install (not TrueNAS), the dashboard runs on port 9119 by default. The app runs with elevated container privileges (root user, CHOWN and DAC_OVERRIDE capabilities) -- this is required for the container to manage its own files. Point storage at a host path or ixVolume dataset so that sessions and memory persist across app updates.

Running Hermes as a Persistent Service

Whether you chose VM or LXC, you want Hermes running as a background service so it survives SSH session ends and reboots. Use hermes gateway to manage this.

For a dedicated homelab server (recommended): Install as a system-wide service so it starts at boot even when no user is logged in:

# Install as a system service (requires sudo)
sudo hermes gateway install --system

# Enable at boot and start now
sudo systemctl enable --now hermes-gateway

For WSL or a single-user workstation: Install as a user-level service instead:

# Install as a user service (no sudo needed)
hermes gateway install

# Enable and start
systemctl --user enable --now hermes-gateway

# Allow service to start at boot even without an active login session
loginctl enable-linger $USER

In either case, the gateway process handles messaging platform connections (Telegram, Discord), the cron scheduler, and webhook listeners. It must be running for scheduled morning briefings (Lesson 7) and Telegram message delivery to work.

Other gateway management commands:

hermes gateway status    # check if running
hermes gateway restart   # restart after a config change
hermes gateway stop      # stop the service

# If running as a system service, prefix with sudo:
sudo hermes gateway restart

Securing the Dashboard

After deployment, Hermes exposes a web dashboard (port 9119 by default; port 30433 if using the TrueNAS app). The dashboard reads and writes your .env file, which contains API keys and secrets. Do not leave it unauthenticated or bind it to a public IP.

In June 2026, exposed unauthenticated Hermes dashboards were found by internet scanners, and the agent was instructed via the dashboard to plant an SSH key backdoor. The auth gate is now mandatory on every non-loopback bind.

Set all three credential variables before binding beyond localhost:

# In ~/.hermes/.env
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=yourusername
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=a-strong-password
HERMES_DASHBOARD_BASIC_AUTH_SECRET=32-or-more-random-bytes-for-token-signing

For remote access, put Hermes behind a VPN (Tailscale or WireGuard) rather than exposing the port to the public internet. The documentation explicitly states that basic auth is "intended for self-hosted / on-prem / homelab dashboards on a trusted network only" -- for internet-facing deployments, use OAuth instead.

Snapshot Before You Experiment

Take a Proxmox snapshot of your Hermes VM immediately after a clean install and basic config. Skill experiments and SOUL.md changes can accumulate state you may want to roll back. With a snapshot, you can always return to a clean baseline in seconds.