The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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.mdindex 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`, thatsession token is the browser-hosted Desktop's credential: the gateway keeps it in its home soWebapp 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 operaCross-subject local submissions carry a private, server-written profile/session/principalbinding for queued execution and recovery. It is not exposed in model requests or publicsession 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 compatibilitydiff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.mdindex 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 thatprofile.-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.mdindex 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.## Dashboarddiff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.mdindex 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 hostA 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 attachmentflow, with a **16 MiB** limit per file. Host files download through the browser's download manager, and