No description
  • HCL 66.6%
  • Shell 33.4%
Find a file
2026-09-21 19:53:25 +02:00
compose chore: bump image pins (webui 0.52.329, agent v2026.9.14) 2026-09-21 16:47:41 +00:00
scripts chore: bump image pins (webui 0.52.329, agent v2026.9.14) 2026-09-21 16:47:41 +00:00
secrets Initial commit: private Hermes Agent on Hetzner (Terraform + cloud-init) 2026-07-19 18:04:11 +01:00
terraform chore: bump image pins (webui 0.52.329, agent v2026.9.14) 2026-09-21 16:47:41 +00:00
.gitignore Initial commit: private Hermes Agent on Hetzner (Terraform + cloud-init) 2026-07-19 18:04:11 +01:00
mise.toml Initial commit: private Hermes Agent on Hetzner (Terraform + cloud-init) 2026-07-19 18:04:11 +01:00
README.md feat: add tailnet-only Suwayomi server 2026-09-03 15:34:10 +00:00
SUWAYOMI.md fix: persist Suwayomi extension store 2026-09-03 15:55:24 +00:00
UPDATING.md feat: add tailnet-only Suwayomi server 2026-09-03 15:34:10 +00:00

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-gateway container sharing the same /root/.hermes home. 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:

  1. Hetzner Cloud project + API token (read/write) — https://console.hetzner.cloud
  2. Tailscale account:
    • Enable MagicDNS and HTTPS Certificates (admin console → DNS).
    • Create an auth key: reusable, pre-authorized, tagged tag:hermes (define tag:hermes under Access Controls first; add yourself as an owner).
  3. OpenRouter API key — https://openrouter.ai/keys
  4. Codeberg repo you want the agent to work on. The deploy key is already generated (see secrets/codeberg.pub); you'll add it below.
  5. 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.sh is 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-box then cd /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.sh pulls the pinned webui + agent images, re-extracts the fresh agent source to /opt/hermes-agent-src, and docker compose up -d to 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/.hermes on the box. Back it up before terraform destroy to keep learned state.
  • Rotate secrets: edit terraform.tfvars → terraform apply (rebuilds cloud-init) or edit /opt/hermes/.env on the box and docker 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). The 0.0.0.0 bind is reachable only via loopback + the tailscale0 interface; 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 ships git and openssh-client. It is not a sudo-capable image.
  • The Codeberg key is a dedicated deploy key (single repo, write) — revoke it in Codeberg to cut the agent off instantly. Keep main protected so the agent can't force-push it.
  • Never commit terraform.tfvars, .env, or secrets/codeberg (all in .gitignore).

Deferred follow-ups (not built yet)

  • Custom domain hermes.beckingham.dev: add an A record → the box's Tailscale 100.x IP, and terminate TLS for that hostname with a DNS-01 cert (Caddy/Traefik bound to the tailscale0 interface). Needs an API-capable DNS host (Hetzner DNS / deSEC).
  • Signal channel: needs signal-cli registered as a linked device (outbound, so the lockdown doesn't matter) on the hermes-gateway container. The gateway now runs (added for Telegram), so Signal is a small step from here — add signal-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/.hermes backups.

Notes / caveats to confirm on first run

  • nousresearch/hermes-agent arm64 support is unconfirmed — server_type defaults to x86 (cx23, same type as beckingham-infra). Verify before switching to an Ampere cax* 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 /health before that finishes; give chat a minute on a cold box.
  • tailscale serve flag syntax varies by version; cloud-init uses --https=443 …. Check tailscale serve status if 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-webui startup log should show agent dir: … [ok] and config file: … (found). If it instead warns hermes-agent source not found, the /opt/hermes-agent-src extraction didn't happen — re-run the extract step in Operate.