docs: clarify Docker localhost and sudo compose setup

CHANGELOG.md

@@ -3,6 +3,10 @@
 
 ## [Unreleased]
 
+### Documentation
+
+- Clarify two Docker onboarding traps: `sudo docker compose` can mount `/root/.hermes` instead of the user's Hermes home on Linux, and Linux Docker Engine users should use a `host-gateway` alias such as `api.local` for host-local model servers instead of configuring `localhost` inside the container. (#3006, #3012)
+
 ## [v0.51.152] — 2026-05-28 — Release DX (stage-batch34 — single-PR optional gateway-backed browser chat)
 
 ### Added

docs/docker.md

@@ -58,6 +58,14 @@ your real `~/.hermes` unless you intentionally want to test real state. Use an
 isolated Hermes home and follow
 [`docs/onboarding-agent-checklist.md`](onboarding-agent-checklist.md) instead.
 
+> **Linux note**: run Compose as the user who owns the Hermes home. The command
+> `sudo docker compose up -d` can make Compose expand `${HOME}` as `/root`, so
+> the default `${HOME}/.hermes` bind mount becomes `/root/.hermes` instead of
+> your user's real Hermes directory. Prefer adding your user to the `docker group`
+> and running `docker compose up -d`; if you must preserve the caller environment
+> for a one-off root run, use `sudo -E docker compose up -d` and verify the
+> rendered mount with `docker compose config` first.
+
 ## Scheduled jobs and the gateway daemon
 
 **Symptom**: Cron jobs created in the Tasks panel never fire. System Settings shows the orange "Gateway not configured" pill, and the Tasks panel shows the same banner above the job list.

docs/onboarding.md

@@ -121,12 +121,24 @@ API root. Common examples:
 | Ollama on the same non-Docker host | `http://127.0.0.1:11434/v1` |
 | LM Studio from Docker Desktop | `http://host.docker.internal:1234/v1` |
 | Ollama from Docker Desktop | `http://host.docker.internal:11434/v1` |
+| Local server from Linux Docker Engine | `http://api.local:<port>/v1` with `api.local:host-gateway` in Compose `extra_hosts` |
 | Local server on another LAN machine | `http://<lan-ip>:<port>/v1` |
 
 Inside Docker, `localhost` means the WebUI container itself, not your Mac,
-Windows host, or another machine on your LAN. If LM Studio or Ollama is running
-outside the container, use `host.docker.internal` on Docker Desktop or the
-server's LAN IP address.
+Windows host, Linux host, or another machine on your LAN. If LM Studio or Ollama
+is running outside the container, use `host.docker.internal` on Docker Desktop,
+use the server's LAN IP address, or add a Linux Docker host alias:
+
+```yaml
+services:
+  hermes-webui:
+    extra_hosts:
+      - "api.local:host-gateway"
+```
+
+Then use `http://api.local:<port>/v1` as the Base URL. The alias avoids writing
+`localhost` in WebUI config where it would resolve to the container loopback
+instead of the host service.
 
 The wizard probes `<base-url>/models` before saving. A successful probe fills
 the model dropdown. A failed probe blocks the setup step and shows an inline

tests/test_v050260_docker_invariants.py

@@ -262,3 +262,29 @@ def test_env_docker_example_warns_about_home_mode_asymmetry():
         ".env.docker.example must include a MULTI-CONTAINER WARNING about "
         "the HERMES_HOME_MODE semantic asymmetry between WebUI and agent."
     )
+
+
+# ── 8: Docker localhost and sudo-compose troubleshooting (#3006, #3012) ────
+
+
+def test_docs_docker_warns_about_sudo_compose_home_expansion():
+    """REGRESSION (#3006): the Docker guide must explain that
+    `sudo docker compose` can expand `${HOME}` to `/root`, mounting the wrong
+    `.hermes` directory into the container."""
+    src = (REPO / "docs" / "docker.md").read_text(encoding="utf-8")
+    assert "sudo docker compose" in src
+    assert "/root/.hermes" in src
+    assert "sudo -E docker compose" in src
+    assert "docker group" in src
+
+
+def test_onboarding_docs_cover_linux_host_gateway_for_container_localhost():
+    """REGRESSION (#3012): local-provider onboarding docs must include the
+    Linux Docker host-gateway shape, not only Docker Desktop's
+    `host.docker.internal` shortcut."""
+    src = (REPO / "docs" / "onboarding.md").read_text(encoding="utf-8")
+    assert "host.docker.internal" in src
+    assert "host-gateway" in src
+    assert "extra_hosts" in src
+    assert "api.local" in src
+    assert "localhost" in src and "container" in src