The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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.mdindex 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 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 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 compatibilitydiff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.mdindex 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-openworker 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````bashdiff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.mdindex 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.+## DashboardConfiguration 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.mdindex 2021ee43feb..ed6afc648a7 100644--- a/website/docs/user-guide/desktop.md+++ b/website/docs/user-guide/desktop.md@@ -32,6 +32,75 @@ hermes desktopThat 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 appThe 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.