Skip to content

The agent that grows with you

docs(webapp): document the gateway-served Webapp

emozilla7979fb2ce396
diff --git a/website/docs/developer-guide/gateway-local-sessions.md b/website/docs/developer-guide/gateway-local-sessions.md
index 8da45145e8e..4eece0ff17d 100644
--- a/website/docs/developer-guide/gateway-local-sessions.md
+++ b/website/docs/developer-guide/gateway-local-sessions.md
@@ -47,7 +47,10 @@ The server issues `session:operator` only at these existing trusted boundaries:
- Native interactive bootstrap ticket redemption (not worker-adoption tickets).
- The dashboard WebSocket upgrade gate, including authenticated dashboard login tickets,
the process-lifetime internal credential for server-spawned PTY clients, and the verified
- legacy session token when that authentication path is enabled.
+ 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`.
- The HTTP mutation gate, after a verified dashboard Session, native HTTP owner grant,
or permitted legacy session token has been accepted.
@@ -60,8 +63,9 @@ 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 expose the gateway listener remotely or implement
-OpenAI API-to-local session affinity; those remain separate integration paths.
+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.
## Deliberately limited compatibility
diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md
index ab9b8f31126..e1cad077620 100644
--- a/website/docs/reference/cli-commands.md
+++ b/website/docs/reference/cli-commands.md
@@ -106,6 +106,7 @@ The install also ships `hermes-agent`, a minimal runner that sends one query and
| `hermes import-agent` | Import an OpenClaw, Claude Code, Codex CLI or Cursor setup (from the [`agent-importers`](../user-guide/import-from-other-agents.md) plugin). |
| `hermes dashboard` | Launch the web dashboard for managing config, API keys, and sessions. |
| `hermes serve` | Start the Hermes backend server (headless; powers the desktop app and remote backends). |
+| `hermes webapp` | Open the Desktop workspace in a browser, served by the gateway. |
| `hermes desktop` (alias `gui`) | Build and launch the native Electron desktop app. |
| `hermes profile` | Manage profiles — multiple isolated Hermes instances. |
| `hermes completion` | Print shell completion scripts (bash/zsh/fish). |
@@ -1922,6 +1923,43 @@ hermes dashboard --port 8080 --no-open
worker dashboard
```
+## `hermes webapp`
+
+```bash
+hermes webapp [options]
+```
+
+Open the Hermes Desktop workspace in a normal browser. The gateway serves it on its own listener when
+`webapp.enabled` is `true` in the config ([Configuration → Webapp](../user-guide/configuration.md#webapp)).
+This command builds the Webapp bundle when it is out of date, starts the gateway if it is not running,
+and opens a one-use sign-in link. Chats run on that gateway, the same one the CLI, Desktop and messaging
+use. See [Desktop App → Use the Desktop workspace from a browser](../user-guide/desktop.md#use-the-desktop-workspace-from-a-browser).
+
+The link is valid for 60 seconds and works once; the browser exchanges it for the sign-in it keeps in
+that tab. Only your own OS user can get a link: the gateway answers this command over its private
+control socket. On macOS, where a one-use link cannot be checked against your OS user, the command
+prints the gateway's private link instead and never passes it to a browser launcher. That link signs a
+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.
+
+| Option | Description |
+|--------|-------------|
+| `--no-open` | Print the one-use link instead of opening a browser |
+| `--skip-build` | Use the existing `apps/desktop/dist-webapp` as is |
+| `--force-build` | Rebuild the bundle even when its build receipt is current |
+| `--build-only` | Build the bundle and stop |
+| `--status` | Show whether the running gateway serves the Webapp, and at which address |
+| `--sign-out` | Sign out every Webapp tab; each needs a new link from `hermes webapp` |
+
+```bash
+# Turn it on once, then open it
+hermes config set webapp.enabled true
+hermes gateway restart
+hermes webapp
+```
+
## `hermes profile`
```bash
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index c332bc857a5..7f4b8333594 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -3163,6 +3163,23 @@ onboarding:
- `seen` — internal state. Hermes latches each shown hint here so it never fires again; the first-message offer is also recorded here once shown. Don't hand-edit it — wipe the whole `onboarding` section if you want to re-see all hints.
- `run` — whether the desktop app opens its first-run onboarding chat on the next launch. Unset means only on a fresh install (no sessions and no profiles yet). Hermes writes `true` when onboarding starts and `false` when it is finished or skipped. It always lives in the default profile's `config.yaml`, whichever profile the app runs. Set `false` to never show it; managed installs can pin it in the managed config.
+## Webapp
+
+The gateway can serve the [Desktop workspace in a browser](./desktop.md#use-the-desktop-workspace-from-a-browser) on its own listener. It is off until you turn it on.
+
+```yaml
+webapp:
+ enabled: false # true: the gateway serves the Webapp
+ host: 127.0.0.1 # loopback address, or 0.0.0.0 / :: for other machines (dashboard sign-in required)
+ port: 9120 # fixed, so the browser's address stays the same across gateway restarts
+```
+
+- `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. 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.
+
+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
Configuration for the [web dashboard](./features/web-dashboard.md) — visual theme, public URL, and authentication providers. The auth providers (OAuth, basic password, drain) are documented in detail on the web-dashboard page; this is the `config.yaml` shape.
diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md
index 2021ee43feb..ed6afc648a7 100644
--- a/website/docs/user-guide/desktop.md
+++ b/website/docs/user-guide/desktop.md
@@ -32,6 +32,75 @@ hermes desktop
That uses your current config, keys, sessions, and skills.
+## Use the Desktop workspace from a browser
+
+The gateway can serve this workspace to a normal browser: sessions, profiles, Capabilities, Messaging,
+Artifacts, scheduled jobs, the host file tree, Git review, previews and the terminal rail. This is
+**not the Web Dashboard**. Turn it on once, then open it with `hermes webapp`:
+
+```bash
+hermes config set webapp.enabled true
+hermes gateway restart
+hermes webapp
+```
+
+The gateway then serves the Webapp at `http://127.0.0.1:9120` (see [Configuration → Webapp](./configuration.md#webapp)
+for the host and port). `hermes webapp` builds the bundle when it is out of date, starts the gateway if
+it is not running, and opens a one-use sign-in link. Chats run on that gateway, the same process that
+serves the CLI, the native Desktop and messaging, so every surface sees one conversation with one queue.
+
+**Signing in.** The link works once, within 60 seconds. The browser exchanges it for a sign-in that it
+keeps in that tab, so reloading keeps you signed in, and so does a gateway restart. A fresh tab or a
+bare URL shows instructions instead of access: run `hermes webapp` again for a new link. **New
+Window**, profile windows and session pop-outs hand the sign-in over with their own one-use link. On
+macOS the command prints the gateway's private link instead, for you to open; it signs a browser in as
+you until you sign out, so keep it private. `hermes webapp --sign-out` signs out every tab.
+
+For a named profile, `hermes -p work webapp` opens the Webapp on `work`. Profiles the default gateway
+serves share its Webapp; a standalone profile's own gateway serves its own when its config turns it on.
+
+**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). 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,
+use host files and Git, and reach that account's environment and credentials. Do not expose it without
+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.
+
+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
+supported audio and video play inline using the server's file-access rules. **Save Image** for
+cross-origin URLs needs CORS, with a **25 MiB** limit and a **30-second** deadline. Website links open
+in a separate tab; explicit URL previews use a sandboxed iframe that cannot open popups, so use **Open
+in browser** for sites that refuse embedding. Native-only features stay in Electron: global shortcuts,
+always-on-top overlays, OS-window inspection, external-terminal launch and the updater.
+
+Chats written before the gateway owned sessions show their history but cannot be continued from the
+browser until they are adopted: run `hermes sessions adopt` once on the host (`hermes -p <profile>
+sessions adopt` for another profile), or open them once in the native Desktop, TUI or CLI.
+
+### Terminal in the Webapp
+
+The terminal rail opens the host's interactive shell, running as a child of the gateway. Refreshing the
+page or losing the connection detaches the terminal without ending its shell; the saved terminal tab
+reattaches to that shell and its profile. Hiding a terminal is not closing it; closing its tab ends the
+shell. A second browser tab attaching to the same terminal takes over the connection.
+
+Detached shells are kept for **15 minutes** while the gateway runs, up to **16 host terminals**
+including detached ones. A gateway restart or update ends them. Reconnecting replays up to **1 MiB** of
+recent output; full-screen programs may need their own redraw command.
+
+The bundle's npm dependencies install into `.build/webapp-workspace` in the checkout, separately from
+the native Desktop, and reinstall only when the lockfile changes. With lazy installs disabled, a plain
+`hermes webapp` does not install them; `--build-only` or `--force-build` does.
+
## What's in the app
The desktop app is organized as a chat-first window with a left sidebar for navigation. It's built to allow managing multiple simultaneous agent conversations, configuring messaging providers, creating artifacts, browsing projects' folder structures, and working on multiple projects at once.