Hermes Agent Web Dashboard: Local Access, Profiles, and Diagnostics

The graphical Hermes Agent Web Dashboard provides browser-based administration for your agent installation, eliminating the need to edit configuration files directly. The dashboard lets you manage API access keys, switch active profiles, inspect past sessions, and launch an embedded terminal without modifying the system environment manually.

Basic Launch and System Dependencies

By default, the dashboard binds to the loopback interface:

hermes dashboard

This command starts a local HTTP server and opens http://127.0.0.1:9119 in your default browser. If that port is already in use by another local service, override it with the --port flag:

hermes dashboard --port 9120 --no-open

The --no-open flag prevents automatically opening a new browser tab, which is ideal for background processes and automation scripts.

The base hermes-agent package does not include the web stack by default. On Linux, macOS, and WSL2 environments, install the required optional components into the agent’s virtual environment:

cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"

The web extra installs FastAPI and Uvicorn, while pty adds ptyprocess for POSIX systems. Building the dashboard’s static frontend requires an active Node.js installation (when npm is present, the frontend builds automatically on first start).

Platform Boundaries: Native Windows vs. WSL2

According to the Windows (Native) guide, a native Windows installation supports the configuration, metrics, tasks, and session database views. However, the embedded /chat terminal tab depends on POSIX PTY pseudo-terminals. Because native Windows does not support this interface, you must run the agent inside WSL2 to access full interactive browser terminal sessions.

It is also essential to separate processes: the web dashboard and messaging gateways (such as those for Telegram, Discord, or other platforms) operate as independent daemons. Starting the web interface does not automatically launch or activate platform messaging gateways.

Profile Management and Model Configuration

The dashboard operates at the machine level, providing centralized administration across all configured profiles. Switching profiles in the sidebar updates the working context via the URL query parameter ?profile=<name>.

1. Config and API Keys Sections: The Config page edits parameters in config.yaml, where modifications are applied by clicking Save. In contrast, the API Keys page manages environment variables in ~/.hermes/.env: keys are set and removed individually per variable, without a global save button or batch validation across all fields.
2. Provider and Model Consistency: The selected model and credentials must strictly correspond to the same provider. When integrating a third-party OpenAI-compatible service, verify the upstream parameters: for example, connection settings, model IDs, and required fields are documented in the BetterToken guide. A third-party provider provides independent API model access only and does not host the Hermes dashboard or manage network tunnels.
3. Verifying Functionality via Sessions: For a manual health check, send a short, read-only prompt. Keep in mind that test queries may be billed by the provider. Successful inference is confirmed when you receive a substantive response in the interface and token consumption is recorded in session metadata or provider logs. The mere appearance of a new entry in the Sessions tab list indicates only that a session record was created, not that the model responded successfully.

Secure Remote Access

By default, the web server listens exclusively on 127.0.0.1. When binding to external interfaces (--host 0.0.0.0), an authentication gate is automatically enforced. If no authentication provider is configured, the agent terminates with an error (fail-closed). The legacy --insecure flag no longer bypasses authentication. Public or external network bindings require mandatory authentication according to the Hermes Agent documentation.

The recommended method for connecting to a remote server without exposing external ports is local port forwarding over an SSH tunnel (replace user@your-server with your remote server address and username):

ssh -N -L 9119:127.0.0.1:9119 user@your-server

If local port 9119 is already in use on your local workstation, use an alternative local port:

ssh -N -L 9120:127.0.0.1:9119 user@your-server

With this setup, the Hermes server on the remote host continues listening strictly on the local 127.0.0.1 loopback interface, all traffic is encrypted through the SSH tunnel, and you can access the dashboard from your workstation at http://127.0.0.1:9119 (or http://127.0.0.1:9120 if using the alternative local port).

Step-by-Step Troubleshooting

When errors occur, isolate the failing layer rather than testing the entire stack at once.

+----------------------------------------------------------------+
| 1. HTTP-транспорт      | 127.0.0.1:9119 /api/status            |
+------------------------+---------------------------------------+
| 2. Окружение и PTY     | Node.js / POSIX ptyprocess (WSL2)     |
+------------------------+---------------------------------------+
| 3. Сокеты и каналы     | /api/pty (Chat) / /api/ws (Desktop)   |
+------------------------+---------------------------------------+
| 4. Провайдер инференса | Ключи API, лимиты и сетевой эндпоинт  |
+----------------------------------------------------------------+

The diagnostic layers outlined in the decision tree above represent:

• Layer 1 (HTTP transport): 127.0.0.1:9119 /api/status
• Layer 2 (Environment and PTY): Node.js / POSIX ptyprocess (WSL2)
• Layer 3 (Sockets and channels): /api/pty (Chat) / /api/ws (Desktop)
• Layer 4 (Inference provider): API keys, quotas, and network endpoint

1. Network Layer (HTTP): A successful response from GET /api/status proves only that the Uvicorn process is running and answering HTTP requests. This unauthenticated endpoint does not guarantee that authorization has passed or that the interactive chat interface is ready.
2. PTY and Interface Layer: A Connection closed error can have several distinct causes. On native Windows, a primary diagnostic cause is the absence of POSIX PTY support (in which case execution should be moved into WSL2). On other platforms, this symptom is not limited to PTY and requires inspecting system logs and socket connections. Blank screen issues or CSS/style build errors require checking your Node.js version and rebuilding frontend dependencies.
3. Socket Channels and Authorization: The browser’s embedded terminal communicates via /api/pty, whereas the remote Desktop client connects over /api/ws. If the client reports that the backend is reachable but sessions do not respond, verify the corresponding socket connection: failures often stem from missing or expired session tickets, or DNS-rebinding protection blocking requests when the Host header does not match the bind address.
4. Model Provider Layer: Latency or error messages returned after submitting a prompt in an active terminal usually originate at the API layer (such as an invalid key in .env, an unreachable provider endpoint, or exceeded quotas and balances). However, provider errors do not prove that the dashboard server itself is completely healthy: diagnosing failures may still require checking the runtime state and session lifecycle.