The Hermes Web UI Dashboard is a browser-based management interface designed to administer a local or remote Hermes Agent installation. It provides a graphical interface for managing configuration files, environment variables, API keys, sessions, cron jobs, skills, analytics, and interactive chat sessions. The backend is a FastAPI server embedded in the Hermes CLI (hermes_cli/web_server.py), serving a React SPA built with Vite and Tailwind CSS.
The dashboard follows a client-server pattern optimized for local or remote administration:
web/ offering views for configuring the agent, managing sessions, scheduled jobs (cron), and launching embedded terminal-based chat via a PTY web/src/App.tsx124-153web_dist, and mediates configuration operations on local files (e.g., config.yaml, .env) and SQLite databases hermes_cli/web_server.py4-10hermes --tui inside a POSIX PTY which the backend bridges over WebSocket to the browser terminal web/src/pages/ChatPage.tsx4-17Sources: hermes_cli/web_server.py4-10 web/src/lib/api.ts37-60 web/src/App.tsx124-153 web/src/pages/ChatPage.tsx4-17 web/src/pages/SessionsPage.tsx web/src/pages/CronPage.tsx web/src/pages/SkillsPage.tsx web/src/pages/ConfigPage.tsx web/src/pages/AnalyticsPage.tsx web/src/pages/EnvPage.tsx web/src/pages/ProfilesPage.tsx web/src/pages/ChannelsPage.tsx
hermes_cli/web_server.py)The hermes_cli/web_server.py module implements the FastAPI backend for the Web UI Dashboard. It serves the React frontend, handles API requests for configuration, sessions, cron jobs, skills, analytics, and API keys, and manages WebSocket connections for interactive features like the embedded terminal.
_lifespan that initializes async locks like app.state.event_lock and app.state.chat_argv_lock hermes_cli/web_server.py188-196_start_desktop_cron_ticker hermes_cli/web_server.py150-168 This ensures scheduled tasks execute even without a dedicated gateway process, using cron.scheduler_provider.resolve_cron_scheduler hermes_cli/web_server.py164-168__HERMES_SESSION_TOKEN__ is injected into index.html by the server and required in the X-Hermes-Session-Token header for all sensitive API calls web/src/lib/api.ts24-37fastapi and uvicorn, ensuring they are only required when the dashboard is actually invoked hermes_cli/web_server.py114-133The dashboard acts as a machine-level management surface. It uses a global profile switcher that appends ?profile=<name> to API requests for specific endpoint families like /api/config, /api/skills, and /api/mcp web/src/lib/api.ts52-92 The backend resolves this profile context to ensure operations target the correct HERMES_HOME and configuration files.
The web_server.py defines numerous API endpoints to manage various aspects of the Hermes Agent:
| Domain | Description | Client Reference |
|---|---|---|
| Status | Agent version, gateway PID, and platform states | api.getStatus() web/src/lib/api.ts67 |
| Configuration | CRUD for config.yaml and .env variables | api.getConfig(), api.setEnvVar() web/src/lib/api.ts72-73 |
| Sessions | SQLite-backed session browsing and search | api.getSessions() web/src/lib/api.ts83 |
| Cron | Scheduled job management and delivery | api.getCronJobs() apps/desktop/src/hermes.ts14-17 |
| Skills | Enable/disable skills and Hub management | api.getSkills() web/src/lib/api.ts70 |
| Analytics | Token usage and model-specific metrics | api.getAnalytics() web/src/lib/api.ts69 |
| Models | Selection, configuration, and MOA options | api.getModelInfo(), api.getModelOptions() web/src/lib/api.ts78-82 |
| Profiles | Management of agent profiles | api.getProfiles() apps/desktop/src/hermes.ts49 |
| Messaging | Platform configuration and onboarding | api.getMessagingPlatforms() web/src/lib/api.ts75 |
Sources: hermes_cli/web_server.py114-133 hermes_cli/web_server.py150-168 hermes_cli/web_server.py188-196 web/src/lib/api.ts24-37 web/src/lib/api.ts52-92 web/src/lib/api.ts67-83 apps/desktop/src/hermes.ts14-49
The frontend is a modern SPA using react-router-dom for navigation and lucide-react for iconography. Internationalization is supported via a structured translation system apps/desktop/src/i18n/types.ts1-8 with full support for English apps/desktop/src/i18n/en.ts Chinese apps/desktop/src/i18n/zh.ts and Japanese apps/desktop/src/i18n/ja.ts
web/src/App.tsx)The main entry point web/src/App.tsx defines the overall structure of the dashboard.
display: none when inactive to maintain the PTY state and WebSocket connection web/src/App.tsx124-132ProfileProvider to maintain the currently managed profile across the SPA web/src/App.tsx69-71web/src/pages/ChatPage.tsx)The Chat page provides a high-fidelity terminal experience for interacting with the Hermes Agent.
@xterm/xterm with the WebGL renderer web/src/pages/ChatPage.tsx19-24PTY_ATTACH_TOKEN_KEY to allow reattaching to the same PTY session across refreshes web/src/pages/ChatPage.tsx67-88clientWidth web/src/pages/ChatPage.tsx129-153apps/desktop/src/hermes.ts)To ensure reliability, especially during startup or over remote connections, the dashboard uses specific timeout configurations:
audioSpeak) and transcription apps/desktop/src/hermes.ts97-122Sources: web/src/App.tsx69-201 web/src/pages/ChatPage.tsx19-153 apps/desktop/src/hermes.ts81-122 apps/desktop/src/i18n/types.ts1-8
The connection between the browser and the agent process involves a pseudo-terminal (PTY) to correctly handle terminal control sequences and TUI rendering.
The pty_ws handler in the backend manages the lifecycle of these subprocesses, ensuring they are reaped when the WebSocket disconnects unless an attachment token is present hermes_cli/web_server.py188-196
Sources: web/src/pages/ChatPage.tsx4-17 hermes_cli/web_server.py188-196
| Page | Technical Role | Implementation File |
|---|---|---|
| Chat | xterm.js terminal host & PTY bridge | web/src/pages/ChatPage.tsx |
| Sessions | Conversation history & FTS search | web/src/pages/SessionsPage.tsx |
| Cron | Scheduled task management | web/src/pages/CronPage.tsx |
| Skills | Tool and Skill management | web/src/pages/SkillsPage.tsx |
| Config | YAML configuration editor | web/src/pages/ConfigPage.tsx |
| Analytics | Usage data visualization | web/src/pages/AnalyticsPage.tsx |
| Keys | Environment variable management | web/src/pages/EnvPage.tsx |
| Models | Model selection & MOA config | web/src/pages/ModelsPage.tsx |
| Profiles | Agent profile management | web/src/pages/ProfilesPage.tsx |
| Channels | Messaging platform config | web/src/pages/ChannelsPage.tsx |
Sources: web/src/App.tsx124-153 web/src/pages/ChatPage.tsx web/src/pages/SessionsPage.tsx web/src/pages/CronPage.tsx web/src/pages/SkillsPage.tsx web/src/pages/ConfigPage.tsx web/src/pages/AnalyticsPage.tsx web/src/pages/EnvPage.tsx web/src/pages/ProfilesPage.tsx web/src/pages/ChannelsPage.tsx
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.