Hermes Web UI

The Hermes Web UI server is built using Python's ThreadingHTTPServer. Each HTTP request is handled in its own thread. The server uses a flat routing structure (if/elif chains) within do_GET and do_POST methods rather than a routing framework.

Key API Routes

GET Routes:

• /: Root
• /health: Health check
• /api/session: Session data
• /api/sessions: List of sessions
• /api/list: File listing
• /api/chat/stream: SSE streaming endpoint
• /api/file: File access
• /api/approval/pending: Check for pending tool approvals
• /api/session/worktree/status: Worktree status

POST Routes:

• /api/upload: File upload
• /api/session/new: Create a new session
• /api/session/update: Update session metadata
• /api/session/delete: Delete a session
• /api/chat/start: Initiate an agent chat session (returns stream_id)
• /api/chat: Synchronous chat fallback
• /api/approval/respond: Respond to a pending tool approval
• /api/session/worktree/remove: Remove a worktree

The Hermes Web UI documentation is organized into several functional categories to help you get started, customize the interface, deploy the system, or contribute to its design.

Getting Started

• Why Hermes: Understand the mental model and how it compares to tools like Claude Code, Cursor, or Codex.
• Onboarding: Follow the first-run wizard, set up providers, and configure local model server Base URLs.
• Troubleshooting: Use diagnostic flows for common failures, such as when an AIAgent is unavailable.

Customization & Extensions

• Themes: Learn about the theme and skin system and how to create custom themes.
• Workspace Git: Manage Git controls within your workspace.
• Extensions: Understand how administrators can inject WebUI extensions.

Deployment & Operations

• Remote Access: Configure SSH tunnels, Tailscale, or mobile access.
• Advanced Chat Setup: Implement dynamic recall-prefill and Gateway-backed browser chat for self-hosted environments.
• Docker: Use Docker Compose for setup and manage bind-mount migrations.
• Process Supervision: Set up the service using launchd, systemd, supervisord, runit, or s6.
• WSL2: Configure auto-start for Windows users via WSL2.
• Agent Onboarding: Review safety rules and checklists for assistant-led installation support.

Architecture & Design

• System Design: View all API endpoints and implementation notes in the ARCHITECTURE.md file.
• Design Principles: Explore design tokens, the 'calm-console' direction, and UI/UX principles.
• RFCs & Contracts: Review project contracts and Request for Comments (RFCs) for architectural proposals.

Conversations should follow a clear visual hierarchy to maintain a 'calm developer console' feeling. Avoid rendering every internal event as a first-class chat card.

Chat Turn Structure

1. User message: Right-aligned, compact bubble.
2. Assistant content: Left-aligned, prose-first (not a heavy bubble).
3. Traces (Tool, thinking, progress, context): Quiet disclosure rows inside or adjacent to the assistant turn.
4. Raw logs/Verbose details: Hidden until explicitly expanded.

Rendering Tool and Activity Traces

• Tool Cards: These are debug event rows, not chat messages. Show the icon, name, short target/preview, and status. Arguments, result snippets, and long logs must be placed behind an expansion affordance.
• Thinking/Context Cards: Use a quiet metadata visual style that does not overpower assistant prose.
• Activity Summaries: Should be terse (e.g., Activity: 4 tools). Do not list every tool name or add redundant badges.
• Automatic Compression: Render as a centered, non-interactive divider with quiet horizontal rules (e.g., Compressing context or Context auto-compressed). Do not use interactive elements like carets or status dots for this.

The multi-container (two- and three-container) setups provide process, network, and resource isolation, but they do not provide full filesystem or trust isolation.

What is isolated:

• Process & Lifecycle: Each service has its own PID namespace. A crash in the agent does not take down the WebUI.
• Network: The gateway API (port 8642) is bound only by the agent service. Other containers communicate via the hermes-net Docker network.
• Resources: You can apply independent resource limits (e.g., CPU/Memory) to the agent vs. the dashboard using deploy.resources.limits.
• Logs & Health: Restart policies and health checks are scoped per service.

What is NOT isolated:

• Filesystem: Both services share the hermes-home volume. The WebUI mounts the agent's source from hermes-agent-src as read-only.
• UID/GID: Both services default to ${UID:-1000} to ensure they can read/write shared volumes. Changing these to different values will cause permission errors.
• Trust: The WebUI runs code from the shared hermes-agent-src volume to install dependencies at startup.

Recommendation: If you require strict filesystem isolation (e.g., you do not trust the WebUI to access agent state), run the agent on a separate host and connect the WebUI via the gateway HTTP API.

The Hermes Web UI implements two distinct validation mechanisms for workspace paths to balance user intent with security. When working with the workspace API, you must distinguish between the registration phase and the operational phase:

1. Registration (validate_workspace_to_add): Used by the /api/workspaces/add endpoint. This is a permissive check. It allows users to register external paths (like WSL mounts) by only blocking paths that are non-existent, not a directory, or system root paths. This prevents circular dependencies where a path couldn't be added because it wasn't already in the trusted list.

2. Operation (resolve_trusted_workspace): Used for actual file read/write operations within an existing workspace. This is a strict check. To prevent path traversal and unauthorized access, the path must reside under the user's home directory, be present in the saved workspace list, or be under BOOT_DEFAULT_WORKSPACE.

// Note: These are internal logic patterns used by the workspace API
// validate_workspace_to_add(path) -> Permissive (for registration)
// resolve_trusted_workspace(path) -> Strict (for file I/O)