dank/serverAppConfigs
1
0 Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(hermes): document namespace addressability and fix stale claims

Browse Source 
New page Architecture/Container Network Namespaces.md: which local services are
addressable from which Podman network namespace on Dankclaw (rootless podman +
netavark). Verified live 2026-09-02: gateway/webui/CDP run in the host netns and
dial loopback; hermes-dashboard is the only Hermes container on a bridge network
(dankclaw_default, 10.89.1.0/24 gw 10.89.1.1) and can dial published ports only —
unpublished host-netns listeners (signal-cli :8080, webui :8787) are refused from
that namespace even though both bind 0.0.0.0.

Corrected while verifying the above:
- Hermes.md: data root is /home/dank/Containers/hermes/data (not the retired
  /home/dank/hermes-data); gateway dials the Signal daemon on loopback; the
  daemon itself is a host user unit (signal-cli-daemon.service) bound to
  0.0.0.0:8080, so the Signal HTTP API is LAN-reachable.
- Hermes-Dashboard.md: it is a Quadlet unit (Network=dankclaw_default), not a
  compose service; data root + /opt/data anonymous volume corrected.
- Hermes-WebUI.md: binds 0.0.0.0:8787 in the host netns (verified: unauthenticated
  GET /health from another LAN machine returned 200) — the SSH tunnel is an access
  path, not a containment boundary; HealthCmd and data-path corrections.
- Network Architecture.md: no hermes vhost exists in either the tracked or the live
  Caddyfile (hermes.franksdank.cloud resolves but routes nowhere); SearXNG exits the
  tunnel via the shared named network searxng.network, not service:gluetun.

Docs only — deploy is a no-op for this change.
This commit is contained in:
Frank committed 2026-09-02 16:10:57 -07:00
1 parent 834ad54112
commit 2e179b024d
6 files changed
+213 -30
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

serverAppConfigs-docs/Dankclaw/Hermes-WebUI.md
+33 -17
View File
@@ -1,7 +1,7 @@
---
type: configuration
title: Hermes-WebUI (Hermex server)
description: The hermes-webui compose service on Dankclaw — the loopback-only API server that the Hermex iPhone app talks to over an SSH tunnel.
description: The hermes-webui container on Dankclaw — the API server that the Hermex iPhone app talks to, reachable over an SSH tunnel and, because it binds all interfaces, from the whole LAN.
tags:
- hermes
- hermes-webui
@@ -19,7 +19,7 @@ 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:** `127.0.0.1:8787` (loopback only) — **Ingress:** SSH tunnel
**Host:** Dankclaw — **Port:** `0.0.0.0:8787` (all interfaces) — **Ingress:** SSH tunnel for the phone app; direct LAN access also works
## Facts
@@ -27,11 +27,11 @@ agent — same memory, skills, and sessions — as the [[Hermes]] gateway and th
|------|-------|
| Image | `docker.io/nousresearch/hermes-agent:latest` (same as the gateway) |
| Command | `python3 /webui/bootstrap.py --foreground` |
| Source checkout | `/home/dank/hermes-webui` on Dankclaw (mounted at `/webui`) |
| Port | `8787`, published to `127.0.0.1` only |
| 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 | shares `/home/dank/hermes-data` with the gateway and dashboard |
| Health | `GET /health` (compose healthcheck + deployer) |
| 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
@@ -56,9 +56,15 @@ gateway's `0600` state files.
## Remote access (Hermex on iOS — persistent SSH tunnel)
Only port `22` is forwarded to Dankclaw at the router, so the webui is
reached through an SSH **local forward** — no extra router ports, no
third-party relay (no Tailscale, no Cloudflare). Implemented 2026-08-31:
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
@@ -88,8 +94,8 @@ third-party relay (no Tailscale, no Cloudflare). Implemented 2026-08-31:
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 127.0.0.1:8787"]
D --> E["/home/dank/hermes-data (shared agent state)"]
C --> D["hermes-webui 0.0.0.0:8787 (host netns)"]
D --> E["/home/dank/Containers/hermes/data (shared agent state)"]
```
## Deployment
@@ -98,8 +104,11 @@ graph LR
./scripts/deploy.sh dankclaw --service hermes-webui
```
The planner maps changes to the `hermes-webui` compose block (and only that
block) to this service, so gateway and inference restarts stay isolated.
`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`.
@@ -107,10 +116,16 @@ Before first deploy, set a strong `HERMES_WEBUI_PASSWORD` in the live
- The `/webui` mount is **rw on purpose**: `bootstrap.py` creates `.venv` in
the repo root. Do not flip it to `:ro`.
- Never publish `8787` beyond loopback without keeping the password set —
the webui can run agent commands.
- The webui and the gateway share one data volume. A config change made on one
side takes effect when the other restarts (same caveat as the dashboard).
- 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.
@@ -125,3 +140,4 @@ Before first deploy, set a strong `HERMES_WEBUI_PASSWORD` in the live
- [[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