Skip to content

The agent that grows with you

docs(webapp): say what turns the Webapp's sign-in on and what the gateway does around it

emozillafbdf0b0f22e9
diff --git a/website/docs/developer-guide/gateway-local-sessions.md b/website/docs/developer-guide/gateway-local-sessions.md
index 4eece0ff17d..d3493a3227a 100644
--- a/website/docs/developer-guide/gateway-local-sessions.md
+++ b/website/docs/developer-guide/gateway-local-sessions.md
@@ -50,7 +50,8 @@ The server issues `session:operator` only at these existing trusted boundaries:
legacy session token when that authentication path is enabled. With `webapp.enabled`, that
session token is the browser-hosted Desktop's credential: the gateway keeps it in its home so
Webapp tabs survive a restart, hands it out only through a one-use link minted for a same-user
- control-socket peer, and replaces it on `hermes webapp --sign-out`.
+ control-socket peer, and replaces it on `hermes webapp --sign-out` and whenever the Webapp's
+ listener fails to start, since its port then belongs to someone else.
- The HTTP mutation gate, after a verified dashboard Session, native HTTP owner grant,
or permitted legacy session token has been accepted.
@@ -64,8 +65,11 @@ restriction rather than treating every accepted dashboard credential as an opera
Cross-subject local submissions carry a private, server-written profile/session/principal
binding for queued execution and recovery. It is not exposed in model requests or public
session snapshots. This change does not implement OpenAI API-to-local session affinity. The gateway
-listener stays on loopback unless `webapp.host` binds a wildcard address, which engages the
-dashboard sign-in gate.
+listener stays on loopback unless `webapp.host` binds a wildcard address. The Webapp's listener engages
+the dashboard sign-in gate on a wildcard bind or when `webapp.public_url` is set, on any bind, and
+one-use launch links are then off. `dashboard.public_url` never applies to the Webapp's listener; the
+gateway's private listener for native clients reads it as main does, so hosted sign-in on that
+listener keeps working.
## Deliberately limited compatibility
diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md
index 95b971e595f..ff0f4afd7b0 100644
--- a/website/docs/reference/cli-commands.md
+++ b/website/docs/reference/cli-commands.md
@@ -1944,10 +1944,11 @@ browser in as you until you run `hermes webapp --sign-out`; keep it private.
For a named profile served by the default gateway (`hermes -p work webapp`), the Webapp opens on that
profile.
-Behind the dashboard sign-in gate (`webapp.host: 0.0.0.0`), the command opens the Webapp's address
-instead of a one-use link, and you sign in there with your dashboard account. When the gateway cannot
-serve the Webapp, the command says why; the gateway reads its Webapp settings when it starts, so run
-`hermes gateway restart` after fixing the cause.
+Behind the dashboard sign-in gate (`webapp.host: 0.0.0.0` or `::`, or `webapp.public_url` set), the
+command opens the Webapp's address instead of a one-use link, and you sign in there with your dashboard
+account. When the gateway cannot serve the Webapp, the command says why; the gateway reads its Webapp
+settings when it starts, so run `hermes gateway restart` after fixing the cause. A Webapp bundle that
+is not built yet is the exception: this command builds it, and the running gateway serves it at once.
| Option | Description |
|--------|-------------|
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index 26ce992976f..6a160b322fb 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -3177,9 +3177,11 @@ webapp:
- `enabled` — the gateway reads it at start; restart the gateway after changing it (`hermes gateway restart`).
- `host` — a loopback address 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 keeps the Webapp off.
-- `port` — when the port is taken, the gateway likewise serves native clients only and `hermes webapp --status` reports why.
+- `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.
- `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 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.
+
The Webapp settings are read from the config of the gateway that serves the profile: the default profile's config for named profiles it serves, a standalone profile's own config otherwise.
## Dashboard
diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md
index d485615eac5..27f55993e92 100644
--- a/website/docs/user-guide/desktop.md
+++ b/website/docs/user-guide/desktop.md
@@ -62,10 +62,11 @@ serves share its Webapp; a standalone profile's own gateway serves its own when
**From another machine.** Set `webapp.host` to `0.0.0.0`; the gateway then requires the
[dashboard sign-in gate](./features/web-dashboard.md#authentication-gated-mode) (username and password
-for a trusted LAN or VPN, OAuth/OIDC for anything internet-facing). `hermes webapp` then opens the
-Webapp's address, where you sign in with your dashboard account; one-use links serve only a loopback
-Webapp. HTTPS is strongly recommended remotely and browsers require it for some microphone and
-clipboard features.
+for a trusted LAN or VPN, OAuth/OIDC for anything internet-facing). Behind a reverse proxy or tunnel
+you run, keep the loopback host and set `webapp.public_url` to the address it serves instead; that
+requires the same sign-in. `hermes webapp` then opens the Webapp's address, where you sign in with your
+dashboard account; one-use links serve only a Webapp that needs no sign-in. HTTPS is strongly
+recommended remotely and browsers require it for some microphone and clipboard features.
:::warning Treat Webapp access like access to Hermes on the host
A signed-in Webapp user can run arbitrary commands as the OS account running Hermes, run agent tools,
@@ -74,10 +75,12 @@ a sign-in provider. Prefer an SSH tunnel, Tailscale or another trusted VPN.
:::
`hermes webapp --status` shows whether the gateway serves the Webapp. When it cannot (the port is
-taken, or a wildcard host has no sign-in provider), the gateway still serves native clients and the
-status says why. The gateway reads these settings when it starts, so restart it after fixing the cause
-(`hermes gateway restart`). When the Webapp's bundle has not been built yet, the status says so instead:
-`hermes webapp` builds it, and the running gateway serves it without a restart.
+taken, or sign-in is required and no sign-in provider is set up), the gateway still serves native
+clients and the status says why. The gateway reads these settings when it starts, so restart it after
+fixing the cause (`hermes gateway restart`). When the port was taken, the gateway also replaces the
+Webapp's sign-in, so open tabs need `hermes webapp` again. When the Webapp's bundle has not been built
+yet, the status says so instead: `hermes webapp` builds it, and the running gateway serves it without a
+restart.
Browser-selected files are staged under the active profile before they enter the normal attachment
flow, with a **16 MiB** limit per file. Host files download through the browser's download manager, and