- HCL 66.6%
- Shell 33.4%
| compose | ||
| scripts | ||
| secrets | ||
| terraform | ||
| .gitignore | ||
| mise.toml | ||
| README.md | ||
| SUWAYOMI.md | ||
| UPDATING.md | ||
hosted-hermes
A private, self-hosted Hermes Agent on a Hetzner server, locked to your Tailscale network (zero public ports), using OpenRouter for models and a Codeberg deploy key so the agent can code.
Provisioned with Terraform + cloud-init so the box is fully reproducible: terraform destroy && terraform apply rebuilds an identical server.
iPhone / Desktop ──(Tailscale, valid TLS)──▶ hermes-box.<tailnet>.ts.net
:443 ─▶ hermes-webui :8787 (chat UI, own login)
:4567 ─▶ Suwayomi :4567 (manga API/WebUI, Basic Auth)
│
▼
Hetzner box · firewall drops ALL public inbound · SSH over Tailscale
┌─ hermes-webui ── ONE container, runs the agent IN-PROCESS ───────────┐
│ reads the single shared /root/.hermes (config · model · plugins │
│ · skills · memory · Codeberg key) and installs + runs the agent │
│ from a read-only source tree at .../hermes-agent │
└──────────────────────────────────────────────────────────────────────┘
Outbound only: OpenRouter · Codeberg (SSH) · Tailscale
One Hermes home, one source of truth. hermes-webui runs the Hermes agent in-process:
it mounts a single shared Hermes home (/root/.hermes) — so config, model, plugins, skills,
memory, and the Codeberg key all live in one place — and installs + runs the agent from a
read-only source tree extracted from the agent image. The separate hermes-gateway container
handles Telegram and scheduled jobs; Suwayomi is an independent manga-server container.
Note: the WebUI container runs the agent in-process, so the gateway daemon (messaging platforms + scheduler/cron) lives in a
hermes-gatewaycontainer sharing the same/root/.hermeshome. That enables Telegram (via the bundled platform adapter + a BotFather token) and scheduled jobs. Other platforms (Signal, WhatsApp, etc.) would need their own adapter/registration — see Deferred follow-ups.
Prerequisites
Gather these before deploying:
- Hetzner Cloud project + API token (read/write) — https://console.hetzner.cloud
- Tailscale account:
- Enable MagicDNS and HTTPS Certificates (admin console → DNS).
- Create an auth key: reusable, pre-authorized, tagged
tag:hermes(definetag:hermesunder Access Controls first; add yourself as an owner).
- OpenRouter API key — https://openrouter.ai/keys
- Codeberg repo you want the agent to work on. The deploy key is already generated
(see
secrets/codeberg.pub); you'll add it below. - Terraform ≥ 1.6 (via
mise) and the Tailscale app on your phone + desktop.
A dedicated admin SSH key (secrets/hermes_admin) is already generated — separate
from your personal key and the blog, so nothing is shared between the two boxes. Terraform
uploads its public half automatically.
Deploy
# 1. Add the Codeberg deploy key (WRITE access) to your repo.
cat secrets/codeberg.pub
# Codeberg → your repo → Settings → Deploy Keys → Add key
# → tick "Enable Write Access". Then protect `main`:
# Settings → Branches → Protect `main` (so the agent works on branches / PRs).
# 2. Fill in your secrets (hcloud_token, tailscale_authkey, tailnet_name,
# openrouter_api_key, dashboard_password [= the WebUI password]).
# The admin SSH key and Codeberg key are read from secrets/ by main.tf.
cd terraform
cp terraform.tfvars.example terraform.tfvars
$EDITOR terraform.tfvars
# 3. Provision.
terraform init
terraform apply
# 4. Wait ~3–4 min: cloud-init installs Docker/Tailscale, EXTRACTS the agent
# source from the agent image, and starts the webui container (which then
# installs the agent's Python deps on first boot). The box appears in
# `tailscale status` as "hermes-box".
Updating this box? Read
UPDATING.md— the canonical runbook for bumping the image pins, updating in place, and rebuilding from scratch. Terraform is provisioning-only (first boot);update.shis how you actually update the running container.
Access
On any device with Tailscale on:
https://hermes-box.<your-tailnet>.ts.net/
Find <your-tailnet> via tailscale status or the admin console. Valid TLS padlock, then
the WebUI login — enter the password from terraform.tfvars (dashboard_password,
which is passed to the container as HERMES_WEBUI_PASSWORD). It sets an HMAC cookie session,
so you log in once per device.
Admin shell (also tailnet-only, uses your tailnet identity — no key needed):
tailscale ssh root@hermes-box
Break-glass (if Tailscale won't come up) via the dedicated key + Hetzner console, or by temporarily allowing inbound 22 in the firewall:
ssh -i secrets/hermes_admin root@<public_ipv4>
Verify (end-to-end)
| Check | Command / action | Expected |
|---|---|---|
| Box on tailnet | tailscale status |
hermes-box online |
| No public access | nmap -Pn <public_ipv4> (see terraform output public_ipv4) |
all filtered |
| Admin | tailscale ssh root@hermes-box |
shell |
| Container up | on box: cd /opt/hermes && docker compose ps |
hermes-webui running (healthy) |
| Agent in-process | on box: docker logs hermes-webui | grep 'agent dir' |
agent dir: … [ok] |
| Health | on box: curl -s localhost:8787/health |
200 |
| Serve mapping | on box: tailscale serve status |
:443 → 8787 |
| WebUI | browser (Tailscale on) → https://…/ |
login, then chat; TLS valid |
| Telegram | message the bot on Telegram (BotFather /newbot) | bot replies (only your user ID is allowed) |
| Locked down | browser (Tailscale off) → the URL | fails to connect |
| OpenRouter | ask the agent something | replies; request shows on OpenRouter |
| Codeberg | ask agent to clone repo, branch, commit, push | branch appears on Codeberg |
| Rebuildable | terraform destroy && terraform apply |
working box from same config |
Operate
- Logs:
tailscale ssh root@hermes-boxthencd /opt/hermes && docker compose logs -f - Update (WebUI + agent, in place):
# On this box. Pins live at the top of scripts/update.sh; bump them to update, # then re-run. Projects + /root/.hermes are host bind-mounts → survive intact. tailscale ssh root@hermes-box bash scripts/update.sh # or copy it over first: scp to /opt/hermes/update.shpulls the pinned webui + agent images, re-extracts the fresh agent source to/opt/hermes-agent-src, anddocker compose up -dto recreate the container (the webui re-pip-installs the agent's deps on boot, ~1–2 min). Raw equivalent if you'd rather drive it by hand:docker pull ghcr.io/nesquena/hermes-webui:0.52.228 docker pull nousresearch/hermes-agent:v2026.8.13 docker create --name agentsrc-extract nousresearch/hermes-agent:v2026.8.13 rm -rf /opt/hermes-agent-src && docker cp agentsrc-extract:/opt/hermes /opt/hermes-agent-src docker rm agentsrc-extract && chown -R 10000:10000 /opt/hermes-agent-src cd /opt/hermes && docker compose up -d - Persistent state (config, model, plugins, memory, skills, deploy key, sessions) lives
in
/root/.hermeson the box. Back it up beforeterraform destroyto keep learned state. - Rotate secrets: edit
terraform.tfvars→terraform apply(rebuilds cloud-init) or edit/opt/hermes/.envon the box anddocker compose up -d.
Security model
- Only entry is the tailnet. The Hetzner firewall (
hcloud_firewall.lockdown) has no inbound rules → all public inbound is dropped. SSH and the WebUI ride Tailscale. - The WebUI requires a login (
HERMES_WEBUI_PASSWORD+ HMAC cookie), and Tailscale Serve terminates TLS in front of it (:443 → 127.0.0.1:8787). The0.0.0.0bind is reachable only via loopback + thetailscale0interface; the firewall blocks the public NIC. - The agent runs in-process inside the webui container as uid
10000(matching the shared home's ownership). All tool execution (git/shell) happens there; the container shipsgitandopenssh-client. It is not asudo-capable image. - The Codeberg key is a dedicated deploy key (single repo, write) — revoke it in Codeberg to
cut the agent off instantly. Keep
mainprotected so the agent can't force-push it. - Never commit
terraform.tfvars,.env, orsecrets/codeberg(all in.gitignore).
Deferred follow-ups (not built yet)
- Custom domain
hermes.beckingham.dev: add an A record → the box's Tailscale100.xIP, and terminate TLS for that hostname with a DNS-01 cert (Caddy/Traefik bound to thetailscale0interface). Needs an API-capable DNS host (Hetzner DNS / deSEC). - Signal channel: needs
signal-cliregistered as a linked device (outbound, so the lockdown doesn't matter) on thehermes-gatewaycontainer. The gateway now runs (added for Telegram), so Signal is a small step from here — addsignal-cli, link it, and enable the platform. - Hardening: SOPS+age encrypted secrets in-repo; BuyPass (NO) CA + Traefik (FR);
Headscale for a self-hosted control plane; scheduled
/root/.hermesbackups.
Notes / caveats to confirm on first run
nousresearch/hermes-agentarm64 support is unconfirmed —server_typedefaults to x86 (cx23, same type as beckingham-infra). Verify before switching to an Amperecax*type.- First boot extracts the agent source (~1.2 GB copied from the 3.8 GB agent image) and
then installs the agent's Python deps into the webui venv (~1–2 min). The UI answers
/healthbefore that finishes; give chat a minute on a cold box. tailscale serveflag syntax varies by version; cloud-init uses--https=443 …. Checktailscale serve statusif the UI 404s.- Tailnet SSH needs an ACL grant (
src: autogroup:member,dst: tag:hermes,users: ["root"]) in the Tailscale admin console — tagged nodes aren't covered by the default "access your own devices" rule. - The
hermes-webuistartup log should showagent dir: … [ok]andconfig file: … (found). If it instead warnshermes-agent source not found, the/opt/hermes-agent-srcextraction didn't happen — re-run the extract step in Operate.