homelab-agent: deployment tool for Hermes Agent

Scripted setup that turns a used mini PC into an always-on Hermes Agent server with n8n, Pi-hole and backups

What homelab-agent does

The reference machine is a 70 euro used Shuttle DS61 with an Intel i5-3475S and 8 GB of RAM. The model runs in the cloud on your own OpenAI, Anthropic or OpenRouter account, or locally if you have the hardware, while the box hosts Hermes Agent, its memory and its tools around the clock. You chat with Hermes on Telegram or WhatsApp and can let it code and push to GitHub.

Beyond Hermes, the stack can include n8n for workflows that call Hermes's OpenAI-compatible API, Pi-hole for DNS, Uptime Kuma, Beszel for system stats, opt-in local AI services on an NVIDIA GPU, Caddy for local names, Tailscale for remote access with no open ports, and restic for nightly encrypted backups pulled to a Mac. Every service except Caddy is optional through a MODULES setting in config.env. The setup.sh script is safe to re-run, and the README puts total time at about an hour.

Key features

One setup.sh command that installs Docker, the firewall, Tailscale and the chosen services
Optional modules for Hermes, n8n, Pi-hole, Uptime Kuma and Beszel
Caddy gives each service a local *.home.arpa name
Nightly encrypted restic backups pulled to a Mac
Rebuild of a dead box from the repo plus the latest backup

When to use it

Running Hermes Agent 24/7 on a spare mini PC at home
Connecting n8n workflows to Hermes through its OpenAI-compatible API
Reaching a home agent server from anywhere over Tailscale without opening ports

Who it is for: Home-lab users who want a reproducible, always-on Hermes Agent server on cheap hardware.

How it fits with Hermes Agent

Hermes Agent is the central service of the stack and is configured through Hermes's own setup during installation.

How to install homelab-agent

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

git clone https://github.com/sjespersen/homelab-agent && cd homelab-agent
./setup.sh

Requirements: An x86-64 PC with 8 GB RAM and an SSD running Ubuntu Server (tested on 26.04), a macOS or Linux computer to set up from, a free Tailscale account and an LLM provider account

Note: The backup pull script in the mac/ folder works only on macOS.

FAQ

What is homelab-agent?

homelab-agent is a repository of scripts and Docker Compose stacks that set up an always-on AI agent server on a used mini PC. It runs Hermes Agent together with optional n8n, Pi-hole, monitoring, Tailscale and backups.

Does homelab-agent work with Hermes Agent?

Yes, Hermes Agent is its main service. The installer starts Hermes's own setup for the model, login and chat apps.

What do I need to run homelab-agent?

You need an x86-64 PC with 8 GB RAM and an SSD, Ubuntu Server, a free Tailscale account and an LLM provider account. A macOS or Linux computer is used for setup, or you can run ./setup.sh --local on the server.