docs(hermes): document namespace addressability and fix stale claims
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
1 parent
834ad54112
commit
2e179b024d
6 files changed
+213
-30
No files matched your search
@@ -12,17 +12,36 @@ The Hermes web dashboard is a browser UI for managing the agent. It shows config
|
||||
| Command | `hermes dashboard --host 0.0.0.0 --port 9119 --no-open --skip-build` |
|
||||
| Port | `9119` (published to the LAN) |
|
||||
| Auth | HTTP basic auth (username + scrypt password hash) |
|
||||
| Data | shares `/home/dank/hermes-data` with the gateway |
|
||||
| Data | bind mount `/home/dank/Containers/hermes/data` → `/data`, shared with the gateway; plus a fresh anonymous volume at `/opt/data` per recreation |
|
||||
|
||||
## Why a separate container
|
||||
|
||||
The gateway container runs `hermes gateway run` (the Signal platform). That entrypoint does not start the dashboard. The dashboard is a separate process. So it runs in its own compose service (`hermes-dashboard`). Both services mount the same data volume. Both restart at boot (`restart: unless-stopped`).
|
||||
The gateway container runs `hermes gateway run` (the Signal platform). That
|
||||
entrypoint does not start the dashboard. The dashboard is a separate process, so
|
||||
it runs in its own Quadlet unit
|
||||
([`dankclaw/hermes/quadlet/hermes-dashboard.container`](../../dankclaw/hermes/quadlet/hermes-dashboard.container):
|
||||
image `localhost/hermes-agent:latest`, `Pull=never`, `Exec=hermes dashboard
|
||||
--host 0.0.0.0 --port 9119 --no-open --skip-build`, `Restart=always`,
|
||||
`RestartSec=5`). All three Hermes containers mount the same `/data` bind mount.
|
||||
|
||||
Unlike its two siblings — `hermes.container` and `hermes-webui.container` both
|
||||
run with `Network=host` — the dashboard is the only Hermes container on a bridge
|
||||
network (`Network=dankclaw_default`, subnet `10.89.1.0/24`, gateway `10.89.1.1`).
|
||||
That has a functional consequence: from inside its namespace it can dial only
|
||||
published ports via the gateway IP, and `host.containers.internal`
|
||||
(`169.254.1.2`) is an alias on the *default* `podman` network that this container
|
||||
is not attached to, so probes to it time out. It therefore never talks to the
|
||||
gateway, the webui, or the CDP daemon over the network — it shares their state
|
||||
through the bind mount instead. See [[Container Network Namespaces]].
|
||||
|
||||
## Authentication
|
||||
|
||||
The dashboard refuses to bind to a non-loopback address without an auth provider. There is no unauthenticated public bind. This repo uses basic auth:
|
||||
|
||||
- `dashboard.basic_auth.username` and `dashboard.basic_auth.password_hash` live in the live `/home/dank/hermes-data/config.yaml`; the tracked backup at `dankclaw/hermes/config.yaml.example` intentionally omits the password hash.
|
||||
- `dashboard.basic_auth.username` and `dashboard.basic_auth.password_hash` live in
|
||||
the live `/data/config.yaml` (host path
|
||||
`/home/dank/Containers/hermes/data/config.yaml`); the tracked backup at
|
||||
`dankclaw/hermes/config.yaml.example` intentionally omits the password hash.
|
||||
- The stored value is a one-way scrypt hash. The plaintext password is never written to a file or the repo.
|
||||
- The hash is generated with `plugins.dashboard_auth.basic.hash_password`.
|
||||
|
||||
@@ -39,3 +58,4 @@ Open `http://192.168.0.143:9119` in a browser on the LAN. Log in with the config
|
||||
## See Also
|
||||
|
||||
- [[Hermes-WebUI]] — the phone-facing API server (Hermex)
|
||||
- [[Container Network Namespaces]] — why this container cannot dial the gateway, webui, or CDP daemon
|
||||
@@ -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
|
||||
@@ -4,8 +4,11 @@ Hermes is the self-improving AI agent from Nous Research. It runs in a terminal,
|
||||
|
||||
**Host:** Dankclaw — **Hostname:** `hermes.dankclaw.local` — **Docs:** https://hermes-agent.nousresearch.com/docs
|
||||
|
||||
**Persistent state:** `/home/dank/hermes-data` on Dankclaw, mounted as `/data` in
|
||||
both containers. The tracked, sanitized configuration baseline is
|
||||
**Persistent state:** `/home/dank/Containers/hermes/data` on Dankclaw, bind-mounted
|
||||
at `/data` in all three Hermes containers (gateway, webui, dashboard). Each
|
||||
container additionally gets an anonymous volume at `/opt/data`, which is
|
||||
re-created empty on every container recreation — anything that lives only there
|
||||
is not durable. The tracked, sanitized configuration baseline is
|
||||
[`dankclaw/hermes/config.yaml.example`](../../dankclaw/hermes/config.yaml.example).
|
||||
|
||||
## Facts (from research, primary source)
|
||||
@@ -22,7 +25,12 @@ both containers. The tracked, sanitized configuration baseline is
|
||||
## Configuration
|
||||
|
||||
- Point Hermes at the local model endpoint or an external provider through its provider config.
|
||||
- The gateway process exposes one port for chat integration; the exact port is set in the Hermes config (`8090` convention in this repo).
|
||||
- The gateway runs `hermes gateway run --force -v` in the **host** network
|
||||
namespace (`Network=host` in its Quadlet unit) and reaches the Signal daemon at
|
||||
`http://127.0.0.1:8080`. That loopback hop works only because the gateway is in
|
||||
the host netns — see [[Container Network Namespaces]]. The daemon itself is a
|
||||
**host** user unit (`signal-cli-daemon.service`), not a container, and binds
|
||||
`0.0.0.0:8080`, so the Signal HTTP API is reachable from the whole LAN.
|
||||
- The data volume persists skills, memory, and session history.
|
||||
- Hermes has two named local providers: `dankclaw-large` reaches
|
||||
`http://192.168.0.143:7770/v1` and exposes `frank-default-large`;
|
||||
@@ -33,9 +41,11 @@ both containers. The tracked, sanitized configuration baseline is
|
||||
|
||||
## Volumes
|
||||
|
||||
| Container path | Host path (convention) |
|
||||
|----------------|------------------------|
|
||||
| `/data` | `/home/dank/hermes-data` |
|
||||
| Container path | Host path (live) | Backing |
|
||||
|----------------|------------------|---------|
|
||||
| `/data` | `/home/dank/Containers/hermes/data` | bind mount (durable; shared by all three containers) |
|
||||
| `/webui` | `/home/dank/Containers/hermes/webui` | bind mount (webui only — the `bootstrap.py` venv lives here) |
|
||||
| `/opt/data` | anonymous volume | image `VOLUME`; fresh empty volume per recreation |
|
||||
|
||||
## Gotchas
|
||||
|
||||
@@ -64,3 +74,4 @@ restart) pays one first-call npm download; subsequent calls are cached.
|
||||
- [[Dankclaw Stack]]
|
||||
- [[OpenWebUI]] — the chat UI that pairs with Hermes
|
||||
- Knowledge base: [[SearXNG]] (Hermes as the search agent)
|
||||
- [[Container Network Namespaces]] — why the gateway and webui can dial loopback services and the dashboard cannot
|
||||
Reference in new issue
Block a user