Internal Web Server & API
Relevant source files
The following files were used as context for generating this wiki page:
The Internal Web Server and API provide the administrative and integration layer for the Hermes Agent framework. This system hosts a web-based dashboard for configuration and an OpenAI-compatible proxy for third-party application integration. It centralizes control over agent memory, profiles, and external tool catalogs through a secured network interface.
This component serves as a multi-platform gateway, allowing the agent core to drive diverse surfaces including the web dashboard, messaging platform integrations, and external API requests. The server maintains persistent sessions and routes events between the agent and external webhooks.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:14-16, skills/autonomous-ai-agents/hermes-agent/SKILL.md:73-77
Web Dashboard (hermes dashboard)
The Dashboard acts as a full administration panel and embedded chat interface. It enables visual management of the agent's internal state without requiring CLI commands.
Key Functional Modules
- Profile Builder: Manages isolated agent configurations, including specific sessions, skills, and memory backends.
- MCP Catalog: Provides a registry for Model Context Protocol (MCP) servers, allowing users to add or remove system capabilities.
- Memory Manager: Inspects and edits the persistent memory stored in the canonical
state.db(SQLite + FTS5). - Webhook Routes: Configures event-driven runs and external triggers for the agent.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:19-21, skills/autonomous-ai-agents/hermes-agent/SKILL.md:75-76
Web Dashboard Flow
The following diagram illustrates how the Web Dashboard interacts with the core Agent systems.
The diagram shows the security layer (OAuth) protecting the management interfaces that interact with the SQLite state and Agent Core.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:46-56, skills/autonomous-ai-agents/hermes-agent/SKILL.md:75-76
OpenAI-Compatible Proxy (hermes proxy)
The proxy provides a local API endpoint that mimics the OpenAI API structure. This allows external tools like Aider, Cline, or custom scripts to use the Hermes Agent and its configured LLM providers without individual API keys for each tool.
Features
- Credential Rotation: Automatically rotates through credential pools and API keys configured in
auth.json. - OAuth Broker: Uses the provider signed into the Nous Portal to authorize external requests.
- Compatibility: Supports standard OpenAI client libraries by redirecting requests to the internal Hermes gateway.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:23-25, skills/autonomous-ai-agents/hermes-agent/SKILL.md:78
Proxy Communication Sequence
This sequence demonstrates an external application utilizing the Hermes Proxy to reach a configured LLM provider.
The sequence shows the Hermes Proxy acting as a broker that manages authentication and formatting between external apps and LLM providers.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:23-25, skills/autonomous-ai-agents/hermes-agent/SKILL.md:78
API Surface Summary
The server exposes different endpoints based on the requested surface.
| Surface | Command | Primary Purpose |
|---|---|---|
| Web Dashboard | hermes dashboard | Administrative control of profiles, memory, and webhooks. |
| Local Proxy | hermes proxy | Local OpenAI-compatible API for third-party tools. |
| Webhook Gateway | Internal | Listens for external events to trigger agent routines. |
| ACP Server | Internal | Integration for IDEs like VS Code and Zed. |
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:21-25, skills/autonomous-ai-agents/hermes-agent/SKILL.md:40-45
Security and Authentication
The internal web server implements strict security measures to protect the user's system and credentials.
- OAuth/Token Gate: The dashboard requires an OAuth login or a specific security token for access.
- Credential Isolation: Secrets remain in
~/.hermes/.envorauth.json. The web API never exposes raw API keys to the client-side dashboard. - Local Brokerage: The proxy acts as a local-only broker, ensuring that external applications do not need direct access to primary environment variables.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:50, skills/autonomous-ai-agents/hermes-agent/SKILL.md:75-76, skills/autonomous-ai-agents/hermes-agent/SKILL.md:121
Implementation Paths
The web server and API logic are distributed across the following directories:
hermes_cli/web_server.py: The main entry point that initializes the FastAPI/Web server.hermes_cli/web_routers/: Contains route definitions for models, chat, and administrative functions.~/.hermes/sessions/: Stores the gateway routing index and request dumps used by the API.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:52, hermes_cli/web_server.py, hermes_cli/web_routers/models.py