Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / web-dashboard

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

TriggerConsequenceGuard
The browser uses an expired local session token after a server restartProtected requests return unauthorized and the open tab cannot manage the serverHTML is not cached and the client performs one reload after a stale-token response
A gated session expires during a page requestThe browser remains in a protected SPA state instead of returning to loginRecognized authentication errors save the current location and perform a full-page login navigation
The browser opens a WebSocket without the mode-specific credentialChat or structured events do not connectUse the shared WebSocket URL builder with a fresh gated ticket or local token
A management request omits the selected profileReads or destructive writes can affect the wrong profile or be refused on a multi-profile hostRoute 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 ownerRename, export, review, or delete can target a different session storePass the profile carried by the listed row to its per-session request
A bulk delete includes a live sessionThe server skips that session while other selected rows are removedShow the server's skipped-active result and keep the live row in the list
A chat PTY is started on a non-POSIX hostThe embedded chat cannot start even though other dashboard pages can workThe server reports the PTY limitation and directs native Windows users to WSL2
A file action targets sensitive credential materialSecrets could be exposed through the browser file viewManaged-file reads and downloads deny sensitive names and credential directories
A plugin is installed but not activated or its backend path is unsafeIts browser feature is hidden or its server routes are not mountedActivation gates, path checks, source rules, and asset suffix allowlists run before use

Key files

FileWhy to read it
web/…/App.tsxDefines the dashboard shell, routes, navigation, profile remount boundary, and plugin integration points.
web/…/api.tsDefines the browser-to-server contract for HTTP, WebSocket auth, base paths, session handling, and profile scope.
web/…/AuthWidget.tsxShows how the shell presents gated identity state and logout without exposing a local loopback control.
web/…/auth-widget-visibility.tsDefines the distinction between local loopback identity and browser-gated identity.
web/…/ChatPage.tsxShows how the browser hosts and maintains the real TUI-backed chat workflow.
hermes_cli/…/chat_ws.pyShows the server-side PTY and structured chat WebSocket boundary.
hermes_cli/web_server.pyShows server assembly, session-token handling, router registration, and SPA mounting.
hermes_cli/web_server_dashboard.pyShows SPA serving, reverse-proxy path handling, themes, plugin discovery, and plugin backend mounting.
web/…/SessionsPage.tsxShows the overview, filtering, search, review, cleanup, bulk actions, and resume workflows.
web/…/ProfilesPage.tsxShows profile selection and profile lifecycle actions from the browser.
web/…/ConfigPage.tsxShows schema-driven and raw configuration editing.
web/…/FilesPage.tsxShows the managed file browsing and transfer workflow.
hermes_cli/…/sessions.pyShows the server contract for session listing and management.
hermes_cli/…/config_env.pyShows the server contract for configuration and environment management.
hermes_cli/…/files.pyShows the server boundary for safe managed-file access.
hermes_cli/…/profiles.pyShows the server boundary for profile lifecycle and profile-owned data.
web/…/registry.tsShows the browser plugin SDK and extension contract.