Skip to content

The agent that grows with you

fix(docker): hermes webapp reuses the baked bundle, and local Desktop files stay out of the image

IAvecilla11a75355a4c5
diff --git a/.dockerignore b/.dockerignore
index b090120f136..22375f8450f 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -90,6 +90,19 @@ apps/desktop/dist/
apps/desktop/dist-webapp/
apps/desktop/build/
apps/desktop/release/
+# The negations above override the global dependency and secret rules.
+apps/**/node_modules
+apps/desktop/**/.env
+apps/desktop/**/.env.*
+apps/desktop/**/.vite
+apps/desktop/**/.cache
+apps/desktop/**/coverage
+apps/desktop/**/playwright-report
+apps/desktop/**/test-results
+apps/desktop/**/*.p12
+apps/desktop/**/*.pfx
+apps/desktop/**/*.pem
+apps/desktop/**/*.key
# Test suite — not shipped in production images
tests/
diff --git a/hermes_cli/webapp.py b/hermes_cli/webapp.py
index 9318b701714..b431d51ef71 100644
--- a/hermes_cli/webapp.py
+++ b/hermes_cli/webapp.py
@@ -103,6 +103,11 @@ def prepare_webapp_renderer(
)
print(f"→ Reusing Hermes Webapp renderer at {dist} (--skip-build)")
return dist
+ # A current, unmarked bundle needs no lock either, so a read-only install
+ # (the Docker image) reuses the one baked at build time.
+ if not force and not webapp_bundle_stale(dist) and source_product_current(project_root, "webapp", dist):
+ print(f"✓ Hermes Webapp renderer is up to date: {dist}")
+ return dist
with _exclusive_build_lock(project_root / _LOCK_NAME):
if not force and source_product_current(project_root, "webapp", dist):
_clear_stale_mark(dist)
diff --git a/scripts/ci/classify_changes.py b/scripts/ci/classify_changes.py
index a36ba7b3230..818746bcc9f 100644
--- a/scripts/ci/classify_changes.py
+++ b/scripts/ci/classify_changes.py
@@ -523,7 +523,11 @@ _E2E_LANE_EXCLUDES = {
"e2e": ("tests/e2e/core/upgrade/", "tests/e2e/core/windows_update/"),
"e2e_desktop_core": ("apps/desktop/e2e/update/",),
}
-_DOCKER_PATHS = (*_DOCKER_META, *_DEP_MANIFESTS, *_NPM_MANIFESTS, "pm/", "tests/docker/")
+# The image builds the Webapp (webapp_build stage), so its manifests and build
+# recipe route here; Desktop sources stay out, as web/ and ui-tui/ do.
+_DOCKER_PATHS = (*_DOCKER_META, *_DEP_MANIFESTS, *_NPM_MANIFESTS, "pm/", "tests/docker/",
+ "apps/desktop/package.json", "apps/desktop/scripts/build-webapp.mjs",
+ "apps/shared/package.json", "scripts/build/")
_NIX_LANE_PATHS = (*_NIX_PATHS, *_NIX_FILES, *_DEP_MANIFESTS, *_NPM_MANIFESTS)
# A pull request with this label runs every slow lane, whatever it touches.
diff --git a/tests/ci/test_classify_changes.py b/tests/ci/test_classify_changes.py
index 27d7e38a79e..86bcca95139 100644
--- a/tests/ci/test_classify_changes.py
+++ b/tests/ci/test_classify_changes.py
@@ -92,7 +92,12 @@ CASES = {
# through the same compilers (tests/ci/test_update_ci_routing.py).
"shared JS builder → frontend + both update suites": (
["scripts/build/web.mjs"],
- _lanes(python=True, frontend=True, e2e_upgrade=True, e2e_desktop_update=True),
+ _lanes(python=True, frontend=True, e2e_upgrade=True, e2e_desktop_update=True, docker=True),
+ ),
+ # The image builds the Webapp through this recipe; Desktop sources do not route to docker.
+ "webapp build recipe → docker": (
+ ["apps/desktop/scripts/build-webapp.mjs"],
+ _lanes(frontend=True, e2e_upgrade=True, e2e_desktop_core=True, e2e_desktop_update=True, docker=True),
),
"root JS tests → frontend": (["tests-js/product-builders.test.mjs"], _lanes(python=True, frontend=True)),
"docs-only → nothing heavy": (["README.md", "docs/guide.md"], _lanes()),
diff --git a/tests/docker/test_webapp_bundle.py b/tests/docker/test_webapp_bundle.py
index 0c8e4e5a0e1..85498c53d60 100644
--- a/tests/docker/test_webapp_bundle.py
+++ b/tests/docker/test_webapp_bundle.py
@@ -1,26 +1,21 @@
-"""The image ships the Webapp renderer where the gateway serves it from.
+"""The image ships a current Webapp renderer that the unprivileged user can use.
The install root is read-only, so ``hermes webapp`` cannot build the bundle at
-runtime: a gateway with ``webapp.enabled`` serves only what the build baked.
+runtime: a gateway with ``webapp.enabled`` serves only what the build baked, and
+the CLI must reuse it without taking the build lock under ``/opt/hermes``.
"""
from __future__ import annotations
-import shlex
import subprocess
-def test_webapp_bundle_is_baked_where_the_gateway_serves_it(built_image: str) -> None:
- py = (
- "from hermes_cli.config import get_project_root; "
- "from hermes_cli.webapp import webapp_bundle_stale, webapp_dist_dir; "
- "dist = webapp_dist_dir(get_project_root()); "
- "assert (dist / 'index.html').is_file(), dist; "
- "assert not webapp_bundle_stale(dist), dist"
- )
- inner = f"source /opt/hermes/.venv/bin/activate && cd /opt/hermes && python3 -c {shlex.quote(py)}"
+def test_webapp_build_only_reuses_the_baked_bundle(built_image: str) -> None:
+ inner = "source /opt/hermes/.venv/bin/activate && cd /opt/data && hermes webapp --build-only"
r = subprocess.run(
["docker", "run", "--rm", "--network=none", "--entrypoint", "su", built_image,
"hermes", "-s", "/bin/bash", "-c", inner],
capture_output=True, text=True, timeout=120, check=False,
)
- assert r.returncode == 0, f"Webapp bundle missing from the image:\n{r.stderr[-2000:]}"
+ out = r.stdout + r.stderr
+ assert r.returncode == 0, f"hermes webapp --build-only failed in the image:\n{out[-2000:]}"
+ assert "up to date" in out, out[-2000:]
diff --git a/tests/hermes_cli/test_webapp_renderer_build.py b/tests/hermes_cli/test_webapp_renderer_build.py
index cf2f6e08246..7de07df65ac 100644
--- a/tests/hermes_cli/test_webapp_renderer_build.py
+++ b/tests/hermes_cli/test_webapp_renderer_build.py
@@ -60,6 +60,22 @@ def test_skip_build_writes_nothing_into_the_install_tree(tmp_path: Path):
assert sorted(tmp_path.rglob("*")) == install_tree
+def test_a_current_bundle_is_reused_without_writing_the_install_tree(tmp_path: Path, monkeypatch):
+ """The Docker image bakes a current bundle under a root-owned install, so reusing it must not
+ open the build lock there."""
+ from hermes_cli import source_build
+
+ _workspace_tree(tmp_path)
+ dist = webapp.webapp_dist_dir(tmp_path)
+ dist.mkdir()
+ (dist / "index.html").write_text("<!doctype html>", encoding="utf-8")
+ monkeypatch.setattr(source_build, "source_product_current", lambda *_a: True)
+
+ install_tree = sorted(tmp_path.rglob("*"))
+ assert webapp.prepare_webapp_renderer(tmp_path) == dist
+ assert sorted(tmp_path.rglob("*")) == install_tree
+
+
def _assert_build_lock_excludes_second_open(tmp_path: Path):
from pm.filesystem import lock_fd, unlock_fd
diff --git a/website/docs/user-guide/docker.md b/website/docs/user-guide/docker.md
index 5517c3ff95c..04b04008f85 100644
--- a/website/docs/user-guide/docker.md
+++ b/website/docs/user-guide/docker.md
@@ -179,6 +179,33 @@ An unauthenticated public dashboard was the entry point for the June 2026 MCP-co
Running the dashboard as a separate container **is** supported when that container shares the host PID and network namespace (e.g. `network_mode: host`, as the repo's own `docker-compose.yml` does — see its `dashboard` service). Its gateway-liveness detection requires a shared PID namespace with the gateway process, so the limitation only applies to dashboards run in isolated bridge-network containers without a shared PID namespace.
+## Running the Webapp
+
+The image ships the [Webapp](./desktop.md) (Hermes Desktop in a browser) prebuilt; the gateway serves it on its own port when the mounted `config.yaml` turns it on (see [Configuration → Webapp](./configuration.md#webapp)):
+
+```yaml
+webapp:
+ enabled: true
+ host: 0.0.0.0
+ port: 9120
+ public_url: "http://localhost:9120" # the address your browser opens
+```
+
+Publish the port and configure a sign-in provider, as for the dashboard:
+
+```sh
+docker run -d \
+ --name hermes \
+ --restart unless-stopped \
+ -v ~/.hermes:/opt/data \
+ -p 9120:9120 \
+ -e HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin \
+ -e HERMES_DASHBOARD_BASIC_AUTH_PASSWORD="$(openssl rand -hex 16)" \
+ nousresearch/hermes-agent gateway run
+```
+
+A non-loopback `host` needs one of the [dashboard's auth providers](#running-the-dashboard), and the listener refuses to start without one. Without `public_url`, links printed by `hermes webapp` inside the container use the container's own address, not the published one.
+
## Running interactively (CLI chat)
To open an interactive chat session against a running data directory: