Web dashboard
The web dashboard is the browser control surface for Hermes Agent. It joins a single-page interface with the Hermes server so an engineer can chat, inspect and manage sessions, change profile and configuration state, work with files, and monitor the running system from one place. It is part of the broader user interface family; its browser chat complements the TUI gateway RPC path, while the desktop application uses the same server-facing capabilities without this browser shell.
Dashboard shell
The dashboard shell gives all browser workflows a common navigation and state context. It presents built-in pages through client-side routes and adds profile selection, status feedback, authentication controls, theme and language choices, and plugin extension points around those pages. The shell loads page areas only when needed so a user can open a management view without first loading chat-specific resources. References: web/…/App.tsx• L80-110, web/…/App.tsx• L141-179, web/…/App.tsx• L375-476
Browser workflows
The dashboard groups its user-facing work into a few related areas. Chat is the live agent surface. Sessions provides a history view with search, filters, review, rename, export, import, cleanup, and resume actions. Configuration and profile pages manage the agent's operating context. Files provides controlled access to the managed file area. The remaining pages expose system health, models, channels, scheduled work, skills, plugins, MCP servers, logs, analytics, pairing, webhooks, and documentation. References: web/…/App.tsx• L159-227, web/…/SessionsPage.tsx• L740-801, web/…/ProfilesPage.tsx• L257-315, web/…/FilesPage.tsx• L80-101, web/…/ConfigPage.tsx• L105-127
Profile scope
Profile scope is the dashboard's machine-level selection of the Hermes profile that management pages should read and change. The selected profile follows the user across profile-owned requests, while pages remount when the selection changes so old data does not remain visible beside new writes. Chat also binds a new terminal session to the selected profile, and session rows retain their owning profile for later actions. References: web/…/App.tsx• L839-851, web/…/api.ts• L63-159, web/…/ChatPage.tsx• L324-358, web/…/SessionsPage.tsx• L1202-1211
Authentication affordance
The authentication affordance shows the signed-in identity and provider only when the server uses gated browser login. In local loopback mode, or when the identity probe returns an unauthorized result, it stays hidden because there is no browser login session to end. In gated mode, logout ends the browser session and returns the user to the login page. References: web/…/AuthWidget.tsx• L45-153, web/…/auth-widget-visibility.ts• L1-5, web/…/api.ts• L414-443
Chat workflow
The chat workflow presents the real Hermes terminal user interface inside the browser rather than recreating the chat experience in page components. The browser supplies a terminal view and surrounding controls, while the server starts the same TUI and agent process used by hermes --tui; this keeps input, transcript behavior, and slash commands aligned across interfaces. References: web/…/ChatPage.tsx• L1-17, web/…/ChatPage.tsx• L495-544, hermes_cli/…/chat_ws.py• L538-615
PTY session
The browser opens /api/pty as a WebSocket and exchanges terminal data with a server-side pseudo-terminal (PTY). A PTY is a process-backed terminal channel that lets the browser send keystrokes and receive rendered terminal output. The server can resume a session, start a fresh session in a selected workspace, and keep a PTY alive across short browser disconnects so the visible chat remains one continuous agent interaction. References: web/…/ChatPage.tsx• L1061-1206, hermes_cli/…/chat_ws.py• L560-692
Chat sidecar
The chat sidecar is a second WebSocket used for structured events beside the terminal stream. It connects the browser to the same chat session through /api/ws, which lets the dashboard show supporting state without becoming a second transcript or composer. References: hermes_cli/…/chat_ws.py• L695-716, web/…/api.ts• L337-359
The browser and server coordinate chat startup and recovery as follows:
sequenceDiagram
participant Browser
participant Server as Dashboard server
participant PTY as Hermes TUI process
participant Agent as Agent runtime
Browser->>Server: Open /api/pty
Server->>PTY: Start or reattach terminal
PTY->>Agent: Run Hermes TUI and agent
Browser<<->>Server: Keystrokes and terminal output
Browser->>Server: Open /api/ws
Server<<->>Agent: Structured chat events
Server-->>Browser: Chat state and rendered output
Server integration
The server integration is the contract between the browser application and the FastAPI dashboard server. JSON routes carry page data and mutations. WebSockets carry terminal, structured chat, and live event traffic. The browser uses one shared client layer so authentication, URL prefixes, profile scope, and error handling apply consistently across these channels. References: web/…/api.ts• L15-31, web/…/api.ts• L161-255, hermes_cli/web_server.py• L1031-1070
HTTP data contract
The browser client maps broad product actions to server route families instead of treating each page as an isolated data source. Read routes supply status, sessions, profiles, files, configuration, model and provider choices, and plugin metadata. Write routes apply changes such as session cleanup, profile edits, configuration saves, file transfers, gateway actions, and plugin changes. The same client adds the selected management profile to profile-owned requests and supports both structured responses and binary file transfers. References: web/…/api.ts• L90-159, web/…/api.ts• L414-559, web/…/api.ts• L601-681, web/…/api.ts• L1057-1154
Authentication modes
The dashboard supports a local session-token mode and a gated browser-login mode. In local mode the server places a short-lived session token in the page and the client sends it with protected API requests. In gated mode the browser uses its authenticated session cookie for HTTP and obtains a single-use ticket before each WebSocket connection. The shared client also redirects a gated session to login when the server reports session expiry, while a stale local token causes one controlled page reload. References: hermes_cli/web_server.py• L379-497, web/…/api.ts• L161-297, web/…/AuthWidget.tsx• L50-74
Deployment paths
hermes dashboard starts the browser-facing server and serves the built single-page application. The server can also place the dashboard under a reverse-proxy path prefix by rewriting the page bootstrap and asset references. hermes serve uses the same server-facing capabilities for desktop and remote clients but stays headless and does not expose the browser application. References: hermes_cli/…/dashboard.py• L1-7, hermes_cli/…/dashboard.py• L76-101, hermes_cli/web_server_dashboard.py• L103-140, hermes_cli/web_server_dashboard.py• L150-243
Profile management
The profile workflow lets an operator create, select, describe, rename, configure, and remove independent Hermes operating contexts. Profile selection changes where profile-owned sessions, configuration, model choices, skills, and other settings are managed, while the dashboard keeps machine-wide profile discovery separate from the selected profile's data. References: web/…/ProfilesPage.tsx• L397-515, web/…/api.ts• L747-841, hermes_cli/…/profiles.py• L78-143
Session management
Session management turns the agent's stored conversations into an operator-facing history and recovery view. It combines an overview of recent activity and gateway platforms with a paged session list that supports category and source filters, search, review, and recovery actions. References: web/…/SessionsPage.tsx• L740-801, web/…/SessionsPage.tsx• L1490-1501, web/…/SessionsPage.tsx• L1763-1873, hermes_cli/…/sessions.py• L175-220
Session lifecycle
The session lifecycle links stored history to live agent work. A user can discover recent or automation sessions, open a readable message view, resume a chosen session in chat, rename it, export or import its record, select several rows for deletion, remove empty sessions, prune old archived sessions, and remove an individual session. The page polls for new sessions created by another Hermes process so the browser view catches up without a manual reload, and each row keeps its owning profile for later actions. References: web/…/SessionsPage.tsx• L390-686, web/…/SessionsPage.tsx• L997-1091, web/…/SessionsPage.tsx• L1202-1473, web/…/api.ts• L444-552
Configuration and file workflows
Configuration and file workflows give the browser controlled ways to change Hermes settings and manage user-owned working data. They are separate surfaces because configuration changes affect agent behavior, while file actions operate on a managed path with explicit read and write rules. References: web/…/ConfigPage.tsx• L165-204, web/…/FilesPage.tsx• L103-126, hermes_cli/…/config_env.py• L80-157, hermes_cli/…/files.py• L151-178
Configuration editing
The configuration page presents the server's schema as grouped fields and also offers a raw YAML view. Form edits preserve settings outside the visible schema, while reset, import, export, and save actions help an operator change a focused part of the configuration without treating the whole file as disposable. References: web/…/ConfigPage.tsx• L249-368, web/…/ConfigPage.tsx• L434-550, hermes_cli/…/config_env.py• L117-157
Managed files
The file workflow presents a bounded directory view with navigation, upload, download, folder creation, and deletion. The server filters sensitive credential material and applies path and file-type checks before returning data, so the browser acts as a controlled file manager rather than a general file system browser. References: web/…/FilesPage.tsx• L154-263, web/…/FilesPage.tsx• L328-465, hermes_cli/…/files.py• L63-107, hermes_cli/…/files.py• L162-178
Dashboard extensions
Dashboard extensions let installed plugins add browser features without changing the core shell. A plugin can contribute a tab, replace a built-in route, fill named layout slots, serve browser assets, and expose protected server routes when its activation and trust rules allow it. References: web/…/App.tsx• L259-370, hermes_cli/web_server_dashboard.py• L517-589, hermes_cli/web_server_dashboard.py• L858-943
Plugin contract
The plugin contract gives browser extensions the shared API client, authentication-aware fetch and WebSocket helpers, common UI components, and slot registration. The server discovers plugin metadata and the browser turns that metadata into navigation and routes, so a plugin can participate in the dashboard's product model instead of running as an unrelated page. References: web/…/registry.ts• L63-106, web/…/registry.ts• L112-191, hermes_cli/…/dashboard_ui.py• L131-180
Themes and fonts
Themes and fonts provide a user-level presentation layer shared by the dashboard shell and terminal view. Built-in choices live with the browser, user themes arrive as normalized definitions from the server, and the active choice is persisted so the same visual settings apply after a reload. References: web/…/context.tsx• L411-471, web/…/context.tsx• L473-568, hermes_cli/…/dashboard_ui.py• L51-106
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the browser route list, navigation entries, lazy page loading, and plugin route overrides aligned when adding or renaming a page.
- Keep
fetchJSON, binary requests, and WebSocket URL creation on the same authentication and base-path rules. - Keep gated cookie auth, local session-token auth, identity visibility, logout navigation, and WebSocket ticket creation aligned across the shell and shared client.
- Keep profile-scoped API families aligned with the server routes that read or write profile data. A missing scope can silently target the dashboard process's profile.
- Keep per-row session actions tied to the profile stamped on the row, and keep bulk actions clear about active sessions that the server refuses to delete.
- Keep the PTY chat contract aligned with the embedded TUI. Changes to resume, workspace, attach, or resize behavior affect browser continuity.
- Keep dashboard plugin metadata, asset serving, backend activation, and SDK contract changes compatible across the server and browser.
- Keep configuration schema responses and the form/YAML editors aligned so a page save does not discard settings outside the visible form.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The browser uses an expired local session token after a server restart | Protected requests return unauthorized and the open tab cannot manage the server | HTML is not cached and the client performs one reload after a stale-token response |
| A gated session expires during a page request | The browser remains in a protected SPA state instead of returning to login | Recognized authentication errors save the current location and perform a full-page login navigation |
| The browser opens a WebSocket without the mode-specific credential | Chat or structured events do not connect | Use the shared WebSocket URL builder with a fresh gated ticket or local token |
| A management request omits the selected profile | Reads or destructive writes can affect the wrong profile or be refused on a multi-profile host | Route profile-scoped calls through the shared profile scope and remount pages on selection changes |
| A session row action uses the global profile instead of the row's owner | Rename, export, review, or delete can target a different session store | Pass the profile carried by the listed row to its per-session request |
| A bulk delete includes a live session | The server skips that session while other selected rows are removed | Show the server's skipped-active result and keep the live row in the list |
| A chat PTY is started on a non-POSIX host | The embedded chat cannot start even though other dashboard pages can work | The server reports the PTY limitation and directs native Windows users to WSL2 |
| A file action targets sensitive credential material | Secrets could be exposed through the browser file view | Managed-file reads and downloads deny sensitive names and credential directories |
| A plugin is installed but not activated or its backend path is unsafe | Its browser feature is hidden or its server routes are not mounted | Activation gates, path checks, source rules, and asset suffix allowlists run before use |
Key files
| File | Why to read it |
|---|---|
| web/…/App.tsx | Defines the dashboard shell, routes, navigation, profile remount boundary, and plugin integration points. |
| web/…/api.ts | Defines the browser-to-server contract for HTTP, WebSocket auth, base paths, session handling, and profile scope. |
| web/…/AuthWidget.tsx | Shows how the shell presents gated identity state and logout without exposing a local loopback control. |
| web/…/auth-widget-visibility.ts | Defines the distinction between local loopback identity and browser-gated identity. |
| web/…/ChatPage.tsx | Shows how the browser hosts and maintains the real TUI-backed chat workflow. |
| hermes_cli/…/chat_ws.py | Shows the server-side PTY and structured chat WebSocket boundary. |
| hermes_cli/web_server.py | Shows server assembly, session-token handling, router registration, and SPA mounting. |
| hermes_cli/web_server_dashboard.py | Shows SPA serving, reverse-proxy path handling, themes, plugin discovery, and plugin backend mounting. |
| web/…/SessionsPage.tsx | Shows the overview, filtering, search, review, cleanup, bulk actions, and resume workflows. |
| web/…/ProfilesPage.tsx | Shows profile selection and profile lifecycle actions from the browser. |
| web/…/ConfigPage.tsx | Shows schema-driven and raw configuration editing. |
| web/…/FilesPage.tsx | Shows the managed file browsing and transfer workflow. |
| hermes_cli/…/sessions.py | Shows the server contract for session listing and management. |
| hermes_cli/…/config_env.py | Shows the server contract for configuration and environment management. |
| hermes_cli/…/files.py | Shows the server boundary for safe managed-file access. |
| hermes_cli/…/profiles.py | Shows the server boundary for profile lifecycle and profile-owned data. |
| web/…/registry.ts | Shows the browser plugin SDK and extension contract. |