Frank
1e491fa69f
Post-change doc reconciliation for the hermes vhosts + DNS deletion batch: - Hermes-Dashboard.md: access is now the hermesadmin.franksdank.cloud vhost (direct Caddy proxy to 192.168.0.143:9119, no guard chain — exempt because the dashboard enforces its own basic-auth login), plus the raw LAN port. The old text claimed an Authentik-guarded public vhost, which was decommissioned. - Hermes-WebUI.md: description updated — the webui is now also reachable via the unguarded hermes.franksdank.cloud vhost (its own password auth is the gate). - LAN-DNS.md: "add a name in two places" corrected to a two-or-three-step decision; internal-only names (prometheus/loki/grafana/seerr) deliberately get no public A record and resolve on the LAN only, and DNS-01 issuance is unaffected because the challenge is a TXT record in the same zone. - Seerr.md: DNS row corrected — addn-hosts only since 2026-09-02; NXDOMAIN on WAN. - hermes-dashboard.container: unit comment no longer claims Authentik termination. No behavior change in this commit; tests 233/233 green (docs-completeness seam included).
144 lines
7.2 KiB
Markdown
144 lines
7.2 KiB
Markdown
---
|
|
type: configuration
|
|
title: Hermes-WebUI (Hermex server)
|
|
description: The hermes-webui container on Dankclaw — the API server that the Hermex iPhone app talks to, reachable over an SSH tunnel, from the whole LAN (it binds all interfaces), and from https://hermes.franksdank.cloud (internal-only vhost).
|
|
tags:
|
|
- hermes
|
|
- hermes-webui
|
|
- hermex
|
|
- dankclaw
|
|
- ssh-tunnel
|
|
timestamp: 2026-09-14
|
|
---
|
|
|
|
# Hermes-WebUI (Hermex server)
|
|
|
|
`hermes-webui` is the [hermes-webui](https://github.com/nesquena/hermes-webui)
|
|
server (MIT, third-party) that the **Hermex** iPhone app connects to. It runs
|
|
the Hermes agent in-process from the shared `HERMES_HOME`, so it is the *same*
|
|
agent — same memory, skills, and sessions — as the [[Hermes]] gateway and the
|
|
[[Hermes-Dashboard]].
|
|
|
|
**Host:** Dankclaw — **Port:** `0.0.0.0:8787` (all interfaces) — **Ingress:** SSH tunnel for the phone app; direct LAN access also works
|
|
|
|
## Facts
|
|
|
|
| Item | Value |
|
|
|------|-------|
|
|
| Image | `docker.io/nousresearch/hermes-agent:latest` (same as the gateway) |
|
|
| Command | `python3 /webui/bootstrap.py --foreground` |
|
|
| Source checkout | `/home/dank/Containers/hermes/webui` on Dankclaw, bind-mounted at `/webui` |
|
|
| Port | `8787`, bound to `0.0.0.0` in the **host** network namespace (`Network=host`) — LAN-reachable, not loopback-only |
|
|
| Auth | `HERMES_WEBUI_PASSWORD` (host `.env`; Hermex signs in with it) |
|
|
| Data | bind mount `/home/dank/Containers/hermes/data` → `/data`, shared with the gateway and dashboard; anonymous volume at `/opt/data` |
|
|
| Health | `HealthCmd=` in the Quadlet unit probes `http://127.0.0.1:8787/health` from inside the unit (works because the webui runs in the host netns); the deployer probes the same path from the host |
|
|
|
|
## Why a container, not a host process
|
|
|
|
The gateway's state files are owned by the container-mapped uid (`109999`,
|
|
from rootless Podman's `1 → 100000/65536` subuid range). A fresh rootless
|
|
namespace on Dankclaw maps identically (verified with `podman unshare
|
|
cat /proc/self/uid_map`), so a second container using the same image reads
|
|
and writes the shared volume with exactly the ownership the gateway already
|
|
uses. A host-side process running as `dank` (uid 1000) could not read the
|
|
gateway's `0600` state files.
|
|
|
|
## How it works
|
|
|
|
- `bootstrap.py` creates `/webui/.venv` on first boot, pip-installs the WebUI
|
|
and agent requirements, then **execs** `server.py` as one foreground process
|
|
(`--foreground`). systemd-free: Podman supervises it via
|
|
`restart: unless-stopped`.
|
|
- `HERMES_WEBUI_SKIP_ONBOARDING=1` keeps the first-run wizard off; a profile
|
|
already exists in `/data` from the gateway.
|
|
- The healthcheck `start_period` is 600 s because the very first boot spends
|
|
minutes pip-installing into a fresh venv.
|
|
|
|
## Remote access (Hermex on iOS — persistent SSH tunnel)
|
|
|
|
Only port `22` is forwarded to Dankclaw at the router, so the phone reaches the
|
|
webui through an SSH **local forward** — no extra router ports, no third-party
|
|
relay (no Tailscale, no Cloudflare). Implemented 2026-08-31. The tunnel is an
|
|
*access path* for the phone, **not** a containment boundary: the server binds
|
|
`0.0.0.0:8787`, so any host that can route to `192.168.0.143` can reach the API
|
|
directly and needs only `HERMES_WEBUI_PASSWORD` to get in (verified 2026-09-02:
|
|
an unauthenticated `GET /health` from another LAN machine returned HTTP 200).
|
|
See [[Container Network Namespaces]] for why the webui is reachable this way and
|
|
the sibling dashboard on `9119` is not.
|
|
|
|
- Dedicated `tunnel` account on Dankclaw (`/usr/sbin/nologin` shell, password
|
|
locked). Authentication is key-only; the account can do nothing except
|
|
authenticate — `ForceCommand /usr/sbin/nologin` kills any session channel
|
|
while the transport stays up for port forwarding.
|
|
- sshd drop-in `/etc/ssh/sshd_config.d/99-tunnel.conf` scopes
|
|
`AllowTcpForwarding yes` to that user only (plus `PermitTTY no`,
|
|
`X11Forwarding no`).
|
|
- Key options on the authorized key pin the blast radius:
|
|
`command="/usr/sbin/nologin",no-pty,restrict,port-forwarding,permitopen="localhost:8787"`
|
|
— a leaked tunnel key can only forward to `localhost:8787`, never act as a
|
|
general SOCKS/SSH proxy.
|
|
- On the phone (client side): create a key on-device (private key never
|
|
leaves the device), hand the **public** key to the admin who appends it to
|
|
`/home/tunnel/.ssh/authorized_keys`, then connect from the SSH client:
|
|
- In-network target `192.168.0.143:22`, off-network target the public
|
|
hostname (router forwards only port 22 → Dankclaw) — same forward config
|
|
otherwise.
|
|
- Local forward `127.0.0.1:8787 → localhost:8787`; Hermex server URL is then
|
|
`http://localhost:8787` in both locations.
|
|
- For a *persistent* tunnel on iOS, Secure ShellFish's personal-VPN mode
|
|
(Network Extension keeps the tunnel up and routes `127.0.0.0/8` through
|
|
it); Termius works but only while its session is connected — iOS allows no
|
|
background SSH daemon.
|
|
|
|
```mermaid
|
|
graph LR
|
|
A[Hermex app] -->|http://localhost:8787| B[SSH local forward on iPhone<br/>persistent via personal VPN]
|
|
B ==>|encrypted SSH to port 22| C[Dankclaw sshd<br/>tunnel user, forced nologin]
|
|
C --> D["hermes-webui 0.0.0.0:8787 (host netns)"]
|
|
D --> E["/home/dank/Containers/hermes/data (shared agent state)"]
|
|
```
|
|
|
|
## Deployment
|
|
|
|
```
|
|
./scripts/deploy.sh dankclaw --service hermes-webui
|
|
```
|
|
|
|
`deploy.sh` copies `dankclaw/hermes/quadlet/*.container` into the quadlet unit
|
|
directory and restarts `hermes.service`, `hermes-dashboard.service` and
|
|
`hermes-webui.service` in the **user** manager of `dank` (linger must be on for
|
|
them to come up at boot), so gateway/dashboard/webui restarts stay isolated from
|
|
inference deploys.
|
|
Before first deploy, set a strong `HERMES_WEBUI_PASSWORD` in the live
|
|
`dankclaw/.env`.
|
|
|
|
## Gotchas
|
|
|
|
- The `/webui` mount is **rw on purpose**: `bootstrap.py` creates `.venv` in
|
|
the repo root. Do not flip it to `:ro`.
|
|
- The webui binds `0.0.0.0:8787` today, so the SSH tunnel is an access path for
|
|
the phone, not a security boundary: any LAN host that can route to
|
|
`192.168.0.143` reaches the API and needs only `HERMES_WEBUI_PASSWORD`. The
|
|
webui can run agent commands, so treat that password as a credential with
|
|
command-execution blast radius. To make loopback-only binding true again, set
|
|
`HERMES_WEBUI_HOST=127.0.0.1` in the unit and require the tunnel for every
|
|
client — that is an exposure change to decide deliberately, not a silent fix.
|
|
- The webui and the gateway share one data root (`/data` is a bind mount of
|
|
`/home/dank/Containers/hermes/data`). A config change made on one side takes
|
|
effect when the other restarts (same caveat as the dashboard).
|
|
- `bootstrap.py` auto-installs a Hermes Agent if it cannot find one; in this
|
|
image the agent is already present, so that path should never fire. If the
|
|
log shows an install attempt, the image changed — re-verify the entrypoint.
|
|
|
|
# Citations
|
|
|
|
- hermes-webui README (env vars, `--foreground`, `/health`): https://github.com/nesquena/hermes-webui
|
|
- Hermex setup model (server URL + password; Cloudflare/Tailscale are optional, not required): https://hermexapp.com/
|
|
|
|
## See Also
|
|
|
|
- [[Hermes]] — the agent and its Signal gateway
|
|
- [[Hermes-Dashboard]] — the LAN browser management UI
|
|
- [[Dankclaw Stack]]
|
|
- [[Container Network Namespaces]] — why this host-netns service is LAN-reachable
|