Skip to content

The agent that grows with you

fix(webapp): give a standalone profile its own Web Access port

unsupportedpastels975446bb88a4
diff --git a/hermes_cli/web_routers/webapp_access.py b/hermes_cli/web_routers/webapp_access.py
index 81eeeab643e..6fb1a18b179 100644
--- a/hermes_cli/web_routers/webapp_access.py
+++ b/hermes_cli/web_routers/webapp_access.py
@@ -120,12 +120,12 @@ async def webapp_access_status(profile: Optional[str] = None):
async def start_webapp_access(body: StartBody, profile: Optional[str] = None):
profile = destructive_profile(profile, "POST /api/webapp-access/start")
async with _one_change_at_a_time():
- gateway, (host, public_url, callback) = await _scoped(
+ gateway, (host, port, public_url, callback) = await _scoped(
profile, lambda gateway: (gateway, webapp_access.plan(body.mode, body.public_url)))
# The bundle before anything lasting: a failed build registers, writes and restarts nothing.
await _in_gateway_home(gateway, webapp_access.build_bundle)
await _in_gateway_home(gateway, lambda: webapp_access.register(callback))
- await _scoped(profile, lambda _gateway: webapp_access.serve(host, public_url), config_write=True)
+ await _scoped(profile, lambda _gateway: webapp_access.serve(host, public_url, port), config_write=True)
return await _restart(gateway, "turning on Web Access")
diff --git a/hermes_cli/webapp_access.py b/hermes_cli/webapp_access.py
index 733a6c69a0d..910a0d380aa 100644
--- a/hermes_cli/webapp_access.py
+++ b/hermes_cli/webapp_access.py
@@ -152,25 +152,101 @@ def _register_nous_sign_in(callback_url: str) -> None:
atomic_write_text(path, json.dumps(record) + "\n", mode=0o600)
-def plan(mode: str, public_url: Optional[str] = None) -> tuple[str, str, str]:
- """Check that *mode* can be served and signed in to; returns ``(host, public_url, callback)``:
- the bind host and the URL to pin for :func:`serve`, and the sign-in callback for
- :func:`register`. Changes nothing, so Start runs it before any slow or lasting step."""
- from gateway.webapp_listener import webapp_settings
-
+def plan(mode: str, public_url: Optional[str] = None) -> tuple[str, Optional[int], str, str]:
+ """Check that *mode* can be served and signed in to; returns ``(host, port, public_url, callback)``:
+ the bind host, the port to write (None to keep the config's, :func:`_port_to_serve`) and the URL to
+ pin for :func:`serve`, and the sign-in callback for :func:`register`. Changes nothing, so Start
+ runs it before any slow or lasting step."""
if mode == "lan":
address = lan_address()
if address is None:
raise WebappAccessError("This machine has no network address other devices can reach.")
- host, url, pinned = "0.0.0.0", f"http://{address}:{webapp_settings(gateway_home()).port}", ""
+ host, pinned = "0.0.0.0", ""
+ serving, port = _port_to_serve(gateway_home(), host)
+ url = f"http://{address}:{serving}"
elif mode == "public":
host, url = "127.0.0.1", _public_url(public_url)
pinned = url
+ port = _port_to_serve(gateway_home(), host)[1]
else:
raise WebappAccessError(f"Unknown access mode {mode!r}.")
if not nous_signed_in():
raise WebappAccessError("Sign in to your Nous account under Providers first.")
- return host, pinned, f"{url}/auth/callback"
+ return host, port, pinned, f"{url}/auth/callback"
+
+
+#: How many ports above the default Start tries for a standalone profile's Webapp.
+_PORT_SEARCH = 100
+
+
+def _port_to_serve(home: Path, host: str) -> tuple[int, Optional[int]]:
+ """``(port, port to write)`` for the Webapp of *home*'s gateway, bound on *host*.
+
+ A ``webapp.port`` in *home*'s config is the user's, and so is the default profile's gateway, which
+ serves the documented address (9120 unless set): both keep it, and Start writes no port. A standalone
+ profile's gateway with no ``webapp.port`` would find the default port taken by the default gateway's
+ Webapp, so it gets the first port above it that no other Hermes home on this machine claims and
+ nothing listens on now, and Start writes it to that profile's ``webapp.port``: the profile keeps that
+ address across restarts, and the gateway, the launcher and the sign-in callback all use it."""
+ from gateway.webapp_listener import DEFAULT_PORT, webapp_settings
+ from hermes_constants import named_profile_home
+
+ if _own_port(home) is not None or named_profile_home(home) is None:
+ return webapp_settings(home).port, None
+ claimed = _claimed_ports(home)
+ for port in range(DEFAULT_PORT + 1, DEFAULT_PORT + 1 + _PORT_SEARCH):
+ if port not in claimed and _port_free(host, port):
+ return port, port
+ raise WebappAccessError(f"No free port for the Webapp from {DEFAULT_PORT + 1} to {DEFAULT_PORT + _PORT_SEARCH}. "
+ f"Set webapp.port in {home / 'config.yaml'} to a free port, then start again.")
+
+
+def _own_port(home: Path) -> Optional[object]:
+ """The ``webapp.port`` *home*'s ``config.yaml`` sets, valid or not (the gateway reports an invalid
+ one by name), or None when it sets none. The file as written: the defaults name a port for everyone."""
+ from ruamel.yaml.error import YAMLError
+
+ from hermes_cli.config import read_user_config_raw
+
+ try:
+ document = read_user_config_raw(Path(home) / "config.yaml")
+ except (OSError, ValueError, YAMLError): # the gateway reports an unreadable config itself
+ return None
+ block = document.get("webapp") if isinstance(document, dict) else None
+ return block.get("port") if isinstance(block, dict) else None
+
+
+def _claimed_ports(home: Path) -> set[int]:
+ """The Webapp ports the other Hermes homes beside *home* claim: the default profile's (9120 unless
+ set) and every other profile's own ``webapp.port``, whether or not its gateway runs now. Only that
+ setting is read from their configs."""
+ from gateway.webapp_listener import DEFAULT_PORT
+ from hermes_constants import named_profile_home
+
+ profile = named_profile_home(home)
+ if profile is None:
+ return set()
+ root = profile.parent.parent
+ root_port = _own_port(root)
+ claimed = {root_port if isinstance(root_port, int) else DEFAULT_PORT}
+ for other in profile.parent.iterdir() if profile.parent.is_dir() else ():
+ port = _own_port(other) if other != profile and other.is_dir() else None
+ if isinstance(port, int) and not isinstance(port, bool):
+ claimed.add(port)
+ return claimed
+
+
+def _port_free(host: str, port: int) -> bool:
+ """Whether a listener could bind *host*:*port* now, as the gateway's does."""
+ family = socket.AF_INET6 if ":" in host else socket.AF_INET
+ with socket.socket(family, socket.SOCK_STREAM) as probe:
+ if os.name != "nt": # as the gateway's listener; on Windows the option would share a bound port
+ probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+ try:
+ probe.bind((host, port))
+ except OSError:
+ return False
+ return True
def build_bundle() -> None:
@@ -193,9 +269,10 @@ def register(callback_url: str) -> None:
_register_nous_sign_in(callback_url)
-def serve(host: str, public_url: str) -> None:
- """Serve the Webapp on *host* from the gateway's next start. Call :func:`register` first."""
- _write_config(enabled=True, host=host, public_url=public_url)
+def serve(host: str, public_url: str, port: Optional[int] = None) -> None:
+ """Serve the Webapp on *host* (and *port* when :func:`plan` chose one) from the gateway's next
+ start. Call :func:`register` first."""
+ _write_config(enabled=True, host=host, public_url=public_url, port=port)
def turn_off() -> None:
@@ -203,16 +280,16 @@ def turn_off() -> None:
_write_config(enabled=False)
-def _write_config(*, enabled: bool, host: str = "", public_url: str = "") -> None:
+def _write_config(*, enabled: bool, host: str = "", public_url: str = "", port: Optional[int] = None) -> None:
"""The ``webapp:`` block, and nothing outside it. Starting pins ``webapp.public_url`` for the
own-URL mode and drops it for LAN, where the callback follows each request; stopping changes
- only ``enabled``, so the next start offers the same address. ``webapp.port`` is the user's:
- a second gateway on this machine needs a port of its own."""
+ only ``enabled``, so the next start offers the same address. ``webapp.port`` is the user's; only a
+ standalone profile that has none gets the free one :func:`plan` chose, once."""
from hermes_cli.config import load_config, save_config
cfg = load_config()
webapp = cfg.get("webapp") if isinstance(cfg.get("webapp"), dict) else {}
- webapp.update(enabled=enabled, **({"host": host} if enabled else {}))
+ webapp.update(enabled=enabled, **({"host": host} if enabled else {}), **({"port": port} if port else {}))
if enabled and public_url:
webapp["public_url"] = public_url
elif enabled:
diff --git a/tests/hermes_cli/test_webapp_access_ports.py b/tests/hermes_cli/test_webapp_access_ports.py
new file mode 100644
index 00000000000..f01f7cdbac6
--- /dev/null
+++ b/tests/hermes_cli/test_webapp_access_ports.py
@@ -0,0 +1,130 @@
+"""Which port Web Access serves a gateway's Webapp on (``hermes_cli.webapp_access._port_to_serve``).
+
+The default profile's gateway serves the documented address, 9120 unless ``webapp.port`` says otherwise.
+A standalone profile has a gateway of its own; turning Web Access on there without a ``webapp.port`` used
+to bind 9120 too, which the default gateway's Webapp holds, so nothing was served. Start now gives such a
+profile the first port above 9120 that no other Hermes home claims and nothing listens on, and writes it to
+that profile's ``webapp.port``, so the gateway binds it, the launcher prints and opens it, the sign-in
+callback names it, and it stays the same across restarts. A ``webapp.port`` the user set always stays.
+No test binds a real port: what listens is faked, and the probe itself is checked on OS-chosen ports.
+"""
+import socket
+from pathlib import Path
+
+import pytest
+
+from hermes_cli import webapp_access
+
+
+def _write(path: Path, text: str) -> Path:
+ path.mkdir(parents=True, exist_ok=True)
+ (path / "config.yaml").write_text(text, encoding="utf-8")
+ return path
+
+
+def machine(monkeypatch, tmp_path):
+ """A Hermes root with a standalone profile ``solo`` and a sibling ``other`` that claims 9122; 9121 is
+ in use by something else. The process runs as ``solo`` (Web Access scopes to its gateway's home)."""
+ root = _write(tmp_path / ".hermes", "")
+ solo = _write(root / "profiles" / "solo", "gateway:\n standalone: true\n")
+ _write(root / "profiles" / "other", "gateway:\n standalone: true\nwebapp:\n port: 9122\n")
+ listening = {9121}
+ probed: list[tuple[str, int]] = []
+
+ def port_free(host, port):
+ probed.append((host, port))
+ return port not in listening
+
+ monkeypatch.setattr(webapp_access, "_port_free", port_free, raising=False)
+ monkeypatch.setattr(webapp_access, "nous_signed_in", lambda: True)
+ monkeypatch.setattr(webapp_access, "lan_address", lambda: "192.168.1.50")
+ monkeypatch.setenv("HERMES_HOME", str(solo))
+ return {"root": root, "solo": solo, "listening": listening, "probed": probed, "monkeypatch": monkeypatch}
+
+
+def _webapp_block(home: Path) -> dict:
+ from hermes_cli.config import read_user_config_raw
+
+ return read_user_config_raw(home / "config.yaml").get("webapp") or {}
+
+
+def test_a_standalone_profile_without_a_port_gets_a_free_one_that_every_surface_uses(machine):
+ from gateway.webapp_listener import dial_origin, listener_plan
+
+ assert webapp_access.gateway_home() == machine["solo"]
+ planned = webapp_access.plan("lan")
+ # 9120 is the default profile's, 9121 is in use, 9122 is the other profile's.
+ assert planned[-1] == "http://192.168.1.50:9123/auth/callback"
+ host, port, public_url, _callback = planned
+ assert (host, port, public_url) == ("0.0.0.0", 9123, "")
+ webapp_access.serve(host, public_url, port)
+ assert _webapp_block(machine["solo"]) == {"enabled": True, "host": "0.0.0.0", "port": 9123}
+ # The gateway binds that port, and the address the launcher prints and opens is built on it.
+ bind_host, bind_port, mount, _reason = listener_plan(machine["solo"])
+ assert (bind_host, bind_port) == ("0.0.0.0", 9123) and mount is not None
+ assert dial_origin(bind_host, bind_port) == "http://127.0.0.1:9123"
+ assert webapp_access.access_status()["port"] == 9123
+ assert _webapp_block(machine["root"]) == {}
+
+
+def test_the_chosen_port_stays_for_that_profile(machine):
+ host, port, public_url, _ = webapp_access.plan("lan")
+ webapp_access.serve(host, public_url, port)
+ webapp_access.turn_off()
+ machine["probed"].clear()
+ machine["listening"].add(9123) # its own gateway may hold it now
+ for mode, url, expected in (("lan", None, "http://192.168.1.50:9123/auth/callback"),
+ ("public", "https://solo.example.test", "https://solo.example.test/auth/callback")):
+ host, port, public_url, callback = webapp_access.plan(mode, url)
+ assert port is None # nothing to write: the config already has it
+ assert callback == expected
+ webapp_access.serve(host, public_url, port)
+ assert _webapp_block(machine["solo"])["port"] == 9123
+ assert machine["probed"] == []
+
+
+def test_the_own_url_mode_also_gets_a_free_port(machine):
+ host, port, _public_url, callback = webapp_access.plan("public", "https://solo.example.test")
+ assert (host, port, callback) == ("127.0.0.1", 9123, "https://solo.example.test/auth/callback")
+ assert machine["probed"][-1] == ("127.0.0.1", 9123)
+
+
+def test_the_default_profile_keeps_the_documented_port_and_writes_none(machine):
+ machine["monkeypatch"].setenv("HERMES_HOME", str(machine["root"]))
+ host, port, public_url, callback = webapp_access.plan("lan")
+ assert port is None and callback == "http://192.168.1.50:9120/auth/callback"
+ webapp_access.serve(host, public_url, port)
+ assert "port" not in _webapp_block(machine["root"])
+ assert machine["probed"] == []
+
+
[email protected]("configured", [9555, 9120, "not-a-port"])
+def test_a_port_the_user_set_is_never_replaced(machine, configured):
+ """Even one another gateway holds, or an invalid one: the gateway then says why by the setting's name."""
+ _write(machine["solo"], f"gateway:\n standalone: true\nwebapp:\n port: {configured}\n")
+ host, port, public_url, _callback = webapp_access.plan("lan")
+ assert port is None and machine["probed"] == []
+ webapp_access.serve(host, public_url, port)
+ assert _webapp_block(machine["solo"])["port"] == configured
+
+
+def test_with_no_free_port_start_refuses_and_names_the_setting(machine):
+ machine["listening"].update(range(9121, 9221))
+ with pytest.raises(webapp_access.WebappAccessError) as refused:
+ webapp_access.plan("lan")
+ assert "webapp.port" in str(refused.value) and str(machine["solo"] / "config.yaml") in str(refused.value)
+ assert "port" not in _webapp_block(machine["solo"])
+
+
+def test_the_probe_sees_a_port_a_listener_holds():
+ """On a port the OS picked, not a real service's."""
+ with socket.socket() as held:
+ held.bind(("127.0.0.1", 0))
+ held.listen()
+ port = held.getsockname()[1]
+ assert webapp_access._port_free("127.0.0.1", port) is False
+ with socket.socket() as probe:
+ probe.bind(("127.0.0.1", 0))
+ free = probe.getsockname()[1]
+ assert webapp_access._port_free("127.0.0.1", free) is True
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index 0b841f59c20..8c64bd991a1 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -3181,7 +3181,7 @@ webapp:
- `enabled` — the gateway reads it at start; restart the gateway after changing it (`hermes gateway restart`).
- `host` — `127.0.0.1`, `::1` or `localhost` keeps the Webapp on this machine. `0.0.0.0` or `::` makes it reachable from other machines and requires a [dashboard sign-in provider](./features/web-dashboard.md#authentication-gated-mode); without one the gateway serves native clients only and `hermes webapp --status` says why. Restart the gateway after adding the provider. Any other value, another loopback address such as `127.0.0.2` included, keeps the Webapp off.
-- `port` — when the port is taken, the gateway likewise serves native clients only and `hermes webapp --status` reports why. It also replaces the Webapp's browser sign-in, since another program may have received it, so open tabs need `hermes webapp` again once the port is free.
+- `port` — a standalone profile's gateway needs a port other than the default gateway's. **Settings → Web Access → Start** picks one for a standalone profile that sets none (the first free port above 9120 no other profile uses) and saves it here; it never replaces a port you set. When the port is taken, the gateway likewise serves native clients only and `hermes webapp --status` reports why. It also replaces the Webapp's browser sign-in, since another program may have received it, so open tabs need `hermes webapp` again once the port is free.
- `public_url` — set it when a reverse proxy or tunnel you run serves the Webapp at its own address (forwarding to `host:port`). It turns on dashboard sign-in even on a loopback `host`, it is the one outside hostname the Webapp accepts requests for, and sign-in callbacks are built on it. Without a sign-in provider the gateway serves native clients only, as for `0.0.0.0`. It must be an `http://` or `https://` address with no credentials, query or fragment; anything else keeps the Webapp off. `dashboard.public_url` is for `hermes dashboard` and never applies to the Webapp.
Sign-in turns on when `host` is `0.0.0.0` or `::`, or when `public_url` is set, whatever the host. `hermes webapp` then opens the Webapp's address (`public_url` when set, where sign-in returns) for you to sign in with your dashboard account: its one-use links only open a Webapp that needs no sign-in. Native clients (the CLI, TUI and Desktop app) never sign in: the gateway's listener for them never asks for it, whatever the config says.
diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md
index 30a1f243bcc..4172ae08534 100644
--- a/website/docs/user-guide/desktop.md
+++ b/website/docs/user-guide/desktop.md
@@ -115,8 +115,9 @@ your Nous account (Providers → Accounts). It appears only in the native app on
and only that app can change it: a browser signed in over the network cannot.
- **This network:** devices on the same Wi-Fi open `http://<this computer's address>:<port>`, where the
- port is `webapp.port` (9120 unless you set another). This is plain HTTP: the connection is not
- encrypted, so others on the network could read it. Use it only on a network you trust.
+ port is `webapp.port` (9120 unless you set another, or Start chose one for a standalone profile).
+ This is plain HTTP: the connection is not encrypted, so others on the network could read it. Use it
+ only on a network you trust.
- **My own URL:** an HTTPS address you already run (Tailscale Serve, a tunnel or a reverse proxy) that
forwards to `http://127.0.0.1:<port>`. It is saved as `webapp.public_url`. Never forward that port
from your router directly.
@@ -134,8 +135,10 @@ Web Access changes only the `webapp:` settings and keeps your `webapp.port`. It
Its Nous sign-in uses a sign-in client of its own, which the first Start registers with your Nous
account and keeps in the gateway's home (`webapp/sign-in-registration.json`). Start never reads or
writes `HERMES_DASHBOARD_OAUTH_CLIENT_ID` in `.env`, so turning Web Access on never changes the
-standalone dashboard's Nous sign-in. A standalone profile with its own gateway needs its own
-`webapp.port` to serve a Webapp beside the default gateway's. `hermes update` rebuilds the Webapp
+standalone dashboard's Nous sign-in. A standalone profile with its own gateway serves its Webapp on a
+port of its own: when its `webapp.port` is unset, the first Start picks the first free port above 9120
+that no other profile uses and saves it as that profile's `webapp.port`, so its address stays the same
+after restarts. A `webapp.port` you set is always kept. `hermes update` rebuilds the Webapp
whenever a profile has it turned on.
If that build fails, the gateway reports the Webapp unavailable, and the page says so, until
`hermes webapp` rebuilds it.