hermes-webui Documentation

Technical Documentation: nesquena/hermes-webui

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Hermes Web UI

Hermes Agent is a sophisticated autonomous agent that lives on your server, accessed via a terminal or messaging apps, that remembers what it learns and gets more capable the longer it runs.

Hermes WebUI is a lightweight, dark-themed web app interface in your browser for Hermes Agent.
Full parity with the CLI experience - everything you can do from a terminal, you can do from this UI. No build step, no framework, no bundler. Just Python and vanilla JS.

Layout: three-panel. Left sidebar for sessions and navigation, center for chat,
right for workspace file browsing. Model, profile, and workspace controls live in
the composer footer — always visible while composing. A circular context ring
shows token usage at a glance. All settings and session tools are in the
Hermes Control Center (launcher at the sidebar bottom).

Setup Hermes so you can access it natively on every device:

This gives you nearly 1:1 parity with Hermes CLI from a convenient web UI which you can access securely through an SSH tunnel from your Hermes setup. Single command to start this up, and a single command to SSH tunnel for access on your computer. Every single part of the web UI uses your existing Hermes agent and existing models, without requiring any additional setup.

Contents Copy Chapter

• Why Hermes — what it is and how it compares
• Quick start — clone + bootstrap.py / start.sh / ctl.sh
• Features — chat, sessions, workspace, voice, profiles, security, themes, panels, mobile
• Configuration & access — auto-discovery, overrides, remote/Tailscale/phone, manual launch
• Nix flake/module — declarative install and service
• Docker — single- and multi-container deploys
• Running tests
• Architecture — backend/frontend layout, state dir
• Docs — the full documentation index
• Contributors

Why Hermes Copy Chapter

Most AI tools reset every session. They don't know who you are, what you worked on, or what
conventions your project follows. You re-explain yourself every time.

Hermes retains context across sessions, runs scheduled jobs while you're offline, and gets
smarter about your environment the longer it runs. It uses your existing Hermes agent setup,
your existing models, and requires no additional configuration to start.

What makes it different from other agentic tools:

• Persistent memory — user profile, agent notes, and a skills system that saves reusable
  procedures; Hermes learns your environment and does not have to relearn it
• Self-hosted scheduling — cron jobs that fire while you're offline and deliver results to
  Telegram, Discord, Slack, Signal, email, and more
• 10+ messaging platforms — the same agent available in the terminal is reachable from your phone
• Self-improving skills — Hermes writes and saves its own skills automatically from experience;
  no marketplace to browse, no plugins to install
• Provider-agnostic — OpenAI, Anthropic, Google, DeepSeek, OpenRouter, and more
• Orchestrates other agents — can spawn Claude Code or Codex for heavy coding tasks and bring
  the results back into its own memory
• Self-hosted — your conversations, your memory, your hardware

vs. the field (landscape is actively shifting — see docs/why-hermes.md for the full breakdown):

† Claude Code has CLAUDE.md / MEMORY.md project context and rolling auto-memory, but not full automatic cross-session recall
‡ Claude Code has cloud-managed scheduling (Anthropic infrastructure) and session-scoped /loop; no self-hosted cron

The closest competitor is OpenClaw — both are always-on, self-hosted, open-source agents
with memory, cron, and messaging. The key differences: Hermes writes and saves its own skills
automatically as a core behavior (OpenClaw's skill system centers on a community marketplace);
Hermes is more stable across updates (OpenClaw has documented release regressions and ClawHub
has had security incidents involving malicious skills); and Hermes runs natively in the Python
ecosystem. See docs/why-hermes.md for the full side-by-side.

Quick start Copy Chapter

Run the repo bootstrap:

git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
python3 bootstrap.py

Or keep using the shell launcher:

./start.sh

For self-hosted VM or homelab installs, ctl.sh wraps the common daemon lifecycle commands without requiring fuser or pkill:

./ctl.sh start              # background daemon, PID at ~/.hermes/webui.pid
./ctl.sh status             # PID, uptime, bound host/port, log path, /health
./ctl.sh logs --lines 100   # tail ~/.hermes/webui.log
./ctl.sh restart
./ctl.sh stop

ctl.sh start runs the bootstrap in foreground/no-browser mode behind the daemon wrapper, writes logs to ~/.hermes/webui.log, and respects .env plus inline overrides such as HERMES_WEBUI_HOST=0.0.0.0 ./ctl.sh start.

Stopping the server. Each launch method has its own stop path because only ctl.sh start writes a PID file (~/.hermes/webui.pid):

Launch method	How to stop
python3 bootstrap.py	Ctrl-C in the terminal (runs in the foreground)
./ctl.sh start	./ctl.sh stop (sends SIGTERM, waits, then SIGKILL)
Detached bootstrap.py (no --foreground) or ./start.sh	Find the PID via lsof -i :8787 (or ss -tlnp) and kill it

./ctl.sh stop cannot stop a server launched by bootstrap.py or start.sh directly — it only manages processes it started itself.

How chat runs by default. WebUI runs the Hermes agent in-process, reading
your HERMES_HOME config directly. It does not connect to an external
Hermes/agent OpenAI-compatible API server to run chat. HERMES_API_URL is only
read by the Tasks/cron health probe and does not route chat.

Two options if you run an external endpoint:

1. Use its models as a chat provider (supported today): add it in
   Settings → Providers as a custom OpenAI-compatible provider with
   base_url = http://127.0.0.1:8642/v1 and your bearer token.
2. Route chat through a Hermes Gateway API server (supported today via
   HERMES_WEBUI_CHAT_BACKEND=gateway): see docs/advanced-chat-setup.md.
   Full agent-loop delegation is not yet shipped; tracked in #1925.

Advanced: dynamic recall prefill & Gateway-backed chat Copy Section

Two optional, self-hosted-deployment features — attaching dynamic session-recall prefill to browser turns (Joplin/Obsidian/Notion/llm-wiki routers), and routing browser chat through a running Hermes Gateway — are documented in docs/advanced-chat-setup.md. Most users need neither.

The bootstrap will:

1. Detect Hermes Agent and, if missing, attempt the official installer (curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash).
2. Find or create a Python environment with the WebUI dependencies.
3. Start the web server and wait for /health.
4. Open the browser unless you pass --no-browser.
5. Drop you into a first-run onboarding wizard inside the WebUI.

Native Windows is not supported for this bootstrap yet. Use Linux, macOS, or WSL2.
For Windows / WSL auto-start at login, see docs/wsl-autostart.md.

A community-maintained native Windows setup is documented at @markwang2658/hermes-windows-native-guide (companion setup repo: @markwang2658/hermes-windows-native). Notes from the community report in #1952:

• Memory: community-measured ~330 MB native vs ~1080 MB with WSL2+Docker (varies by configuration).
• What works: chat, workspace browser, session management, all themes.
• Known limitations: some POSIX-style file paths surface in the workspace browser; bash-assuming agent tools may not work natively.
• Native Windows setup: install Python 3.11+, then from the hermes-agent root in PowerShell: python -m venv venv → pip install -r requirements.txt → pwsh .\start.ps1 (it auto-discovers venv\Scripts\python.exe).
• WSL2 relationship: not a prerequisite — a WSL2-built venv (venv/bin/python, ELF) isn't invokable by native Windows Python, so use the native setup above. WSL2 stays useful as a parallel install if you want the full bootstrap.py + Linux runtime.

If provider setup is still incomplete after install, the onboarding wizard will point you to finish it with hermes model instead of trying to replicate the full CLI setup in-browser.
For a step-by-step walkthrough of the wizard, provider choices, local model server Base URLs, and safe re-runs, see docs/onboarding.md.
If an AI assistant is helping with install, reinstall, bootstrap, provider setup, or first-run support, have it read docs/onboarding-agent-checklist.md before running commands or inspecting logs.

Features Copy Chapter

Chat and agent Copy Section

• Streaming responses via SSE (tokens appear as they are generated)
• Multi-provider model support -- any Hermes API provider (OpenAI, Anthropic, Google, DeepSeek, Nous Portal, OpenRouter, MiniMax, Xiaomi MiMo, Z.AI); dynamic model dropdown populated from configured keys
• Send a message while one is processing -- it queues automatically
• Edit any past user message inline and regenerate from that point
• Retry the last assistant response with one click
• Cancel a running task directly from the composer footer (Stop button next to Send)
• Tool call cards inline -- each shows the tool name, args, and result snippet; expand/collapse all toggle for multi-tool turns
• Subagent delegation cards -- child agent activity shown with distinct icon and indented border
• Detached child results are delivered to the parent as internal wakeups. Their raw prompts and completion toasts do not appear as messages from the user; the parent can summarize the results in its own reply. Ordinary background-process wakeups remain visible. A completed parent reply does not, by itself, cancel or suppress outstanding children; a later result may still start a follow-up turn.
• Mermaid diagram rendering inline (flowcharts, sequence diagrams, gantt charts)
• Thinking/reasoning display -- collapsible gold-themed cards for Claude extended thinking and o3 reasoning blocks
• Approval card for dangerous shell commands (allow once / session / always / deny)
• SSE auto-reconnect on network blips (SSH tunnel resilience)
• File attachments persist across page reloads and are stored outside the active workspace by default (~/.hermes/webui/attachments/<session_id>/, or HERMES_WEBUI_ATTACHMENT_DIR/<session_id>/ when configured)
• Message timestamps (HH:MM next to each message, full date on hover)
• Code block copy button with "Copied!" feedback
• Syntax highlighting via Prism.js (Python, JS, bash, JSON, SQL, and more)
• Safe HTML rendering in AI responses (bold, italic, code converted to markdown)
• Bare HTTP(S) URLs are auto-linked without absorbing adjacent CJK prose; Unicode IDN host separators and raw-CJK IRI paths remain linkable
• rAF-throttled token streaming for smoother rendering during long responses
• Context usage indicator in composer footer -- token count, cost, and fill bar (model-aware)

Sessions Copy Section

• Create, rename, duplicate, delete, search by title and message content
• Session actions via ⋯ dropdown per session — pin, move to project, archive, duplicate, delete
• Pin/star sessions to the top of the sidebar (gold indicator)
• Pinned-conversation limits apply separately to each session's owning profile; root/default aliases share a limit. Unpin an empty session before switching its profile through chat or /goal.
• Archive sessions (hide without deleting, toggle to show)
• Session projects -- named groups with colors for organizing sessions; delegated subagent sessions have no project of their own and follow their nearest ancestor's project in the project filter and the Unassigned chip; forks and other child sessions keep their own project, so a fork moved to "No project" stays Unassigned
• Project bindings -- right-click a project chip and pick Project settings… to pin a default workspace (or several workspaces, with one marked default) and a model. The chip's + (and New Chat while the project filter is active) then opens a session already in that workspace/model. The reasoning-effort binding stays in the API (POST /api/projects/bind) but is dormant: the dialog no longer offers the row, and nothing applies a stored value to a new session any more — the only mechanism would be the profile-wide reasoning-effort preference (the same agent.reasoning_effort setting the /reasoning command writes), so a row inside a per-project dialog read as per-project while silently moving the whole profile's effort; it comes back with per-session effort (#7881)
• Session tags -- add #tag to titles for colored chips and click-to-filter
• Grouped by Today / Yesterday / Earlier in the sidebar (collapsible date groups)
• Download as Markdown transcript, full JSON export, or import from JSON
• Create a public read-only share link for the active conversation from the Control Center; shared pages show a sanitized transcript snapshot without workspace, profile, or live controls
• Sessions persist across page reloads and SSH tunnel reconnects
• Browser tab title reflects the active session name
• CLI session bridge -- CLI sessions from hermes-agent's SQLite store appear in the sidebar with a gold "cli" badge; click to import with full history and reply normally
• Token/cost display -- input tokens, output tokens, estimated cost shown per conversation (toggle in Settings or /usage command)

Workspace file browser Copy Section

• Directory tree with expand/collapse (single-click toggles, double-click navigates)
• Breadcrumb navigation with clickable path segments
• Preview text, code, Markdown (rendered), and images inline
• Chat links using workspace://path/to/file open files in the right-side preview pane
• Edit, create, delete, and rename files; create folders
• Binary file download (auto-detected from server)
• File preview auto-closes on directory navigation (with unsaved-edit guard)
• Dismissing the workspace panel is respected: resizing the viewport or showing the
  on-screen keyboard no longer force-reopens the panel after you close it (#6710)
• Previews report their real load outcome -- a broken source is reported as a
  failure instead of a silent success -- and a response that never settles is
  released by a bounded wait so the panel still opens; the source keeps loading
  and a late failure is surfaced in the status line (#6710)
• Git detection -- branch name and dirty file count badge in workspace header
• Right panel is drag-resizable
• Syntax highlighted code preview (Prism.js)

Voice input Copy Section

• Microphone button in the composer (Web Speech API)
• Tap to record, tap again or send to stop
• Live interim transcription appears in the textarea
• Auto-stops after ~2s of silence
• Appends to existing textarea content (doesn't replace)
• Hidden when browser doesn't support Web Speech API (Chrome, Edge, Safari)

Profiles Copy Section

• Profile chip in the composer footer -- dropdown showing all profiles with gateway status and model info
• Gateway status dots (green = running), model info, skill count per profile
• Profiles management panel -- create, switch, and delete profiles from the sidebar
• Clone config from active profile on create
• Optional custom endpoint fields on create -- Base URL and API key written into the profile's config.yaml at creation time, so Ollama, LMStudio, and other local endpoints can be configured without editing files manually
• Seamless switching -- no server restart; reloads config, skills, memory, cron, models
• Per-session profile tracking (records which profile was active at creation)

Authentication and security Copy Section

• Optional password auth -- off by default, zero friction for localhost
• Enable via HERMES_WEBUI_PASSWORD env var or Settings panel
• Installed PWAs work best with WebUI's own password. Reverse proxies are supported, but proxy basic auth can block the service-worker update fetches an installed app needs and leave it on a blank screen after an update; see docs/troubleshooting.md for recovery steps.
• Optional passkeys/WebAuthn -- register from Settings -> System after signing in with a password; the login page only shows passkey sign-in after at least one passkey exists
• After registering at least one passkey, Settings -> System can remove the password and keep passkey-only sign-in enabled. Password auth remains the bootstrap/recovery path until you choose to go passwordless; passkeys are same-origin and stored locally in the WebUI state directory
• Optional native OIDC login for WebUI sessions -- configure webui_oidc.issuer, client_id, allow_claim, and allow_values in config.yaml, or set the matching HERMES_WEBUI_OIDC_* environment variables. OIDC stays disabled until all four are present, and startup prints a warning if the config is partial.
• Native OIDC stores the PKCE/state nonce flow in process memory. That works for the shipped single-process server, and it also works behind a load balancer when callbacks stay sticky to the same WebUI instance. Multi-instance deployments need session affinity, or the callback can land on a different process and fail state validation.
• Signed HMAC HTTP-only cookie with 24h TTL
• Minimal dark-themed login page at /login
• Security headers on all responses (X-Content-Type-Options, X-Frame-Options, Referrer-Policy)
• 20MB POST body size limit
• CDN resources pinned with SRI integrity hashes

Themes Copy Section

• Appearance is split into two axes: Theme (system, dark, light) and Skin
  (default, ares, mono, slate, poseidon, sisyphus, charizard,
  sienna, catppuccin, nous, geist-contrast / Geist Contrast)
• Switch via Settings -> Appearance (instant live preview) or /theme
• Persists across reloads (server-side in settings.json + localStorage for flicker-free loading)
• Skins use data-skin plus CSS variables; dark mode resolves through the
  .dark class, not a data-theme custom-theme axis — see THEMES.md

Settings and configuration Copy Section

• Hermes Control Center (sidebar launcher button) -- Conversation tab (export/import/clear), Preferences tab (model, send key, theme, language, all toggles), System tab (version, password)
• Send key: Enter (default) or Ctrl/Cmd+Enter
• Send-key on touch devices: plain Enter inserts a newline on phones (iPhone/iPod, Android phones) and on tablets / iPadOS / touch-capable Macs that only expose a coarse pointer (no attached hardware keyboard), matching the software keyboard's return key. Devices that report a fine pointer (for example, a tablet with a hardware keyboard) keep the configured physical-keyboard send-key behavior. The configured shortcut and the Send button remain available for sending.
• Show/hide CLI sessions toggle (enabled by default)
• Token usage display toggle (off by default, also via /usage command)
• Task list in chat toggle (off by default) -- a collapsible task strip pinned at the top of the chat area, summarising the current session's todos. While it is on, the sidebar Todos panel is hidden and the workspace-panel Todos toggle is disabled with an explanation, so the same list is never shown twice; switch it back off in Settings -> Appearance to restore the sidebar panel and re-enable the workspace toggle.
• Control Center always opens on the Conversation tab; resets on close
• Unsaved changes guard -- discard/save prompt when closing with unpersisted changes
• Cron completion alerts -- toast notifications and unread badges scoped to the active profile on the Tasks tab and session sidebar
• Background agent error alerts -- banner when a non-active session encounters an error
• Approval and clarification browser alerts notify once per pending owner when its session is not actively viewed. Local approval dismissal hides attention without resolving the prompt; resolution, replacement, and cancellation retire that owner's alert state. Denied or failed notification delivery can retry while the prompt remains pending.

Slash commands Copy Section

• Type / in the composer for autocomplete dropdown
• Plain skills match case-insensitive keywords in their name or description; built-in, agent/plugin, and bundle commands keep prefix matching and take precedence over a same-slug skill
• Built-in: /help, /clear, /compress [focus topic], /compact (alias), /model <name>, /workspace <name>, /new, /usage, /theme
• Arrow keys navigate, Tab/Enter select, Escape closes
• Unrecognized commands pass through to the agent

Model aliases in `/model`

/model <alias> accepts any alias configured for the profile, in either of Hermes's two formats:

model_aliases:                     # canonical
  sol:
    model: gpt-5.6-sol
    provider: openai-codex

model:
  provider: openrouter
  aliases:                         # legacy
    sol: openai-codex/gpt-5.6-sol  # provider-qualified
    fast: gpt-4                    # unqualified

Alias resolution follows the format of the alias:

• A canonical model_aliases entry and a provider-qualified legacy target name their own
  route. The target is authoritative, so /model sol selects that provider even when a
  same-named model exists on another provider. A canonical entry also takes precedence over a
  legacy entry with the same name.
• An unqualified legacy target names only a model, so it keeps the ordinary lookup: the
  active provider first, then the normal fuzzy match. This is the behavior /model had before,
  and it is unchanged.

Aliases that carry their own endpoint or credentials are resolved server-side; the browser only
receives the model, the provider id, and an opaque route id, never a base URL or key.
On the in-process backend, an alias with its own base_url follows Hermes's direct-alias
credential rules: its declared api_key/key_env wins; otherwise only a credential resolved
for that endpoint's own host is sent (for example an OpenRouter key to openrouter.ai), never
the provider label's key to an unrelated host. The alias's provider still selects its wire protocol.

Gateway and runner chat support provider-only aliases by sending the resolved target model
and provider, not the alias name: their runtime does not share WebUI's alias registry. Aliases
that explicitly declare base_url, api_key, or key_env need the in-process backend. External
chat starts, wakeups, Gateway regeneration, and Gateway goal kickoffs reject them with HTTP 400 and
reason: model_alias_requires_in_process_backend before dispatch; a new Gateway goal is not
set. Runner regeneration remains unsupported (HTTP 409), regardless of alias selection.
Ambient credentials resolved for a provider-only alias do not count as alias overrides.
The session retains its target model and profile-bound opaque route id, including Gateway
success/error writeback, so a later backend switch can still resolve the original alias.

A session stores that opaque route id, not the endpoint, so an alias that is later deleted or renamed
leaves the session pointing at a route nothing owns. That send fails closed — on every backend, the
in-process worker, the gateway and the runner alike — with a controlled "model alias unavailable"
error instead of quietly falling back to another provider; pick the model again to store a live route.

With HERMES_WEBUI_RUNTIME_ADAPTER=runner-local, /goal <text> returns HTTP 501
(status: unsupported) without changing an existing goal or starting a run. The
runner contract does not yet provide atomic goal replacement and kickoff; WebUI
never substitutes local goal execution. /goal status, pause, resume, and
clear delegate to the runner when supported. Legacy-direct and legacy-journal
goal kickoff behavior is unchanged for supported routes. Normal runner chat supports provider-only model aliases.

Server-initiated turns retain the pre-session stale-Agent-runtime barrier. It
runs before loading the session; named-profile alias and Gateway routing happen
only after admission. A stale default local runtime can therefore reject a wakeup
before the session's named-profile Gateway ownership is known.

Panels Copy Section

• Chat -- session list, search, pin, archive, projects, new conversation
• Tasks -- view, create, edit, run, pause/resume, delete cron jobs; run history; completion alerts
• Skills -- list all skills by category, search, preview, create/edit/delete; linked files viewer
• Memory -- view and edit MEMORY.md and USER.md inline
• Profiles -- create, switch, delete agent profiles; clone config
• Todos -- live task list from the current session; hidden while the in-chat task list toggle is on, which also disables the workspace-panel Todos tab
• Insights -- token, cost, and skill-usage analytics; period presets (7/30/90/365 days) plus a Custom range with start/end date pickers
• Spaces -- add, rename, remove workspaces; quick-switch from topbar

Mobile responsive Copy Section

• Hamburger sidebar -- slide-in overlay on mobile (<640px)
• Sidebar top tabs stay available on mobile; no fixed bottom nav stealing chat height
• Files slide-over panel from right edge
• Touch targets minimum 44px on all interactive elements
• Full-height chat/composer on phones without bottom-nav spacing
• Desktop layout completely unchanged

Configuration & access Copy Chapter

start.sh auto-detects almost everything; the subsections below cover the knobs for when it can't, and how to reach the UI remotely.

What start.sh discovers automatically Copy Section

Before it installs the agent or writes any state, the bootstrap binds the resolved host and port as a preflight. If another service already holds the port, it stops right there, names the address it could not bind, and prints a free alternative to pass to ./start.sh or set as HERMES_WEBUI_PORT in .env. The running service and your existing configuration are left untouched. When the listener on that port is a healthy WebUI -- the instance you already started -- bootstrap reports it ready and leaves it alone, browser included; only a foreign service gets the conflict message.

If discovery finds everything, nothing else is required.

Overrides (only needed if auto-detection misses) Copy Section

export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent
export HERMES_WEBUI_PYTHON=/path/to/python
export HERMES_WEBUI_PORT=9000
export HERMES_WEBUI_AUTO_INSTALL=1  # enable auto-install of agent deps (disabled by default)
./start.sh

Auto-install requires the selected Agent to match HERMES_WEBUI_AGENT_DIR or the Agent under HERMES_HOME, and still checks ownership and permissions.

Or inline:

HERMES_WEBUI_AGENT_DIR=/custom/path ./start.sh 9000

Full list of environment variables:

Extension deployments can inspect sanitized, authenticated diagnostics at GET /api/extensions/status; see WebUI Extensions.

Nix flake and NixOS module Copy Section

Hermes WebUI has a Nix flake package and a NixOS service module so you can run it declaratively.

Install the latest package with:

nix shell github:nesquena/hermes-webui#default

Use this flake input in your system configuration:

inputs.hermes-webui.url = "github:nesquena/hermes-webui";

Then add the module and configure it in nixosModules:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    hermes-agent.url = "github:NousResearch/hermes-agent";
    hermes-webui.url = "github:nesquena/hermes-webui";
  };

  outputs = { self, nixpkgs, hermes-agent, hermes-webui, ... }: {
    nixosConfigurations.<host> = nixpkgs.lib.nixosSystem {
      modules = [
        hermes-agent.nixosModules.default
        hermes-webui.nixosModules.default
        ({ pkgs, ... }: {
          services.hermes-agent.enable = true;
          services.hermes-webui = {
            enable = true;
            host = "127.0.0.1";
            port = 8787;
            stateDir = "/var/lib/hermes-webui";
            user = "hermes";
            group = "hermes";
            hermesHome = "/var/lib/hermes/.hermes";
            agent.package = hermes-agent.packages.${pkgs.stdenv.hostPlatform.system}.default;
            environmentFiles = [ "/run/secrets/hermes-webui.env" ];
          };
        })
      ];
    };
  };
}

The module defaults to 127.0.0.1. Set host = "0.0.0.0" and openFirewall = true only when you want direct network access, and pair that with auth, for example HERMES_WEBUI_PASSWORD via environmentFiles.

The published Hermes Agent package exposes passthru.hermesVenv, so the module derives HERMES_WEBUI_PYTHON from its interpreter. Bootstrap then locates the installed run_agent.py through that interpreter without importing Agent code and exports its parent as HERMES_WEBUI_AGENT_DIR. Packages may expose passthru.hermesAgentDir as a direct path instead. Use agent.dir and agent.python as explicit overrides for custom package layouts.

When WebUI reads shared Hermes Agent state, run the service as a user that can already read that state. For a co-located Hermes Agent service, set user and group to the agent service account; the module only creates the default hermes-webui account and never changes ownership of an existing hermesHome.

The module maps directly onto existing WebUI environment variables, including:
HERMES_WEBUI_HOST, HERMES_WEBUI_PORT, HERMES_WEBUI_STATE_DIR, HERMES_HOME, HERMES_WEBUI_AGENT_DIR, and HERMES_WEBUI_PYTHON.

Set environmentFiles for secrets like API keys. Protected WebUI runtime keys from the module are rejected there, so keep host, port, state, and agent wiring in the module options. Keep reverse proxy and TLS configuration in your surrounding deployment module because those details are deployment-specific.

Remote access (SSH tunnel, Tailscale, phone) Copy Section

The server binds to 127.0.0.1 by default. To reach it from another machine,
use an SSH tunnel (ssh -N -L 8787:127.0.0.1:8787 user@host, which start.sh
prints for you over SSH) or, on a single-operator or access-restricted tailnet,
use the preferred Tailscale Serve
flow, which keeps WebUI on loopback behind tailnet-only HTTPS. Direct access to
http://<server-tailscale-ip>:8787 with HERMES_WEBUI_HOST=0.0.0.0 and
HERMES_WEBUI_PASSWORD is a fallback when Serve is unavailable. Full setup and
the community ARM64-Android field report: docs/remote-access.md.

Manual launch (without start.sh) Copy Section

If you prefer to launch the server directly:

cd /path/to/hermes-agent          # or wherever sys.path can find Hermes modules
HERMES_WEBUI_PORT=8787 venv/bin/python /path/to/hermes-webui/server.py

Note: use the agent venv Python (or any Python environment that has the Hermes agent dependencies installed). System Python will be missing openai, httpx, and other required packages.

Health check:

curl http://127.0.0.1:8787/health

Docker Copy Chapter

Pre-built images (amd64 + arm64) are published to GHCR on every release.

For a comprehensive setup guide covering all 3 compose files, common failure modes, and bind-mount migration, see docs/docker.md. The README covers the 5-minute happy path.

5-minute quickstart (single container) Copy Section

The simplest setup: one WebUI container that runs the agent in-process.

git clone https://github.com/nesquena/hermes-webui
cd hermes-webui
cp .env.docker.example .env
# Edit .env if your host UID isn't 1000 (e.g. macOS where UIDs start at 501)
docker compose up -d
# Open http://localhost:8787

Run Compose as the user who owns your Hermes home. sudo docker compose up -d can make ${HOME} expand to the root user's home, so Docker mounts the wrong .hermes directory instead of your real ~/.hermes and the WebUI starts with config.yaml (not found, using defaults). Prefer adding your user to the Docker group and running docker compose up -d; if you must use sudo, set absolute paths first, for example HERMES_HOME=/home/you/.hermes HERMES_WORKSPACE=/home/you/workspace sudo -E docker compose up -d, then verify with docker compose config.

The container auto-detects your UID/GID from the mounted ~/.hermes volume so files written by the agent stay readable by you on the host.

To enable password protection (required if you expose the port outside 127.0.0.1):

echo "HERMES_WEBUI_PASSWORD=change-me-to-something-strong" >> .env
docker compose up -d --force-recreate

Manual `docker run` (no compose) Copy Section

docker pull ghcr.io/nesquena/hermes-webui:latest
docker run -d \
  -e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \
  -v ~/.hermes:/home/hermeswebui/.hermes \
  -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \
  -v ~/workspace:/workspace \
  -p 127.0.0.1:8787:8787 \
  ghcr.io/nesquena/hermes-webui:latest

Build locally Copy Section

docker build -t hermes-webui .
docker run -d \
  -e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \
  -v ~/.hermes:/home/hermeswebui/.hermes \
  -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \
  -v ~/workspace:/workspace \
  -p 127.0.0.1:8787:8787 \
  hermes-webui

Multi-container setups Copy Section

If you want the agent and WebUI in separate containers (for isolation, or because you're already running an agent gateway elsewhere):

# Agent + WebUI
docker compose -f docker-compose.two-container.yml up -d

# Agent + Dashboard + WebUI
docker compose -f docker-compose.three-container.yml up -d

Both compose files use named Docker volumes by default, which solves the UID/GID problem by construction. If you need bind mounts to share an existing host directory, see docs/docker.md for the full migration recipe.

Known limitation (#681): in the two-container setup, tools triggered from the WebUI run in the WebUI container, not the agent container. If you need git/node/etc. on the WebUI's filesystem, either use the single-container setup, extend the WebUI Dockerfile, or use the community all-in-one image.

Source boundary note (#2453): the multi-container setup mounts hermes-agent-src read-only into the WebUI by default. This prevents WebUI-side source rewrites but is still an implementation-coupling bridge, not a stable Agent API boundary. See docs/rfcs/agent-source-boundary.md for the current source/API decoupling inventory.

Common failure modes Copy Section

For the deep dive on each of these, see docs/docker.md.

Note: By default, Docker Compose binds to 127.0.0.1 (localhost only).
To expose on a network, change the port to "8787:8787" in docker-compose.yml
and set HERMES_WEBUI_PASSWORD to enable authentication.

Running tests Copy Chapter

Tests discover the repo and the Hermes agent dynamically -- no hardcoded paths.
Use the repo test runner so local runs do not accidentally use an unsupported
system Python. It creates/uses .venv with Python 3.11, 3.12, or 3.13 and
installs the dev test dependencies from requirements-dev.txt when missing.

cd hermes-webui
./scripts/test.sh

Pass normal pytest arguments after the script for focused runs:

./scripts/test.sh tests/test_regressions.py -v

Or seed the repo .venv from an explicit supported base interpreter:

HERMES_WEBUI_TEST_PYTHON=/path/to/python3.12 ./scripts/test.sh tests/ -v

The override selects the Python used to create or rebuild .venv; dependencies
are still installed into the repo-local virtual environment, not into the
system/Homebrew interpreter.

Tests run against an isolated server with a separate state directory.
Production data and real cron jobs are never touched. Current snapshot:
~11,500 tests collected across ~1,150 test files, run in CI on Python 3.11,
3.12, and 3.13 (3 parallel shards each).

Architecture Copy Chapter

No build step, no framework, no bundler — a Python standard-library HTTP server
and vanilla JS. The backend lives in api/, the frontend in static/.

Backend (api/)

server.py         HTTP routing shell + auth middleware
api/
  auth.py         Optional password authentication, signed cookies, passkeys
  config.py       Discovery, globals, model detection, reloadable config
  helpers.py      HTTP helpers, security headers
  models.py       Session model + CRUD + CLI/state.db bridge
  onboarding.py   First-run onboarding wizard, OAuth provider support
  profiles.py     Profile state management, hermes_cli wrapper
  routes.py       All GET + POST route handlers (if/elif dispatch, no decorators)
  state_sync.py   /insights sync — message_count to state.db
  streaming.py    SSE engine, run_agent, cancellation, compression
  updates.py      Self-update check and release notes
  upload.py       Multipart parser, file upload handler
  workspace.py    File ops, workspace helpers, git detection

Frontend (static/)

index.html        HTML template
style.css         All CSS incl. mobile responsive, themes + skins
ui.js             DOM helpers, renderMd, tool cards, context indicator
workspace.js      File preview, file ops, git badge, central api() fetch wrapper
sessions.js       Session CRUD, collapsible groups, search, reload recovery
messages.js       send(), SSE handlers, live streaming, session recovery
panels.js         Cron, skills, memory, profiles, settings (Control Center)
commands.js       Slash command autocomplete
boot.js           Mobile nav, voice input, theme/skin boot, bfcache handler

Tests + packaging

tests/            Pytest suite (~11,500 tests; isolated server/state fixtures)
pyproject.toml    Standard build metadata plus the Ruff lint gate; checkout launch surface still centers on bootstrap.py / start.sh / ctl.sh
Dockerfile        python:3.12-slim container image
docker-compose.yml  Compose with named volume and optional auth
.github/workflows/  CI: ruff + sharded pytest, browser smoke, Docker smoke,
                    multi-arch Docker build + GitHub Release on tag

State lives outside the repo at ~/.hermes/webui/ by default
(sessions, workspaces, settings, projects, last_workspace). Override with HERMES_WEBUI_STATE_DIR.
Full design notes and the endpoint catalog are in ARCHITECTURE.md.

Compatibility Copy Chapter

The version shown in the WebUI runtime status is the WebUI version only (build/image/tag currently running). It is not a full compatibility map.

The WebUI is still coupled to Hermes Agent internals for runtime execution, provider/model access, and state/schema usage until the stable agent boundary work in #1925 and #2491 land. In practice, the WebUI imports Agent modules directly (api/config.py, api/providers.py, api/streaming.py) and reads Agent state layout directly, so version skew can cause import or behavior drift.

Compatibility policy

• WebUI release branches are tested against the matching Hermes Agent release available at that WebUI release time.
• Upgrade both together: upgrade or pin WebUI and hermes-agent together (same release train/version/date), especially before enabling production traffic.
• Running pinned older/newer combinations is untested and unsupported until the stable API boundary work in #1925 / #2491 is in place.
• Record the full hermes-agent + hermes-webui versions in issue reports when upgrade mismatches are suspected.

Docker users: pin both image tags (or corresponding pinned source revisions) rather than using latest on one side and a fixed tag on the other. When upgrading the multi-container setup, follow the agent-image upgrade procedure in docs/docker.md (which requires dropping the hermes-agent-src volume before recreating). The current source-boundary status is tracked in docs/rfcs/agent-source-boundary.md.

Docs Copy Chapter

Start here

• docs/why-hermes.md — why Hermes, the mental model, and a detailed comparison to Claude Code / Codex / OpenCode / Cursor
• docs/onboarding.md — first-run wizard, provider setup, local model server Base URLs, and safe re-runs
• docs/troubleshooting.md — diagnostic flows for common failures (e.g. "AIAgent not available")

Using & customizing

• THEMES.md — theme + skin system, custom theme guide
• docs/workspace-git.md — the workspace Git controls
• docs/kanban.md — the Kanban board's status flow: who may set which column, how tasks enter and leave Scheduled, and the parent re-gating on Scheduled/Blocked → Ready
• docs/EXTENSIONS.md — administrator-controlled WebUI extension injection

Deploying & operating

• docs/remote-access.md — SSH tunnel, Tailscale, and phone access (incl. a community ARM64-Android field report)
• docs/remote-access-zh.md — 中文远程访问指南：Tailscale、SSH 隧道、Windows 原生部署（自启仅适用 WSL 用户）
• docs/advanced-chat-setup.md — optional dynamic recall-prefill and Gateway-backed browser chat for self-hosted deployments
• docs/docker.md — Docker compose setup, common failures, and bind-mount migration
• docs/supervisor.md — launchd, systemd, supervisord, runit, and s6 process-supervisor setup
• docs/wsl-autostart.md — WSL2 auto-start at Windows login
• docs/onboarding-agent-checklist.md — safety rules and pass/fail checks for assistant-led install/reinstall support

Contributing & design

• CONTRIBUTING.md — contribution style, PR expectations, and local verification
• ARCHITECTURE.md — system design, all API endpoints, implementation notes
• TESTING.md — manual browser test plan and automated coverage reference
• DESIGN.md — design tokens and the calm-console direction
• docs/UIUX-GUIDE.md — UI/UX principles sourced from the design docs and visual inventories
• docs/sse-streams.md — cross-client SSE endpoint reference: session streaming, gateway SSE probe scope, heartbeats, and proxy behavior
• docs/architecture/transcript-auto-follow-scroll.md — transcript auto-follow contract: pinned/unpinned state model, input-tail re-pinning, reader-resume rules, and the transcript's overscroll suppression rationale
• docs/CONTRACTS.md — project contract/RFC/design index for contributors and agents
• docs/rfcs/README.md — RFC index for larger architecture and durability proposals

Release history & plan

• CHANGELOG.md — release notes per version
• ROADMAP.md — feature roadmap and sprint history
• SPRINTS.md — forward sprint plan with CLI + Claude parity targets
• CONTRIBUTORS.md — the full community credit roll

Contributors Copy Chapter

Hermes WebUI is built with help from the open-source community. Every PR — whether merged directly, absorbed into a batch release, or salvaged from a larger proposal — shapes the project, and we're grateful to everyone who has taken the time to contribute.

Over 326 contributors have shipped code that landed in a release tag. The full, continuously-updated credit roll — including everyone with one or two PRs and the special-thanks roll for design and architectural work — lives in CONTRIBUTORS.md. A snapshot of the most prolific contributors:

Top contributors (by PR count, including absorbed/batch-released work) Copy Section

See CONTRIBUTORS.md for the full ranked list of all 326 contributors — the 3+ PR tables, the 1–2 PR roll, and the special-thanks notes for design and architectural contributions.

Notable contributions Copy Section

@franksong2702 — Most prolific external contributor (180 PRs, v0.49.3 → v0.51.384)
Across the longest tenure of any external contributor: the session title guard (#301), breadcrumb workspace navigation (#302), embedded workspace terminal (#1099), worktree-backed session creation (#2053), onboarding documentation (#2052), composer footer container queries, streaming-session sidebar exemption (#1327), session sidecar repair, cron output preservation (#1295), profile default workspace persistence, manual /compress async start/status endpoints (#2128), worktree status surface (#2109) + guarded remove (#2156) for the lifecycle umbrella #2057, session post-render dedup (#2166), native-WebUI fast path (#2170), tail-window response trim (#2171), stale-stream guard extension (#2158), CSP report collector (#2160), and a long tail of polish across mobile/responsive, the session sidebar, and the workspace state machine.

@Michaelyklam — Most prolific contributor of recent releases (118 PRs, v0.50.240 → v0.51.198)
Production Docker hardening (#1921, drops sudo-capable staging user), profile-scoped skills endpoints (#1903), gateway PID resolution under profile-scoped HERMES_HOME (#1901), profile-aware AIAgent cache (#1898/#1904), backslash LaTeX delimiters (#1848), Codex quota error surfacing (#1770), shell-route HTML 503 (#1836), stale Kanban client recovery (#1828), context auto-compression toast lifetime (#1988), /goal command (#1866), Kanban detail-view scrolling (#1916), CLI session tool metadata preservation (#1778), Traditional Chinese kanban locale backfill (#1979), v0.51.51 mobile Insights bucketing/layout (#2120/#2121), Hermes run adapter RFC (#2105 for #1925), fork-from-here absolute index (#2198 for #2184), opencode-go custom-provider overlap routing (#2204 for #1894).

@rodboev — Windows / cross-platform correctness + test reliability (83 PRs, v0.51.223 → v0.51.384)
A broad, sustained sweep with a strong focus on making the project work outside Linux: the ctl.sh Windows process-tree-kill fix (#3670), the local Windows full-suite signal/orphan-process work, slash-command autocomplete polish, and a long tail of frontend and infrastructure fixes shipped across dozens of release batches.

@bergeouss — Provider management UI + Docker hardening (70 PRs, v0.48.0 → v0.51.385)
Provider management UI for adding/editing custom providers from Settings, OAuth provider status detection (#1552), two-container Docker setup, profile isolation hardening (per-profile .env secrets), the bulk of what users see when they touch Settings → Providers, Reveal-in-Finder context menu (#1551), gateway status card (#1552), auto-assign session to active project filter (#1550), "What's new?" link in update banner (#1549), OpenRouter free-tier live fetch (#1548), credential pool 401 self-heal (#1553), inline provider chip + group model count in model picker (#1644).

@ai-ag2026 — Session recovery + audit infrastructure (75 PRs, v0.50.279 → v0.51.367)
Autonomous-AI contributor (Hermes Agent-driven) focused on durability: state.db-backed sidecar reconciliation (#2041), orphan .json.bak recovery on startup (#2035), read-only session recovery audit endpoints (#2036, #2040), active run lifecycle in /health (#2039), crash-safe turn-journal RFC at docs/rfcs/turn-journal.md (#2042), append-only turn-journal helper (#2059), lifecycle events layer (#2062), Content-Security-Policy-Report-Only header (#2084), per-cron toast toggle (#2100), fork-session compression lineage isolation (#2014).

@dso2ng — Session lineage + diagnostics (30 PRs, v0.50.227 → v0.51.327)
/api/session/lineage-report/<sid> endpoint for bounded session graph diagnostics (#2012), stale Mermaid render error cleanup (#1337), session_source="fork" continuation-chain isolation (#2063), lazy lineage-report fetch on sidebar badge expand (#2130), and a long tail of frontend reliability fixes around session loading.

@jasonjcwu — Composer + transcript polish (16 PRs, v0.50.227 → v0.51.132)
Sidebar collapse via active-rail click (#2054, fuses #1884 + #1924), composer chip lightbox (#1758), title fixes for tool-heavy first turns, silent compress-status during session switch (#2185), concurrent-send loss fix (#2186), in-transcript steer message badges (#2187), and a string of frontend polish fixes.

@Jordan-SkyLF — Live streaming + UX polish (12 PRs, v0.50.18 → v0.51.66)
Original sprint of workspace fallback resolution, live reasoning cards (#366, #367, #394–#397), then a recent burst: manual "Refresh usage" button on the Provider quota card (#2150), cancelled-turn status classification (#2151), Firefox sidebar scroll stabilization (#2200), early provisional session titles (#2202), target-aware "What's new?" update-banner links (#2207), and MCP tools overflow fix in Settings (#2210).

@aronprins — v0.50.0 UI overhaul (PR #242, plus 9 follow-ups)
The biggest single contribution to the project: a complete UI redesign that moved model/profile/workspace controls into the composer footer, replaced the gear-icon settings panel with the Hermes Control Center (tabbed modal), removed the activity bar in favor of inline composer status, redesigned the session list with a ⋯ action dropdown, and added the workspace panel state machine. Plus chat transcript redesign (#587), sidebar declutter (#584), three-column layout refactor (#899), light/dark theme + accent skins (#627), and shared confirm()/prompt() dialog replacement (PR #251 extracted from #242).

@iRonin — Security hardening sprint (PRs #196–#204)
Six consecutive, focused security PRs: session memory leak fix (expired token pruning), CSP + Permissions-Policy headers, 30-second slow-client connection timeout, optional HTTPS/TLS support via environment variables, upstream branch tracking fix for self-update, and CLI session support in the file-browser API. The kind of focused, high-quality security work that makes a self-hosted tool trustworthy.

@lucasrc — Auth-hardening trilogy (PRs #2191, #2192, #2193)
Three coordinated security PRs that all landed in v0.51.57: thread-safe login rate limiter with PBKDF2 key separation, password-hash cache invalidation on Settings save, and the full 64-char HMAC-SHA256 session signature with a backwards-compatible migration bridge. The kind of cleanly-decomposed security work that's reviewable as three independent pieces.

@LumenYoung — Streaming hot-path correctness (8 PRs, v0.51.47 → v0.51.99)
The original stale-stream writeback guard (#2136 — the bug class the next two releases extended), gateway-state alive-null classification (#2075), compression-banner anchor alignment (#2182), and context-progress ring auto-refresh on compression complete (#2188). Each PR opened a small surgical fix in one of the most fragile subsystems in the codebase.

@dobby-d-elf — Frontend reliability + motion polish (15 PRs, v0.51.38 → v0.51.161)
Workspace fallback on deleted directories (#2138), iPhone PWA bottom-scroll fix (#2143), the new "Activity: X tools" composer footer shimmer animation (#2203), and follow-up animation tuning (#2212).

@JKJameson — Composer + session polish (10 PRs)
Persistent composer draft per session (#1956), and a long tail of polish across the composer and session sidebar.

@gabogabucho — Spanish locale + onboarding wizard
Full Spanish (es) locale covering all UI strings, plus the one-shot bootstrap onboarding wizard that guides new users through provider setup on first launch.

@deboste — Reverse-proxy auth + mobile responsive layout (PRs #3, #4, #5)
Three of the very first community PRs: fixed EventSource/fetch to use URL origin for reverse-proxy setups, corrected model provider routing from config, and added mobile responsive layout with dvh viewport fix. Early foundation work.

@indigokarasu — Visual redesign proposal (PR #213)
A CSS-only redesign of the full UI — proper design tokens, an icon rail sidebar replacing the emoji tab strip, consistent form cards, breadcrumb nav, and 7 built-in themes as custom properties. The PR didn't merge as-is but shaped the design language and theme architecture that shipped in v0.50.0.

@zenc-cp — Anti-hallucination guard for the ReAct loop (PR #133)
A three-layer approach (ephemeral anti-hallucination prompt, live token filtering, session-history cleanup) that the streaming pipeline still uses.

@Hinotoi-agent — Profile + session security (PRs #351, #2048)
Profile .env secret isolation fix (PR #351) preventing API key leakage between profiles, and session-import workspace validation (PR #2048) blocking a crafted-JSON file-read against /.

@Sanjays2402 — Endless-scroll + Start-jump race fix (PR #1949)
A generation-token + mutex pair fixing the v0.51.30 race between endless-scroll prefetch and Start-jump's _ensureAllMessagesLoaded. The naive same-flag-check approach (proposed in #1942 and #1962) was a no-op for the post-await race — Sanjays2402's fix was the correct shape.

@fxd-jason — Real-time approval + clarify via SSE (PRs #1350, #1355)
Replaced 1.5s HTTP polling with SSE long-connections for both approval and clarify, cutting latency from up to 1.5s to near-instant. Got all the correctness details right (atomic subscribe + snapshot, notify-inside-lock, head-of-queue payload, trailing event re-emission).

@happy5318 — Custom provider model dedup (PR #1947)
Fixed the same model from different named custom providers being silently deduplicated in the picker, with Opus catching a race in the original tests that needed augmentation.

@NocGeek — Streaming scroll + manual cron output persistence (7 PRs)
Streaming scroll viewport stability when tool/queue cards insert (#1360), manual cron-run output and metadata persistence (#1372, split from held #1352).

@DavidSchuchert — German translation (PR #190)
Complete German locale (de) covering all UI strings, settings labels, commands, and system messages — and stress-tested the i18n system, exposing several elements that weren't yet translatable and getting them fixed as part of the same PR.

@Bobby9228 — Mobile Profiles button (PR #265)
Added the Profiles entry to the mobile navigation flow, making profile switching reachable on phones.

@kevin-ho — OLED theme (PR #168)
The 7th built-in theme: pure black backgrounds with warm accents tuned to reduce burn-in risk.

@andrewy-wizard — Chinese localization (PR #177)
Initial Simplified Chinese (zh) locale. One of the first non-English locales.

@DelightRun — session_search fix for WebUI sessions (PR #356)
Tracked down the missing SessionDB injection in the streaming path that was silently breaking the tool for every WebUI session.

@lawrencel1ng — Bandit security fixes (PR #354)
Systematic bandit-scan fixes: URL scheme validation before urlopen, MD5 usedforsecurity=False, and 40+ bare except: pass blocks replaced with proper logging.

@shaoxianbilly — Unicode filename downloads (PR #378)
Proper Content-Disposition with RFC 5987 filename*=UTF-8''... encoding so non-ASCII filenames download without crashing.

@lx3133584 — CSRF fix for reverse proxy (PR #360)
A real-world blocker for anyone hosting behind Nginx Proxy Manager or similar on a port other than 80/443.

@betamod — Security audit (PR #171)
A comprehensive CSRF / SSRF / XSS / env-race-condition audit that shipped in v0.39.0.

@TaraTheStar — Bot name + thinking blocks + login refactor (PRs #132, #176, #181)
Configurable assistant display name, thinking/reasoning block display, and a login page refactor.

Repo Copy Chapter

[email protected]:nesquena/hermes-webui.git

Overview (`docs/rfcs/README.md`) Copy Section

RFCs

This directory holds design documents for hermes-webui features that are
worth thinking through in writing before (or alongside) implementation —
typically when the change touches durability, recovery, schema, or cross-
cutting infrastructure.

Conventions Copy Chapter

• One file per RFC. Filename is the topic (kebab-case), not a number.

• Top of every RFC carries a small header:

  text Copy

  - **Status:** Proposed | Accepted | Implemented | Withdrawn
  - **Author:** @github-handle
  - **Created:** YYYY-MM-DD

• Sections usually include: Problem, Goals, Non-goals, Proposal, Open
  questions, Rollout plan. Skip what doesn't apply.

• An RFC is a starting point for review. Comments and revisions land via PR
  edits, not separate discussion threads.

• An RFC documents a design direction. It is not an invitation to file
  implementation PRs against fragments of it. Before opening any PR that
  implements an accepted RFC, confirm with a maintainer in the tracking
  issue that the implementation slice is wanted and that no other
  contributor is already building it. Speculative implementations of RFC
  fragments without a confirmed integration site will be held.

When to file an RFC Copy Chapter

• The change is large enough that you want consensus before writing code.
• The change touches data-at-rest formats or recovery semantics.
• The change introduces a new architectural primitive (journal, queue,
  scheduler, cache layer) that other features will build on.
• A reviewer asks for one during code review.

When in doubt, just ship the code — small features don't need RFCs.
First-time contributor RFCs should be discussed in an issue before opening a PR.

Current RFCs Copy Chapter

• hermes-run-adapter-contract.md — #1925
  event/control contract, runtime-state ownership matrix, acceptance catalog,
  and reversible migration gates for moving WebUI execution behind an explicit
  adapter boundary.
• webui-run-state-consistency-contract.md
  — #2361 consistency rules for keeping transcript, model context, live streams,
  replay, compression, and session metadata coherent during active and recovered
  WebUI runs, including the per-layer authority matrix (authority, persistence
  lifetime, allowed divergence, replay/recovery rules) and the review checklist.
• live-to-final-assistant-replies.md
  — #3400 accepted product model for long-running assistant replies, live
  process prose, tool activity, recovery, terminal outcomes, display
  projections, and the final-answer boundary.
• transparent-stream-activity-mode.md
  — #3820 implemented opt-in display mode for power users who need a
  transparent, chronological Thinking / progress / tool-call stream alongside
  the default Compact Worklog and opt-in Final answer only projections.
• stable-assistant-turn-anchors.md — #3926
  implemented frontend presentation/reconciliation model for anchoring live
  assistant activity, settled final answers, replay, and all activity display
  modes to one assistant turn; remaining hardening is tracked under #3400.
• canonical-session-resolution.md — #2361
  focused contract for resolving URL, query parameter, localStorage, sidebar,
  and compression-lineage session IDs to one canonical visible chat target.
• turn-journal.md — Crash-safe WebUI turn journal for
  recovering interrupted chat submissions.
• webui-pending-intent-controls.md —
  #3058 control-surface companion to #3400 for Queue, Steer, Stop-and-send,
  Interrupt, and leftover-steer inputs submitted while a long-running agent
  session is active.
• session-sse-contract-v1.md — #4812 Proposed
  contract vocabulary, replay identity, event taxonomy, cursor/resume semantics,
  and implementation gates for GET /api/sessions/{session_id}/events.
• exact-persisted-message-replay-guard.md
  — proposed persistence-boundary invariant that removes only byte-equivalent
  replay rows carrying stable event identity before a session save.

Overview (`docs/pr-media/6469-sidebar-handoff/README.md`) Copy Section

Sidebar idle / terminal handoff evidence

Failure and scope Copy Chapter

The independent /api/sessions response can report idle before the chat SSE's
terminal frame reaches the page. Three sidebar paths were retiring chat state:
idle reconciliation, INFLIGHT purging, and optimistic-row retirement. The idle
path clears the Worklog and active stream ID; the subsequent done is rejected
as stale, so no settled Anchor scene is persisted.

A real-HTTP barrier reproduces this on both published PR head
75c8ff8d2a991f22389e3e4263ee03fb8d8f67a0 and frozen upstream
b09fded7b8c98b549a49aaaece3721015337d307. Applying only the sessions.js
product fix to the frozen upstream also passes the identical oracle: this is a
shared lifecycle defect, not evidence that artifact replay introduced it. The
historical hosted run lacks this instrumentation, so its exact interleaving
cannot be proved retrospectively; its empty-surface/no-persistence signature
matches the controlled reproduction.

Reproduction Copy Chapter

LIFECYCLE_SCENARIO=normal LIFECYCLE_TEST_BITE=settle-worklog-frame-proof \
  .venv/bin/python tests/browser_conversation_lifecycle.py
./scripts/test.sh tests/test_sidebar_terminal_handoff.py -q

The existing frame proof now uses a test-only server wrapper to hold the actual
done HTTP write. The real worker finishes; the real browser receives an idle
sidebar response through renderSessionList() while its native EventSource
remains open. The test verifies pane, INFLIGHT and registry ownership, then
releases done and retains all existing painted-frame, final-answer, semantic
activity and hard-reload assertions. The fixture always releases/cleans up and
has a bounded wait. Normal production server startup is unchanged.

No renderer, terminal payload or persistence response is fabricated. Runtime
events come from the existing deterministic localhost Gateway fixture, not a
live model/provider. All state and files are disposable. These are browser
viewport checks, not physical-device acceptance.

Before / after Copy Chapter

Each screenshot is taken after the idle sidebar response, before the terminal
HTTP frame is released. The exact published source fails at both widths. The
patched source preserves three live activity rows and then passes completion
and hard reload. results.json records the predicate results without machine
paths or credentials.

The fix only defers these sidebar cleanups for the current pane's exact OPEN
chat transport. Missing, CONNECTING, CLOSED and mismatched sources still take
the existing stale recovery path.

Missing terminal frame: bounded recovery Copy Chapter

The OPEN-only guard at 85f1c2d34b62b0ade85f51ed2cf8c1cf56f5ab9e could wait
forever when the terminal frame never arrived. The follow-up keeps the live
handoff for 1.5 seconds, then probes the exact stream through
/api/chat/stream/status with an eight-second timeout and no retries.
Repeated sidebar hints cannot restart the deadline or create concurrent
requests. active:true keeps the OPEN owner intact even when the persisted
session fields already look idle; only explicit runtime inactivity permits the
canonical session restore. A failed or malformed runtime probe uses the
existing interrupted-stream path rather than claiming successful settlement.
Normal terminal delivery, transport replacement/close, navigation, and a newer
optimistic turn invalidate the old request. Already-running stream-end recovery
remains the sole recovery owner.

LIFECYCLE_SCENARIO=normal LIFECYCLE_TEST_BITE=sidebar-idle-missing-terminal \
  .venv/bin/python tests/browser_conversation_lifecycle.py
./scripts/test.sh tests/test_sidebar_idle_stream_recovery.py -q

The new browser row keeps the real terminal HTTP barrier closed until cleanup;
the client must recover without receiving done or stream_end. Published
85f1c2d34b fails the 11-second completion bound with S.busy still true.
The patched implementation restores the final answer and passes the unchanged
painted-frame, semantic activity, persistence and hard-reload checks before the
barrier is released. The cloud workflow runs both delayed- and missing-terminal
rows. No live provider or production state is used.

A production Gateway regression also blocks post-turn goal evaluation after
the success transcript has already cleared active_stream_id and pending
fields. During that interval the worker and exact entry in STREAMS remain
live and no done event has been emitted, proving why persisted session flags
cannot authorize sidebar settlement on their own.

Overview (`docs/pr-media/7245/README.md`) Copy Section

PR #7245 — retired message-action failure proof

Captured on 2026-09-20 in Chrome 153.0.8010.52 with fresh, disposable browser
contexts, at 1440 × 900 and 390 × 844. No real sessions, model calls, credentials,
production state, or existing browser profile were used.

What the images prove Copy Chapter

These are explicitly synthetic transcript fixtures, not screenshots of a live
user conversation. They compose the current production message-action rendering
helpers from static/ui.js, the actual icons/styles, and the complete extension
runtime. The fixture's status line displays the message passed to Core's error
callback; it is not a screenshot of the full application's toast styling.

The before/after variable is the runtime: before uses published PR head
b3c2e39f219b9778200fdeebd1a777764c112726; after uses the repaired runtime on the
integration containing upstream 10003f46d48415a7f5691b2018ad76bfe5486863.

The test clicks an action, unregisters it, registers and starts a replacement
with the same ID/target, then rejects the original native Promise. Before,
the old invocation reports one error even while the replacement is correctly
pending. After, it reports none; the replacement remains pending until its own
completion. Neither case produces an uncaught browser exception.

The same browser fixture also exercised pressed-state invalidation, duplicate
click suppression, concurrent targets, attachment-only empty text, frozen click
context, connected-opener focus, HTML-cache reconstruction, hidden-row exclusion,
stale-index rejection, and uninstall cleanup. Narrow action targets measured
40 × 40 px. This does not prove every full-app virtualization or network-recovery
schedule; those retain the separate repository tests and hosted lifecycle gates.

Reproducible regression tests Copy Chapter

./scripts/test.sh tests/test_extension_message_actions.py -k retired_message_action -q

All four variants failed at the observable error callback before the product fix
and passed afterward: unregister, same-ID replacement, uninstall, and a thenable
that reports failure after already reporting success. Existing tests continue to
verify that errors from a current invocation are surfaced.

A separate agent-free smoke check booted the real server.py with isolated HOME,
state and workspace on loopback, then loaded /, /#settings, and /#sessions
at both viewports: zero console errors and zero uncaught exceptions. The fixture
images above are not presented as evidence of that separate full-app check.

Overview (`docs/pr-media/reasoning-hydration/README.md`) Copy Section

Stored reasoning identity: browser evidence

These are synthetic persisted-session fixtures, not user conversations. They run
through Session.save(), the real WebUI HTTP session loader and the unmodified
browser renderer. No Agent/provider invocation is made. Public static assets load
as in the existing browser gates; this is not a network sandbox certification.

Frozen baseline: ff26335b87610f70d74ff008608a321fb1281bd1.
The fixture contains two same-text events with IDs A/B and one exact redelivery
of A. Before the API fix, both initial load and hard reload show only A. After the
fix they show A/B exactly once. Tests assert the DOM row identities, not merely
that two labels are visible. The Thinking cards are collapsed in these captures;
the machine-readable snapshots also check their identical retained text.

Reproduce from the candidate checkout:

.venv/bin/python tests/browser_reasoning_identity_hydration.py --artifact-dir /tmp/reasoning-proof

The same driver on the baseline fails all four load/reload × desktop/narrow
identity assertions. It uses disposable Hermes/state/workspace directories and
stops its own server/browser; it does not modify production sessions. Test setup
initially lacked the seed directory and a trial's blanket external-resource block
caused console failures. Neither was counted as product RED evidence. The final
baseline/candidate comparison uses the same corrected driver.

October 1 filtered-reasoning regression Copy Chapter

Baseline: reviewed head 5ca72febbab3 plus normal upstream merge
dd5451903686 (product fix absent). A persisted running Thinking row carries
its exact stream identity. Transcript reasoning either repeats visible progress
or matches the final answer; neither should consume a reconciliation slot.

Both variants fail the intended DOM identity assertion on baseline: the two saved
Thinking events are absent on load and hard reload at 1280px and 390px. After the
slot filter, both variants preserve A/B exactly once in all eight combinations.
The four images below show the visible-prose variant after hard reload; the
final-answer variant has the same missing/preserved event outcome.

.venv/bin/python tests/browser_reasoning_identity_hydration.py --filtered-reasoning visible-prose --artifact-dir /tmp/reasoning-filter-prose
.venv/bin/python tests/browser_reasoning_identity_hydration.py --filtered-reasoning final-answer --artifact-dir /tmp/reasoning-filter-final

These remain synthetic, isolated Chromium checks; no physical-device or live
provider behavior is claimed. An initial trial lacked per-row stream ownership
and passed on baseline, so it is not negative proof. A second trial waited for
an absent worklog and timed out; the final driver captures missing rows and fails
on their identities instead of counting a timeout as evidence.

October 1 second review: missing reasoning metadata Copy Chapter

No-tool thinking content with no reasoning metadata must not allocate a
settlement slot that discards a distinct saved running event. The synthetic
persisted fixture contains Transcript thought in content parts and saved
Distinct saved thought with event ID saved-event and row ID saved-row.

The baseline is reviewed head b2fadb981b90988138d1a34bf55b2bf415ac4471
plus upstream de512304b306211e71da103b5c218b17ef8d4ddc, merge commit
7cf6fc55b7a5244cf25960cd24fd7ab2bd153ee0. On that baseline, actual server
load and hard reload lose the saved ID and show Transcript thought at both
1280 and 390 px. The repaired product commit
6a3c432fde1a97d5261696bdac04cdbb210d8cf1 preserves the saved row/event IDs,
Distinct saved thought, completed status, and exactly one final answer.
Both missing and empty metadata cases pass all eight width/load combinations.
Thinking details were opened with real header clicks before capture.

python tests/browser_reasoning_identity_hydration.py --no-tool-reasoning missing-metadata --artifact-dir /tmp/reasoning-no-metadata
python tests/browser_reasoning_identity_hydration.py --no-tool-reasoning empty-metadata --artifact-dir /tmp/reasoning-empty-metadata

The driver launches isolated temporary state/workspace and an Agent-free stub;
no real provider or personal session is used. Existing visible-prose/final-answer
filtering and equal-text/different-ID browser cases also passed.

October 1 third review: transcript Markdown owns the prose body Copy Chapter

Baseline: reviewed head b0bf02710664 plus pinned upstream
e33da25c6cfde3ea337e1b6d7701161d02e995cf, normal merge
b6198a23fa9493f9a24d5f45c549fbd722196e52. The saved running prose row
carries saved-prose-event / saved-prose-row, but its live text has collapsed
whitespace. The settled transcript contains exact Markdown and a read_file
tool call before the final answer.

Before the repair, hydration inherits the saved row's flattened body as well as
its identity: the fenced block has no native pre code element, and the two
lists collapse into one item. After the repair, hydration retains the exact
transcript text and payload, source and grouping metadata, while inheriting
only durable identity fields. The browser keeps a native fenced block with
print(42), an unordered list with a / b, an ordered list with c, one tool
row, and one final answer through both initial load and hard reload. The images
below capture hard reload at 1280 × 900 and 390 × 900.

.venv/bin/python tests/browser_reasoning_identity_hydration.py --transcript-markdown fenced-code --artifact-dir /tmp/prose-fenced
.venv/bin/python tests/browser_reasoning_identity_hydration.py --transcript-markdown lists --artifact-dir /tmp/prose-lists
.venv/bin/python tests/browser_reasoning_identity_hydration.py --transcript-markdown indented-code --artifact-dir /tmp/prose-indented

The exact indented-code review fixture is covered too: hydration must retain
print(42)\n print(43) byte-for-byte in scene text and payload. Current
renderMd already renders this fixture as a paragraph when given the exact
transcript, rather than a native indented code block. The browser's indented
case checks source ownership and parity with that existing renderer; this
repair does not claim to add native indented-code syntax support. Existing
Thinking text/identity behavior and metadata-only no-tool reasoning boundaries
remain covered by the same driver and focused regressions.

These are synthetic persisted sessions, real HTTP loads and Chromium DOM
checks, with isolated temporary Hermes/state/workspace and no provider request
or personal data. Machine-readable snapshots capture both load and reload.

CONTRACTS (`docs/CONTRACTS.md`) Copy Section

Project Contracts

This document is a contributor-facing index for existing Hermes WebUI contracts,
RFCs, design constraints, and review expectations. It does not replace the
source documents and it does not mark proposals as implemented. Follow each
linked document's status and scope.

Use this file when starting a change so the relevant public contract is visible
before code is edited. This index focuses on documentation routing and
contributor guidance; it does not change runtime behavior or CI gates.

Start here Copy Chapter

• AGENTS.md: repository entry point for AI assistants,
  public-safety rules, and the short redline checklist.
• CONTRIBUTING.md: contribution style, verification,
  PR description expectations, UI evidence, and project-specific constraints.
• README.md: product overview, quick start, architecture map,
  feature inventory, and docs index.
• CHANGELOG.md: release history maintained by the release
  workflow. Read it for context, but do not edit it in ordinary contributor PRs;
  put release-note-ready wording in the PR body instead.

Runtime, durability, and state contracts Copy Chapter

• docs/remote-workspaces.md:
  architecture contract for remote terminal workspaces (SSH/Docker), target-side
  POSIX path preservation against macOS synthetic firmlink expansion, and
  per-profile isolation boundaries.
• docs/rfcs/webui-run-state-consistency-contract.md:
  proposed consistency rules for current WebUI streaming, recovery, replay,
  model-context reconstruction, compression, UI scene/cache, and sidebar metadata
  repairs. Start here for narrow fixes that keep the existing WebUI execution
  path.
• docs/rfcs/live-to-final-assistant-replies.md:
  accepted product model for long-running assistant replies, live process text,
  tool activity, recovery, terminal outcomes, and final-answer boundaries. Start
  here for UI/UX changes to running-session assistant reply rendering.
• docs/rfcs/stable-assistant-turn-anchors.md:
  implemented presentation/reconciliation model that attaches live, settled,
  replayed, and recovered activity to one assistant-turn owner and projects one
  activity_scene_v1 into Compact Worklog, Transparent Stream, or Final answer
  only. Remaining hardening stays tracked under #3400.
• docs/architecture/stable-assistant-turn-anchor-phase0.md:
  cumulative implementation inventory for the Stable Assistant Turn Anchors
  work under #3926. Use it to distinguish shipped wiring from historical slice
  boundaries before changing live SSE, replay, settlement, INFLIGHT, or
  renderMessages() paths.
• docs/architecture/transcript-auto-follow-scroll.md:
  implemented contract for transcript auto-follow: the pinned/unpinned state
  model, the input-tail capture and reader-resume re-pinning rules (including
  one-consumption-per-input and reader input outranking queued restores), and
  the overscroll-behavior-y: none rationale for .messages. Start here
  before changing the scroll listener, the settle writer, or the queued
  live-render restore paths.
• docs/rfcs/canonical-session-resolution.md:
  proposed contract for resolving URL routes, query parameters, localStorage,
  sidebar rows, and compression-lineage IDs to one canonical visible session
  target. Start here for session routing, boot restore, stale parent, or
  compression-tip selection changes.
• docs/rfcs/hermes-run-adapter-contract.md:
  proposed event/control contract, runtime-state ownership matrix,
  acceptance-test catalog, and reversible migration gates for moving WebUI
  execution behind an adapter boundary. Use this for adapter-seam, control-plane,
  runner, sidecar, or execution-ownership work; do not treat it as authorization
  to implement those slices.
• docs/architecture/agent-api-contract.md:
  current audit of WebUI dependencies on the hermes-agent source checkout and
  the replacement API/client surfaces needed before source mounts can be removed.
  Start here for issue #2491 and Docker/source-boundary migration slices.
• docs/rfcs/turn-journal.md: proposed crash-safe
  write-ahead journal for browser-originated chat turns.
• docs/rfcs/webui-pending-intent-controls.md:
  proposed control-surface companion to the long-running-session reply model for
  Queue, Steer, Stop-and-send, Interrupt, and leftover-steer inputs submitted
  while an agent run is active. Start here for busy-composer behavior, pending
  queued messages, interrupt replacement, steer visibility, or leftover-steer
  recovery changes.
• docs/rfcs/README.md: RFC conventions and current RFC index.
• docs/rfcs/session-sse-contract-v1.md:
  proposed contract vocabulary, cursor/resume semantics, replay identity, snapshot
  fallback, event taxonomy, and implementation gates for the per-session SSE
  stream GET /api/sessions/{session_id}/events (#4812). Distinct from the
  existing global session-list stream GET /api/sessions/events. Start here for
  any work that touches per-session SSE, Last-Event-ID replay, or session
  lifecycle event delivery. The Phase 1 server route and journal relay for
  GET /api/sessions/{session_id}/events are implemented; broader client,
  platform, and semantic-taxonomy claims in the RFC remain behind the recorded
  proof gates. Prefer the RFC's Authoritative emitted events table (live
  /api/chat/stream wire names) over the aspirational semantic taxonomy when
  writing clients against current source.
• docs/architecture/models-cache-invalidation.md:
  current contract for the /api/models catalog cache identity: the
  config.yaml, auth.json, and catalog source-fingerprint axes, the
  one-directional volatile-key deny-lists (auth rotation and Codex's
  models_cache.json refresh timestamps), the stat-identity fallbacks, and the
  schema/version stamps. Start here before changing model-catalog caching, the
  /api/models cache keys, or the Codex catalog dependency (#2443, #7540).
• docs/architecture/send-path-model-provider.md:
  current contract for which provider the browser routes an outgoing chat turn
  to: the _modelProviderForSend() precedence order (explicit @provider:model
  tag → dropdown provider with session-scoped pick evidence → the loaded
  session's own provider → persisted state → null), why a bare dropdown match
  is not intent after a restore, and the lifecycle of the picker's explicit-pick
  marker. Start here before changing provider precedence for outgoing turns,
  the picker's pick evidence, or restored-session provider resolution
  (#7860, #7865).
• docs/architecture/live-models-allowlist.md:
  current contract for how /api/models/live filters a custom provider's
  upstream catalog: the four signals in evaluation order (discovered catalog
  defers to the live probe, explicit plural models: allowlist filters,
  singular model: never gates, no allowlist shows the full catalog), the
  serialized-list shapes hermes config set persists, the deliberate
  empty-allowlist-is-not-configured rule, and the probe-failure fallback.
  Start here before changing custom-provider model filtering or
  discovery-vs-allowlist semantics (#7165, #7404).
• docs/architecture/profile-home-resolve-cache.md:
  current contract for the call-scoped memoization around
  _resolve_profile_home_param() in api/workspace.py: what it caches, the
  one-hot-loop scope (_load_cli_sessions_uncached) versus every other call
  site getting fresh resolution, and the freshness guarantee that a symlink
  retarget or transient resolve fallback is always observed on the next call.
  Start here before widening this cache's scope or adding a similar
  call-scoped cache elsewhere (#7636).
• docs/architecture/session-channel-lifecycle.md:
  current contract for the per-session SSE channel and the per-turn stream lifecycle: the state
  layers and their authoritative writers, the writer-side subscriber-liveness signal plus the
  channel collection rules (GRACE, IDLE_TTL, queue-stall and writer-staleness), the single
  orphan predicate shared by chat/start admission, busy reporting and the reaper, the
  launch-phase claim that covers registration-to-admission, and the lock discipline
  (STREAMS_LOCK → ACTIVE_RUNS_LOCK). Start here before changing subscriber liveness, channel
  collection, stream registration, or orphan reclaim (#7302).

When a change touches streaming, recovery, replay, compression, context
reconstruction, cancellation, approval/clarify, session metadata, or run state,
read the relevant RFC before editing. In the PR description, name the state layer
or event/control surface affected and include a regression test or manual
verification for the relevant invariant.

Proposed RFCs are review guardrails, not implementation authorization. Do not
implement RFC fragments unless the task or tracking issue explicitly asks for
that slice.

UI, UX, and theme contracts Copy Chapter

• DESIGN.md: design tokens and the current calm-console
  direction: conversation first, quiet metadata, restrained accents, and
  progressive disclosure for debugging detail.
• docs/UIUX-GUIDE.md: contributor-facing synthesis of the
  repository's UI/UX principles, sourced from existing project docs and code
  comments.
• docs/ui-ux/index.html: message-area inventory wired to
  the real app stylesheet.
• docs/ui-ux/two-stage-proposal.html:
  existing two-stage chat UX proposal for issue #536.
• THEMES.md: theme and skin guidance; the core palette
  variable contract lives in static/style.css.

Current appearance has a theme axis (light, dark, system) and a separate
skin axis (default, ares, mono, slate, poseidon, sisyphus,
charizard, sienna, catppuccin, nous, geist-contrast) in
static/boot.js and static/style.css. Do not follow stale data-theme-only theme guidance unless
the current code and tests prove that model still applies.

For UI or UX work, include before/after evidence, verify relevant responsive
states, and prefer stable class/data hooks over one-off visual behavior.

Choosing the relevant contract Copy Chapter

Before editing, identify which contract family the task exercises. This is a
routing check, not a request to read every document in the repository. Read the
documents that match the touched subsystem.

Use this lightweight note in an issue comment, draft PR, task note, or AI-agent
handoff when it helps clarify scope:

## Contract Routing

Task type:
Touched areas:
Relevant public docs:
- `AGENTS.md`
- `CONTRIBUTING.md`
- `docs/CONTRACTS.md`
- <subsystem-specific documents>
Scope boundaries:
Evidence needed before claiming done:

For small, obvious fixes, keep this short. The goal is to avoid routing mistakes,
not to create process overhead.

Contract changes Copy Chapter

Changing contract documents, RFC guidance, or contract tests changes review
expectations for future contributors. A PR that intentionally changes an
existing contract should include a Contract Change section in its PR body with:

• the previous contract,
• the new contract,
• the affected docs and tests,
• the compatibility or migration reason.

Contract tests and corresponding docs must move together. Tests that encode
product semantics must not silently redefine the contract by asserting the
opposite behavior without updating the public docs and naming the change in the
PR body.

The static tests for this guidance are advisory coverage. They pin contributor
wording so the rule stays visible. This advisory coverage is not an automated
policy gate; static coverage is not an automated policy gate and does not enforce
PR-body content on GitHub. A future release-time or CI check could
surface contract-affecting diffs whose PR body lacks Contract Routing, but this
document only defines the review expectation.

Release batches should list included contract-affecting PRs explicitly so
reviewers can distinguish ordinary green-CI fixes from changes that update the
project's product or runtime guardrails.

PR preparation checklist Copy Chapter

Before opening or updating a PR, verify CONTRIBUTING.md against the actual PR
body. This checklist applies even when code and tests are already done.

Required checks:

• The PR solves one logical problem.
• The PR body contains all required sections from CONTRIBUTING.md:
  Thinking Path, What Changed, Why It Matters, Verification,
  Risks / Follow-ups, and Model Used.
• Model Used discloses provider/model and notable agent/tool use, or says
  None -- human-authored.
• UI/UX changes include before/after evidence and responsive-state coverage.
• Runtime/streaming changes name the state layer or invariant being changed and
  list the regression or manual invariant check.
• Contract-affecting PRs include Contract Routing; intentional contract
  changes also include Contract Change.
• Onboarding/setup validation used isolated HERMES_HOME and
  HERMES_WEBUI_STATE_DIR, unless the human operator explicitly requested real
  state.
• Docs updates are included or explicitly not needed, and release-note-worthy
  changes are described in the PR body rather than by editing CHANGELOG.md.
• After the GitHub write, read the PR back and verify the headings rendered as
  intended.

Green CI plus a focused diff is not sufficient if the PR description or evidence
does not match the touched subsystem.

Setup, onboarding, and operational references Copy Chapter

• TESTING.md: automated test command and manual browser test
  plan.
• ARCHITECTURE.md: API, module layout, and design
  constraints.
• docs/onboarding.md: first-run wizard and provider setup.
• docs/onboarding-agent-checklist.md: safety
  rules for assistant-led install, reinstall, bootstrap, provider setup, local
  model setup, Docker onboarding, and WSL onboarding.
• docs/docker.md: Docker compose setup, common failures, and
  bind-mount migration.
• docs/troubleshooting.md: diagnostic flows for common
  failures.
• docs/EXTENSIONS.md: administrator-controlled WebUI
  extension injection.

Quick redline checklist Copy Chapter

Before opening a change for review, confirm:

• The change solves one logical problem; unrelated refactors are split out.
• AGENTS.md, this index, and any linked contract for the touched subsystem were
  read before editing.
• Behavior, setup, architecture, testing, or workflow changes update the relevant
  docs; release-note-ready changes include PR-body release-note wording while
  CHANGELOG.md is left to release commits.
• UI/UX changes include before/after evidence and cover relevant desktop,
  narrow, and mobile states.
• Runtime, streaming, recovery, replay, compression, or sidebar changes state
  which layer they mutate and include a regression for the invariant.
• New dependencies, build tools, frameworks, or long-lived processes are avoided
  unless the benefit and rollback story are explicit.
• Onboarding/setup validation uses isolated HERMES_HOME and
  HERMES_WEBUI_STATE_DIR unless the human operator explicitly asks to use real
  state.
• Secrets, private paths, local-only workflows, and personal notes stay out of
  tracked docs and examples.

Future evolution Copy Chapter

This index is not intended to make the first contract set final. Future PRs may
add, revise, split, or retire contracts when real issues, implementation changes,
RFC decisions, contributor feedback, or review experience show that guidance is
incomplete or stale.

Potential follow-up areas include session import/export, cron, extensions,
security boundaries, Docker/runtime isolation, and lightweight checks that keep
key contract links from drifting.

EXTENSIONS (`docs/EXTENSIONS.md`) Copy Section

WebUI Extensions

Hermes WebUI supports a small, opt-in extension surface for self-hosted installs.
It lets an administrator serve local static assets and inject same-origin CSS or
JavaScript into the app shell without editing the WebUI source tree.

Trust model — read this first. Extensions execute with full WebUI session
authority. An extension JS file can call any API the logged-in user can call,
including reading conversation history, sending messages, modifying settings,
and triggering tool actions. Only enable extensions you wrote yourself or
from sources you trust as much as the WebUI source itself. If your WebUI is
shared with users you do not fully trust, do not enable extensions.
If you set HERMES_WEBUI_EXTENSION_DIR yourself, do not point it at a
user-writable directory on a shared host.

This is intentionally not a plugin marketplace or dependency system. It is a
safe escape hatch for local dashboards, internal tooling, and workflow-specific
panels that should not live in core Hermes WebUI.

The vetted extension library. The curated, one-click-installable extensions
that appear in the gallery live in a separate public repo:
hermes-webui/hermes-webui-extensions.
"In the registry == vetted." That repo holds the entries, the authoring
conventions (docs/extension-entry.md),
the JSON schema, and the CI safety gates. This document covers the WebUI-side
infrastructure (loader, manifest contract, capabilities, install client);
see the library repo to browse existing extensions or contribute a new one.

What extensions can do Copy Chapter

Extensions can:

• serve files from one configured local directory at /extensions/...
• inject configured same-origin stylesheets into <head>
• inject configured same-origin scripts before ``
• read a local JSON manifest that lists bundled scripts/styles to inject
• call the normal WebUI APIs available to the browser session
• call trusted local loopback sidecars directly from extension JavaScript when
  the browser Content Security Policy allows that origin

Extensions cannot, by themselves:

• bypass WebUI authentication
• serve files outside the configured extension directory
• load third-party scripts/styles through the built-in injection config
• register new WebUI backend routes or proxy arbitrary sidecar/backend traffic
  outside the fixed consented extension sidecar path described below
• change Hermes Agent permissions, models, memory, or tools unless they call
  existing authenticated APIs that already allow those changes

Configuration Copy Chapter

One-click install (no configuration required) Copy Section

For a single-user self-hosted instance you do not need to configure anything.
Open Settings → Extensions, pick an extension from the gallery, and click
Install — it just works. The first install creates a WebUI-managed
extension directory under your state dir (STATE_DIR/extensions, e.g.
~/.hermes/webui/extensions/) and installs into it; gallery-installed
extensions load automatically on the next app-shell render with no environment
variables and no restart of your shell.

The managed directory lives alongside your sessions and settings in the
WebUI-owned state dir. That is a different trust domain from "a world-writable
directory on a shared box": only the WebUI process (and whoever can already
write your ~/.hermes state) can place code there. The trust model below still
applies — installed extension code runs with full session authority — so only
install extensions from the vetted gallery or sources you trust as much as the
WebUI source itself.

Some gallery entries need more than WebUI assets. If an extension declares
post-install guidance or lifecycle requirements such as a loopback sidecar or a
native host, Settings -> Extensions shows a Next step note on the card after
install. For example, Desktop Companion can install the WebUI bridge from the
gallery, but the desktop pet is only visible after the local Desktop Companion
app is started.

Manual / advanced configuration (optional) Copy Section

HERMES_WEBUI_EXTENSION_DIR is optional and overrides the managed default.
Set it when you want extensions to live in a specific directory you control
(e.g. a checked-out bundle, or a path mounted into a container). When set it
must point to an existing directory before any script or stylesheet URLs are
injected; WebUI never auto-creates an admin-specified path:

export HERMES_WEBUI_EXTENSION_DIR=/path/to/my-extension/static
export HERMES_WEBUI_EXTENSION_SCRIPT_URLS=/extensions/app.js
export HERMES_WEBUI_EXTENSION_STYLESHEET_URLS=/extensions/app.css
./start.sh

Multiple URLs may be comma-separated:

export HERMES_WEBUI_EXTENSION_SCRIPT_URLS=/extensions/runtime.js,/extensions/app.js
export HERMES_WEBUI_EXTENSION_STYLESHEET_URLS=/extensions/base.css,/extensions/theme.css

For bundled or multi-extension installs, you may list assets in a manifest file
inside HERMES_WEBUI_EXTENSION_DIR instead of maintaining long comma-separated
environment variables:

cat > ~/.hermes/webui-extension-bundle/extensions.json <<'JSON'
{
  "extensions": [
    {
      "id": "templates",
      "scripts": ["templates/templates.js"],
      "stylesheets": ["templates/templates.css"]
    },
    {
      "id": "sidebar-tools",
      "scripts": ["sidebar-tools/sidebar-tools.js"],
      "stylesheets": ["sidebar-tools/sidebar-tools.css"]
    }
  ]
}
JSON

HERMES_WEBUI_EXTENSION_DIR=~/.hermes/webui-extension-bundle \
HERMES_WEBUI_EXTENSION_MANIFEST=extensions.json \
./start.sh

Manifest entries use the same URL safety rules as the environment variables.
Bare relative entries such as templates/templates.js resolve to
/extensions/templates/templates.js; absolute same-origin entries such as
/extensions/shared.js or /static/theme.css are also accepted. A manifest may
be an object with top-level scripts / stylesheets, an object with an
extensions array, or a top-level array of extension objects. Disabled entries
may be kept in the manifest with the JSON boolean "enabled": false. Explicit
HERMES_WEBUI_EXTENSION_SCRIPT_URLS and
HERMES_WEBUI_EXTENSION_STYLESHEET_URLS still work and are appended after
manifest assets, with duplicates ignored.

When an extension is installed from Settings -> Extensions, WebUI records the
installed package and loads that package's manifest.json automatically on the
next app-shell render. In this gallery-installed mode, a manifest located at
HERMES_WEBUI_EXTENSION_DIR/<extension-id>/manifest.json resolves bare relative
assets relative to that package directory. For example,
"scripts": ["assets/companion-adapter.js"] in
desktop-companion/manifest.json injects
/extensions/desktop-companion/assets/companion-adapter.js.

Manual manifests configured with HERMES_WEBUI_EXTENSION_MANIFEST follow the
same rule: relative assets resolve from the manifest file's directory. A root
manifest such as extensions.json keeps the existing
/extensions/<asset-path> behavior, while a subdirectory manifest such as
desktop-companion/manifest.json resolves relative assets under
/extensions/desktop-companion/.

Extension entries may also declare a loopback sidecar for diagnostics and the
opt-in proxy:

{
  "extensions": [
    {
      "id": "desktop-companion",
      "name": "Desktop Companion",
      "scripts": ["companion-adapter.js"],
      "stylesheets": ["companion-adapter.css"],
      "sidecar": {
        "type": "loopback",
        "origin": "http://127.0.0.1:17787",
        "health_path": "/health",
        "proxy_auth": "token-v1"
      }
    }
  ]
}

Loopback sidecars do not change asset injection behavior. They are reported
by diagnostics so an operator can see that a local companion service was
declared and optionally check its health from the browser. If the operator later
approves the proxy in Settings → Extensions, WebUI may proxy requests only
through the fixed per-extension sidecar path for that extension.

Sidecar proxy authentication (`proxy_auth`) Copy Section

The loopback port a sidecar binds is reachable by any local process, and the
proxy strips every inbound credential (cookies, Authorization, CSRF, x-hermes-*)
before forwarding — so a sidecar cannot, on its own, tell a proxied request from a
direct one. The proxy_auth field closes that gap:

• token-v1 (recommended for any sidecar that mutates state) — WebUI mints a
  per-extension secret at STATE_DIR/sidecar-auth/.token (mode 0600) and
  injects it as the X-Hermes-Sidecar-Token header on every proxied request. The
  sidecar resolves the token file in this order — HERMES_EXT_SIDECAR_TOKEN_FILE
  → $HERMES_WEBUI_STATE_DIR/sidecar-auth/.token →
  $HERMES_HOME/webui/sidecar-auth/.token → platform default
  (~/.hermes/webui/…, %LOCALAPPDATA%\hermes\webui\… on Windows) — and must
  validate the header on every route except /health, returning 401 on a
  missing/mismatched token and 503 when the token file is absent/unreadable.
  The canonical scaffold in the extensions repository (examples/, see
  docs/SIDECAR_CONTRACT.md) does all of this for you — do not hand-roll it.
• absent (or the explicit literal "legacy") — legacy mode (no token;
  unchanged behavior). Only appropriate for read-only, non-sensitive sidecars.
• Any other value fails closed (the sidecar declaration is rejected).

Auth-off posture: WebUI authentication is optional and off by default. Because
the consent endpoint and proxy route are unauthenticated in that mode, token-v1
fails closed regardless of whether the sidecar origin is loopback: consent and proxy
resolution return 403 until WebUI authentication is configured. Otherwise, any
caller that can reach WebUI could ask core to inject the token and use it as a
forwarding oracle. The extensions panel exposes the local_unprotected posture so
the operator is told to enable authentication before granting consent. The token
protects against other-UID and sandboxed local callers; it does not defend against
arbitrary same-UID code (which can read the token file, WebUI's own signing key, or
run the sidecar's tool directly).

Extension entries may declare browser-local settings when they also request
extension-owned storage:

{
  "id": "desktop-companion",
  "permissions": {
    "storage": {
      "owned": true
    }
  },
  "settings_schema": [
    {
      "key": "show_badge",
      "type": "boolean",
      "label": "Show badge",
      "default": true
    },
    {
      "key": "mode",
      "type": "enum",
      "label": "Mode",
      "options": [
        {"value": "compact", "label": "Compact"},
        {"value": "full", "label": "Full"}
      ],
      "default": "compact"
    }
  ]
}

Settings are a first-pass browser feature. WebUI sanitizes the manifest schema, injects the accepted schema before extension scripts, and leaves persistence to the browser. The backend does not store extension settings or expose a generic settings write route, and it does not treat these values as secrets.

The sanitizer accepts only boolean, string, number, integer, and enum
fields. It drops sensitive: true fields, unsupported types, malformed enum
options, duplicate keys after the first valid field, and defaults that do not
match the declared type. settings_schema is honored only when
permissions.storage.owned is exactly true.

Extension scripts can use the sanctioned browser accessors:

const settings = window.HermesExtensionSettings.settingsForExtension("desktop-companion");
const value = settings.get("show_badge");
settings.set("show_badge", false);

const storage = window.HermesExtensionSettings.storageForExtension("desktop-companion");
storage.set("lastPanel", "settings");

const sameSettings = window.hermesExt.settings.forExtension("desktop-companion");
const sameStorage = window.hermesExt.storage.forExtension("desktop-companion");

Settings persist only non-default overrides. Resetting settings removes those
overrides and returns schema defaults. Extension-owned storage uses a separate
browser-local namespace, and clearing storage removes that namespace without
changing settings.

Cooperative extension identity Copy Section

An injected extension can claim a stable browser-page identity together with its
existing settings and storage accessors:

const ext = window.hermesExt.register("desktop-companion");
if (ext) {
  ext.settings.set("show_badge", false);
  ext.storage.set("lastPanel", "settings");
}

register(id) trims the ID and succeeds only for an ID in the effective-enabled,
Core-sanitized manifest inventory that was present at the initial page boot. It
returns null for empty, malformed, unknown, or untrusted IDs without creating
settings or storage state. Re-registering the same ID in one page returns the
same handle object; different IDs receive different handles. The handle exposes
only the canonical id, settings, storage, events, and messages fields. Settings and
storage are backed by the same factories used by the legacy accessors.

Manifest enable/disable changes still take effect after a WebUI reload. A handle
already created in the current page may remain cached across a status refresh;
this is expected and does not implement runtime unload. This identity is a
cooperative attribution convenience for extensions sharing the page—not a
sandbox, isolation mechanism, capability or permission system, or security
boundary. Extensions still execute with the full WebUI session authority
described above.

Custom Configure editors Copy Section

Extensions with structured configuration that does not fit scalar
settings_schema fields can register one custom editor entry point on their
scoped E0 settings handle:

const ext = window.hermesExt?.register?.("dictionary-manager");
const unregister = ext?.settings?.registerConfigure?.(({ opener, restoreFocus }) => {
  openDictionaryManager({ opener, restoreFocus });
});

registerConfigure(handler) is available only through a valid boot-trusted E0
handle. It does not require settings_schema or extension-owned storage. The
first handler registered for an extension wins; duplicates return null and do
not replace it. A successful registration returns an idempotent unregister
function.

Core shows one Configure button only for the extension's current
effective-enabled row under Settings → Extensions → Installed. Diagnostics
never shows the button. Late registration updates an already-mounted Installed
row. Disable or uninstall status removes the entry point immediately; uninstall
followed by a same-ID reinstall cannot revive the old page-local handler until a
full WebUI reload injects and registers the new extension script.

Core enters a pending state before invoking the handler and passes the activated
button as opener plus a one-shot restoreFocus() callback. The extension owns
its dialog, validation, persistence, and close lifecycle. It must either call
restoreFocus() when its UI closes or return a thenable whose settlement means
the Configure UI is closed. Both paths end pending and converge on Core's
one-shot focus restoration. A synchronous non-thenable handler remains disabled
while unsettled. If it never calls restoreFocus(), it remains disabled until reload.
Core does not guess dialog lifetime with a timeout.

Synchronous throws, thenable-access failures, and asynchronous rejections are
isolated, logged with the extension ID, and surfaced as a generic failure. Focus
returns to the connected opener when possible, otherwise to the current visible
Configure button or the Installed tab without forcing navigation. The hook does
not let an extension return DOM for Core to render, add a backend settings route,
or change the trusted same-origin extension model.

Message actions Copy Section

Extensions can register a small, Core-rendered action on settled user and
assistant messages without querying or rewriting private transcript DOM:

const ext = window.hermesExt?.register?.("message-pins");
const unregister = ext?.messages?.registerAction?.({
  id: "pin",
  label: "Toggle pin",
  icon: "pin",
  roles: ["user", "assistant"],
  getPressed({ sessionId, messageIndex, role }) {
    return isPinned(sessionId, messageIndex, role);
  },
  onInvoke({ sessionId, messageIndex, role, text }) {
    togglePin({ sessionId, messageIndex, role, text });
  },
});

registerAction(descriptor) is available only through a valid boot-trusted E0
handle. It does not add a manifest permission or sandbox boundary. A descriptor
requires a stable ID ([A-Za-z][A-Za-z0-9._-]{0,63}), a plain-text label of at
most 120 characters, a Core-owned icon token (pin, bookmark, or star), and
an onInvoke function. roles is an optional non-empty subset of user and
assistant and defaults to both. Malformed descriptors, duplicate
extensionId:actionId identities, and registrations beyond the page-wide V1
limit of two return null. A successful registration returns an idempotent
unregister function, and unregistering releases its slot.

If extension-owned state changes somewhere other than the registered action
(for example, a pin is removed from an extension-owned header popover), call
ext.messages.invalidateActions(). Core then discards transcript HTML caches
and re-evaluates that extension's visible getPressed presentations. The call
returns true when the extension has an active message-action registration and
false otherwise.

Core places accepted actions after the built-in message controls in registration
order. It renders them only on visible, settled user/assistant message rows—not
live partial output, hidden worklog/anchor content, process-wakeup notices, tool
rows, or other surfaces. Core also reconciles late registration, rerender,
session-cache restore, pagination/virtualization, unregister, effective disable,
and uninstall. Uninstall quarantines the page-local identity until a full reload.

The optional getPressed callback is synchronous and receives a frozen
{ sessionId, messageIndex, role } object with no text. Only a strict true
sets aria-pressed="true"; a false value, exception, thenable, or thenable-access
failure is treated as unpressed without breaking transcript rendering.

On a user click, Core resolves the row again and passes onInvoke a frozen
{ sessionId, messageIndex, role, text } snapshot. messageIndex is the
absolute index in the current persisted session message list, including the
pagination offset. It is stable when older history is prepended, but it is not a
durable ID across edit, regenerate, or truncate operations. text is the
Core-normalized visible plain text used by that row's Copy/TTS surface—not
rendered HTML, hidden reasoning, the complete provider payload, or a
transcript-wide read. It is an empty string when an otherwise eligible settled
row has visible attachments or media but no plain text.

A thenable returned by onInvoke controls pending state. Repeated clicks on the
same extension/action/session/message target are suppressed while it is pending;
different targets may run concurrently. Throws, thenable-access failures, and
rejections from the current invocation are isolated and surfaced as a generic
failure. Once an invocation has settled, or its action is unregistered or
uninstalled, late callbacks cannot report a failure, refresh actions, clear a
replacement invocation's pending state, or restore stale focus. Core preserves
and restores the connected opener when possible after settlement. There is no Core
timeout, message/session mutation API, arbitrary row markup, extension-controlled
ordering, or overflow menu in V1.

Turn lifecycle events Copy Section

A registered extension can react when a session turn observed by the current page
starts or reaches a terminal state:

const ext = window.hermesExt.register("desktop-companion");
const stop = ext && ext.events.on("turn:complete", event => {
  console.log(event.sessionId, event.streamId, event.status);
});

// Remove the listener when the extension no longer needs it.
if (stop) stop();

The supported event types are turn:start, turn:complete, turn:error, and
turn:cancel. The frozen event object always contains type, sessionId,
streamId, and timestamp (Unix seconds). Start events also contain
startedAt; terminal events contain endedAt and may contain status.
events.on(type, handler) returns an idempotent unsubscribe function, or null
for an unsupported type or non-function handler. An exception in one extension
listener is logged and does not prevent other listeners or the chat UI from
continuing.

The version-1 mapping is deliberately small: attaching a confirmed live session
stream emits turn:start; SSE done emits turn:complete; SSE cancel and
application errors classified as cancelled or interrupted emit
turn:cancel; other application errors and an unrecoverable live-stream
connection failure emit turn:error. Transport-only stream_end does not emit
a second terminal event.

Core suppresses reconnect duplicates so a recently observed
sessionId/streamId pair produces at most one start event and one terminal
event. sessionId is the owner of the original stream; server-side compression
or session rotation at completion does not change that lifecycle identity.
Terminal callbacks run after Core has cleared the original stream ownership,
applied the current session's immediate terminal transcript projection, and
returned the owned pane to its idle state. They do not wait for unrelated
follow-up work such as notifications, queued turns, or optional recovery
refreshes.

This is a page-local, live-stream notification surface. It does not replay
history, report turns that finish without this page observing their stream, or
provide token, tool, approval, or metrics events. It follows the same cooperative
trust model as register(id) and adds no sandbox or permission boundary. A
durable or global agent event stream is a separate Core contract. Ephemeral
/btw answer streams are not included in this version.

URL rules Copy Chapter

Injected asset URLs are deliberately restricted:

• must be same-origin paths
• must start with /extensions/ or /static/ after manifest normalization
• must not include a URL scheme, host, fragment, quote, angle bracket, newline,
  NUL byte, or backslash
• must not contain dot-segments or dotfiles after percent-decoding

Allowed examples:

/extensions/app.js
/extensions/app.css
/extensions/app.js?v=1
/static/theme.css

Rejected examples:

https://example.com/app.js
//example.com/app.js
javascript:alert(1)
/api/session
/extensions/app.js#fragment

These restrictions keep the existing Content Security Policy intact and avoid
turning the extension hook into a third-party script loader. Invalid configured
URLs are ignored rather than injected.

Trusted local sidecars Copy Chapter

Manifest-bundled extensions may integrate with a trusted local sidecar process,
such as a desktop companion listening on http://127.0.0.1:17787. The injected
extension JavaScript can talk to that sidecar directly from the browser, and
WebUI diagnostics still use that direct browser path. WebUI may also proxy the
same sidecar through a fixed per-extension sidecar path after explicit persisted
user consent. WebUI does not create arbitrary extension-owned backend routes.

Loopback sidecar origins are already included in WebUI's enforced CSP
connect-src directive:

http://127.0.0.1:*
http://localhost:*
http://ipc.localhost
ws://127.0.0.1:*
ws://localhost:*

The wildcard ports above cover any loopback port, including
http://127.0.0.1:17787. For a trusted non-loopback origin that you explicitly
control, append the exact origin with HERMES_WEBUI_CSP_CONNECT_EXTRA before
starting WebUI:

HERMES_WEBUI_CSP_CONNECT_EXTRA=https://companion.example.internal HERMES_WEBUI_EXTENSION_DIR=/path/to/my-extension/static HERMES_WEBUI_EXTENSION_MANIFEST=extensions.json ./start.sh

HERMES_WEBUI_CSP_CONNECT_EXTRA accepts space-separated http(s):// or
ws(s):// origins only. It rejects paths, directive injection, and invalid port
numbers. Avoid wildcard or remote origins unless you fully control the target;
extension JavaScript runs with the logged-in WebUI session's authority.

Loopback sidecar declarations Copy Chapter

Sidecar declarations are sanitized before they appear in diagnostics:

• only "type": "loopback" is supported
• origin must be an http or https origin on 127.0.0.1, localhost, or
  [::1]
• origin must not include a username, password, path, query string, or fragment
• health_path is optional and defaults to /health
• when present, health_path must start with / and must not contain a scheme,
  host, query string, fragment, quotes, control characters, backslashes, empty
  segments, whitespace, or path traversal

Invalid sidecars are skipped with a stable warning code such as
sidecar_origin_rejected, sidecar_type_unsupported,
sidecar_health_path_rejected, or sidecar_invalid. Raw rejected origins and
paths are never returned by the status endpoint. If health_path is omitted,
diagnostics use /health; if health_path is present but invalid, the sidecar is
skipped rather than probed.

Remote images (`img-src`) Copy Chapter

The default policy allows images only from the WebUI itself plus data: and
blob:. Remote https: images are blocked so that a model reply cannot make
the browser contact an arbitrary server just by rendering (#7941). In chat a
blocked remote image shows as an "Open image · host" link instead. An extension
page that loads images from another origin needs the operator to allow it:

# space-separated http(s) origins; optional *. subdomain wildcard and port.
export HERMES_WEBUI_CSP_IMG_EXTRA="https://images.example.com https://*.cdn.example.com"

The bare scheme https: restores the old allow-everything behaviour. The
same validation rules as HERMES_WEBUI_CSP_FRAME_EXTRA below apply, and the
allowlist also covers images inside chat replies and public share pages.

Embedding an external web app in an iframe Copy Chapter

By default the WebUI's Content-Security-Policy only allows it to embed
same-origin content in an `` (the frame-src directive falls back to
'self'). An extension that wants to pin an external self-hosted web app — a
Grafana board, Vaultwarden, a personal dashboard — as a tab therefore needs the
operator to widen frame-src, opt-in, via an environment variable:

# space-separated http(s) origins; optional *. subdomain wildcard and port.
export HERMES_WEBUI_CSP_FRAME_EXTRA="https://grafana.example.com https://*.dash.example.com:8443"

Rules and guarantees:

• Only http(s) origins are accepted (an iframe src is always http(s)).
  Entries may include a *. subdomain wildcard and a port or * port; a path,
  a ws:///wss:// scheme, an invalid port, or any attempt to inject another
  directive is rejected and the whole value is ignored (with a logged warning).
• This mirrors the existing HERMES_WEBUI_CSP_CONNECT_EXTRA knob (which widens
  connect-src for fetch/WebSocket); the two are independent.
• It only governs what the WebUI page may embed. It does not touch
  frame-ancestors, which stays 'none' — so widening frame-src never lets
  another site embed the WebUI itself.
• Default-off: with the variable unset, the policy is unchanged (same-origin
  iframes only).

An "external app tab" extension should document the exact origin(s) it needs so
the operator can set this knob deliberately, rather than assuming a wide-open
policy.

Static file serving Copy Chapter

When HERMES_WEBUI_EXTENSION_DIR points at an existing directory, files under
that directory are available below /extensions/:

/path/to/my-extension/static/app.js  ->  /extensions/app.js
/path/to/my-extension/static/ui.css  ->  /extensions/ui.css

The static handler is sandboxed:

• path traversal is rejected, including encoded traversal
• dotfiles and dot-directories are not served
• symlinks that resolve outside the extension directory are rejected
• missing or invalid extension directories behave as disabled
• manifest paths must be relative files inside the configured extension directory
• malformed, missing, or oversized manifests are ignored without enabling unsafe URLs
• failures return a generic 404 without exposing local filesystem paths

Security notes Copy Chapter

Only enable extensions from directories you control. Extension JavaScript runs in
the WebUI origin and can call the same authenticated WebUI APIs as the logged-in
browser session.

For shared or remotely exposed installations:

• keep HERMES_WEBUI_PASSWORD enabled
• bind to loopback unless you intentionally expose the service
• review extension code before enabling it
• prefer small, auditable extension files
• avoid serving generated or user-writable directories as extension roots

Registering a custom theme (skin) Copy Chapter

Extensions can contribute a custom skin that appears in the native
Settings → Appearance skin picker, instead of bolting on a parallel theme
switcher. Call window.registerHermesSkin(descriptor) from your extension
script:

window.registerHermesSkin({
  name: 'E-Ink',            // display name (also the picker label)
  value: 'e-ink',           // optional stable key; slugified from name if omitted
  label: 'E-Ink',           // optional explicit picker label
  scheme: 'light',          // optional: force a light or dark base while selected
  colors: ['#000000', '#ffffff', '#555555'],  // up to 3 preview swatches
  tokens: {                 // CSS design-token overrides for this skin
    '--bg': '#ffffff',
    '--surface': '#ffffff',
    '--text': '#000000',
    '--accent': '#000000',
    '--border': '#000000'
    // ...any of the allowed tokens below
  }
});

The call returns true on success and false if the descriptor was rejected
(so an extension can detect and log a bad theme). Once registered, the skin
shows up in the picker, can be selected, and persists across reloads exactly
like a built-in skin. Registering the same key again updates it in place
(idempotent), which is what a live theme editor relies on while the user edits.

Use scheme when a skin is light-only or dark-only. Accepted values are
"light" and "dark"; any other value is ignored. This does not rewrite the
user's saved Theme setting (Light, Dark, or System Default). It only
controls the effective base theme class while that extension skin is selected,
so a dark editor skin is not mixed with light-mode code/table tokens, and a
light E-Ink skin is not mixed with dark-mode tokens.

Core does the security-sensitive work for you. Because token values are
written into CSS, every value is sanitized in core, once, so every theme
extension inherits the guard:

• Allowed token names (anything else is dropped): --bg, --surface,
  --surface2, --surface-subtle, --text, --text2, --muted, --accent,
  --accent2, --accent3, --accent-contrast, --accent-hover,
  --accent-text, --accent-bg, --accent-bg-strong, --accent-rgb,
  --border, --border2, --hover-bg, --code-bg, --code-text,
  --sidebar, --sidebar-text, --user-bubble, --assistant-bubble,
  --success, --warning, --danger, --info, --link.
• Allowed value shapes (anything else is dropped): hex colors, rgb() /
  rgba(), hsl() / hsla(), CSS color keywords, simple numeric-with-unit
  values (px/em/rem/%), and a bare RGB triple (e.g. 0, 0, 0 for
  --accent-rgb, which the app consumes inside rgba(...)). Values containing
  url(), expression(), semicolons, braces, or other CSS-injection vectors
  are rejected.
• Reserved keys are protected — an extension cannot overwrite a built-in
  skin key (e.g. default, ares, graphite).
• A descriptor with no valid tokens after sanitization is rejected entirely.
• Skin scheme is constrained — only light and dark are accepted. Invalid
  scheme values are ignored rather than rendered into CSS.

This is the supported, forward-looking way for theme-pack and theme-creator
extensions to integrate with the built-in appearance system.

Registering a custom TTS engine Copy Chapter

Extensions can contribute a text-to-speech engine that appears in the
Settings → TTS Engine dropdown alongside the built-ins (Browser / Edge /
ElevenLabs) and is used by both playback paths — the hands-free voice-mode
auto-read and the per-message "Listen" button. Call
window.registerHermesTtsEngine(descriptor):

window.registerHermesTtsEngine({
  id: 'voicevox',                 // [a-z0-9_-], not a built-in
  label: 'VOICEVOX (local)',      // shown in the dropdown (textContent — escaped)
  // synthesize(text, opts) -> Promise<ArrayBuffer | Blob | TypedArray> of audio.
  // opts carries the user's saved { voice, rate, pitch } (engine may ignore).
  synthesize(text, opts) {
    return fetch('http://127.0.0.1:50021/...', { /* ... */ })
      .then(r => r.arrayBuffer());
  }
});  // -> true on success, false if rejected

Rules and guarantees:

• id must be slug-safe ([a-z0-9][a-z0-9_-]{0,31}) and may not shadow a
  built-in engine (browser, edge, elevenlabs) — those are reserved.
• label is inserted with textContent, never innerHTML (no markup
  injection into the dropdown).
• synthesize must return audio bytes (ArrayBuffer, Blob, or a typed array);
  core coerces to an ArrayBuffer and plays it through the same <audio>
  lifecycle as the Edge engine (including stop/rearm in voice mode). A rejected
  promise or empty/invalid result fails gracefully (toast on the Listen button;
  re-listen in voice mode).
• Core owns selection, the dropdown option, and playback; the extension only
  produces audio. Re-registering the same id updates it in place.
• Network note: if your engine calls a local server (e.g. VOICEVOX on
  http://127.0.0.1:50021), that request is a same-origin-policy / CSP
  connect-src concern like any extension network call — loopback is already in
  the default connect-src. Declare permissions.network_external honestly
  based on where it calls.

Extension authoring guidance Copy Chapter

Extensions share the page with the WebUI app, so they should be additive and
reversible. Prefer small, well-scoped DOM changes that can be removed or hidden
without breaking the built-in Chat, Tasks, Settings, or session views.

Recommended patterns:

• create extension-specific containers with unique IDs or class prefixes
• add UI next to existing views instead of replacing large app containers
• keep event listeners scoped to extension-owned elements where possible
• preserve built-in navigation behavior and restore any view state you change
• use hidden, aria-*, and extension-scoped CSS for panels or overlays
• guard initialization so reloading or re-injecting the script does not create
  duplicate buttons, panels, timers, or event listeners

Avoid destructive mutations such as replacing document.body.innerHTML,
main.innerHTML, or other broad WebUI containers. Those patterns can remove or
mask the app's existing panels and leave normal navigation unable to recover
after an extension view is opened.

For custom pages, prefer adding a dedicated panel and toggling it alongside the
built-in views:

(() => {
  if (document.getElementById('my-extension-panel')) return;

  const panel = document.createElement('section');
  panel.id = 'my-extension-panel';
  panel.className = 'main-view my-extension-panel';
  panel.hidden = true;
  panel.textContent = 'My extension page';

  document.querySelector('main')?.appendChild(panel);

  function showPanel() {
    document.querySelectorAll('main > .main-view').forEach((view) => {
      view.hidden = view !== panel;
    });
  }

  // Wire showPanel() to an extension-owned button or menu item.
})();

If host CSS overrides [hidden], add an extension-scoped rule such as:

.my-extension-panel[hidden] {
  display: none !important;
}

Contributing to the extension library Copy Section

To publish an extension in the vetted gallery, open a PR against
hermes-webui/hermes-webui-extensions
following docs/extension-entry.md
(entry layout, extension.json/manifest.json shape, and the capability +
best-practice conventions). Every entry PR runs the repo's CI validators and
safety scan before it can merge, and merged entries are published to the registry
that powers Settings → Extensions.

Minimal example Copy Chapter

Create a local extension directory:

mkdir -p ~/.hermes/webui-extension
cat > ~/.hermes/webui-extension/app.css <<'CSS'
.my-extension-badge {
  position: fixed;
  right: 12px;
  bottom: 12px;
  padding: 6px 10px;
  border-radius: 999px;
  background: #202236;
  color: #fff;
  font: 12px system-ui, sans-serif;
  z-index: 9999;
}
CSS
cat > ~/.hermes/webui-extension/app.js <<'JS'
(() => {
  const badge = document.createElement('div');
  badge.className = 'my-extension-badge';
  badge.textContent = 'Extension loaded';
  document.body.appendChild(badge);
})();
JS

Start WebUI with the extension enabled:

HERMES_WEBUI_EXTENSION_DIR=~/.hermes/webui-extension \
HERMES_WEBUI_EXTENSION_STYLESHEET_URLS=/extensions/app.css \
HERMES_WEBUI_EXTENSION_SCRIPT_URLS=/extensions/app.js \
./start.sh

Open the WebUI and confirm the badge appears.

Diagnostics Copy Chapter

Authenticated administrators can inspect sanitized extension configuration at:

GET /api/extensions/status

The status endpoint is read-only and follows the normal WebUI authentication
rules. The same sanitized diagnostics are also shown in Settings → Extensions
for operators who prefer to inspect extension state from the browser. Installed
manifest entries can be enabled or disabled from that panel through the
authenticated POST /api/extensions/toggle endpoint. The toggle writes only a
WebUI-managed override in the WebUI state directory; it does not edit extension
manifests, fetch new extension assets, uninstall files, or add extension-owned
backend routes. Manifest entries with "enabled": false remain
manifest-disabled and cannot be re-enabled from WebUI.

The diagnostics return the same public asset URLs that can already be injected
into the HTML, plus coarse manifest status, per-extension effective state, asset
counts, sanitized declared loopback sidecars, and warning codes for rejected or
unavailable configuration. manifest.script_count and
manifest.stylesheet_count count accepted assets from the effectively enabled
manifest entries only; manifest.sidecar_count counts accepted enabled loopback
sidecars from the manifest. counts.script_urls and counts.stylesheet_urls
count the final post-env-merge URLs, while counts.sidecars counts the sanitized
sidecar list returned in sidecars. counts.manifest_extensions counts
sanitized manifest extension entries with valid IDs, and counts.user_disabled
counts installed manifest entries currently suppressed by the WebUI-managed
override. manifest.entry_count counts the loaded top-level manifest object and
effectively enabled extension entries that were inspected for injection, not
every extension object in the file. The endpoint and Settings panel do not
return HERMES_WEBUI_EXTENSION_DIR, resolved manifest paths, raw environment
values, rejected URL strings, rejected sidecar origins, rejected health paths, or
the override state-file path.

When sanitized loopback sidecars are present, Settings → Extensions renders a sidecar monitor card. The browser checks each declared health_url directly with fetch(..., { credentials: 'omit', cache: 'no-store' }) and a short timeout. A successful HTTP response is shown as healthy, a non-OK HTTP response as unhealthy, and CORS/network/timeouts as unreachable or blocked; raw health response bodies are never rendered. If a healthy response includes an optional top-level runtime object, the panel may parse it and render only allowlisted scalar fields such as sidecar, native_host, bridge, last_seen_at, and webui_origin. This keeps sidecar-specific diagnostics machine-readable without making WebUI depend on any one extension's private payload shape.

The same card also exposes proxy consent through POST /api/extensions/sidecar-proxy-consent and reports the fixed per-extension sidecar path /api/extensions/<extension-id>/sidecar/<relative-path>. WebUI strips Cookie, Authorization, and CSRF headers before contacting the sidecar, and sidecar Set-Cookie headers are stripped before the browser sees the response. WebUI does not create arbitrary extension-owned backend routes; the proxy surface stays on that fixed per-extension sidecar path.

When sanitized settings are present, Settings -> Extensions renders
browser-local controls for installed manifest entries. Save, reset, and clear
storage actions call window.HermesExtensionSettings; they do not call backend
storage routes and do not write WebUI settings.

GUIDELINES (`docs/GUIDELINES.md`) Copy Section

Change guidelines — writing a PR that lands cleanly

Hermes WebUI is deliberately simple: Python on the server, vanilla JS in the browser, no build
step. That simplicity only survives if every change is scoped, verified, and complete. This
document is the distilled set of principles that make the difference between a PR that merges on the
first review and one that needs several rounds of back-and-forth. It applies to human and
AI-assisted contributions alike — but it is written especially for AI coding agents, because the
mistakes below are the ones they make most often and most confidently.

If you read nothing else, read the four root causes. The ten rules are just their enforcement.

The four root causes of a change that has to be redone Copy Chapter

Almost every change that fails review fails for one of these reasons. Learn to catch them in your
own work before you open the PR.

1. Fixing the instance instead of the class. The single most common one. A bug usually has
   more than one home — the same mistake lives at several call sites, across more than one backend
   or code path, in a companion endpoint, in a second layout, on more than one lifecycle exit. It's
   easy to fix the exact line the report points at and leave the siblings broken. The missed one is
   usually a different dimension than the one you were looking at (a second backend, an unusual
   layout, the cancel path, the multi-item case).

2. Mistaking a proxy for proof. "The test passes," "the code contains the string," "that branch
   ran," "I mocked it and it returned the right thing" — none of these prove the user-visible
   behavior is correct. A test that would still pass if you reverted the fix is testing nothing.

3. Reasoning about a value's content but not its lifetime. You get the value right but miss when
   it goes stale, who is responsible for cleaning it up, and what happens to it on every exit path
   (success, error, cancel, replace, shrink, concurrent access). Leaked resources, orphaned caches,
   stale reads, and "the decision used one value but the action used another" all live here.

4. Letting the diff grow past the task. Extra changes you weren't asked for, or re-implementing
   something the codebase already centralizes (a fallback, a shared helper, an extension point).
   Every extra line is a new risk surface and makes the change harder to review and to trust.

A fifth applies only to visible changes: placing a control where the code is, not where the
user's attention should go.

The ten rules Copy Chapter

1. Fix the class, not the instance. Copy Section

Before writing the fix, search for every sibling — other call sites, producers and consumers,
alternate backends, companion endpoints, other layouts, every lifecycle exit — and fix at the
shared chokepoint. If you deliberately leave one out of scope, name it in the PR and say why.
One guard in the shared function is a smaller and more correct change than one guard per caller.
The chokepoint is the smallest boundary that contains the fault, not the widest one you can
reach: fixing the class means guarding every sibling of the bug, not disabling a whole stage or
pipeline to suppress one bad output. If your fix blocks more than the fault occupies, it has grown
past the task (rule 9).

2. Trace one authoritative value end-to-end. Copy Section

Follow the value from input → normalize → decision → action → persist → cleanup, and use the
same resolved value at every stage. Don't let the code that decides see one value while the
code that acts uses the stale or un-normalized one — that split is a silent correctness bug.
Before you key a decision on a value, confirm it's authoritative: written at the point of intent
(a canonical kind field, a provenance marker stamped by the action itself, a recorded origin) — not
inferred from an id prefix, content shape, emptiness, or DOM state. Search for an existing canonical
field first; inference that happens to work on the case in front of you is the most common way a
guard misfires on a sibling. If no authoritative field exists, add a test with an adjacent case that
matches your heuristic and must not trigger.

3. When you can't confirm something, fail closed and say so. Copy Section

For anything touching authority, capability, identity, or containment: if you cannot confirm it's
safe, deny it — don't take the permissive branch on uncertainty, and never report a failure as a
success. Treat "unknown", "absent", and "unverifiable" as distinct from "allowed." Stating "I could
not verify X" in the PR is good engineering; hiding it is how a security or reliability bug ships.

4. Enumerate the state-space before you edit. Copy Section

Write down which dimensions the change touches — entry point, backend, item count (0 / 1 / many /
duplicate), lifecycle exit (success / error / cancel / replace / shrink / teardown), auth on vs off,
concurrency (two profiles or workers at once), input shape (empty / hostile / aliased) — and cover
each, or mark it out of scope on purpose. Most redo rounds are one un-considered dimension. Those
axes are generic; the ones that actually bite are subsystem-specific and are not obvious to a
first-time contributor. Before editing an unfamiliar subsystem, find its real variants: read the
closed PRs and review threads that touched the same code, where the discriminating dimensions
(every session-lineage kind, every replay/recovery source, each stream response shape) were already
enumerated. Reuse that list rather than inventing your own from the one case you were handed.

5. Assume inputs and check-then-use gaps are adversarial. Copy Section

Input crossing a trust boundary can be crafted to break a naive check (odd delimiters, casing, YAML
aliases, path traversal). Filesystem and process state can change between the moment you check it
and the moment you use it, so validate at the point of use (hold a file descriptor/handle rather
than re-resolving a path). Scope caches by their complete identity or they leak across
profiles/sessions under concurrency. Validation is worthless if the thing you finally use isn't the
thing you validated.

6. A test must fail before your fix and pass after it. Copy Section

Run your new test against the current code first and confirm it fails for the right reason; only
then apply the fix. Assert the observable behavior (the row updates, the secret is absent from
the log, the request carries the right value) — not a source string, and not through a mock that
stands in for the very thing under test. If the bug is about picking the right one of several items,
the test must include several items, or it can't catch picking the wrong one. When the issue ships a
reproduction — a session capture, a script, exact steps, an attachment — your test loads that,
not a fixture you rebuilt from your reading of it. A fix and a test written from the same wrong model
of the bug will base-fail and head-pass on the fixture forever while the real symptom sits untouched;
loading the reporter's actual scene is what breaks that agreement. A reproduction is whatever pins
the bug's shape — a downloadable capture, but a fenced JSON structure, the field-level trigger
conditions, or exact steps bind it just as tightly. Bind your fixture to that shape: satisfy every
condition it names and let the assertion fail when any one is violated, instead of granting the
fixture a property the report never had so a guard will fire. Reconstruct the shape yourself only
when the issue genuinely leaves it unpinned — and then say so, and say what you assumed.

7. Name the owner of every piece of state and prove it's released. Copy Section

For each resource or mutation you introduce (a cache entry, a lock, a temporary env change, a
loading flag, a DOM node, a pending-map entry), show it is cleaned up or invalidated on every
exit — success, error, cancellation, replacement, shrink/clear, and teardown — not just the happy
path. Happy-path testing structurally cannot see these leaks.

8. Fallbacks and defaults are contracts — extend the mechanism, don't copy it. Copy Section

If your change means editing several parallel blocks identically, stop: the codebase almost
certainly has a mechanism for this (a fallback, a shared helper, an extension point) and you've
missed it. Add to the one canonical place. For example, new user-facing copy goes in the en locale
and rides the existing fallback — don't paste English into every locale block.

9. The diff is the task and nothing else. Copy Section

Change exactly what the task requires. Anything else you noticed goes in the PR description as a
note, not into the diff. Before opening the PR, run the affected tests and a broader sweep of
neighboring tests (not only the ones you added), and remove every unrelated change.

10. A visible control costs attention on every future visit — place it accordingly. Copy Section

Where a control lives should be decided by how often it's used and by where mainstream chat apps put
the equivalent — not by where your diff already is. Rare per-item actions belong in an overflow/⋮
menu; global or data actions belong in Settings; only genuinely daily-use controls earn a spot on a
hot surface like the composer. Then verify it visually: capture desktop and narrow-viewport,
before and after, and confirm nothing is clipped, no overflow-collapse is tripped, and no hover-only
affordance is stranded on touch.

Show your work in the PR description Copy Chapter

The fastest review is one where the reviewer can see that the above is handled instead of having
to discover the gaps. Make your PR description carry the evidence:

• The siblings you found for rule 1/4 — and any you deliberately left out of scope.
• Proof the test bites — that your new test failed before the fix.
• Verification run — the affected + neighboring tests, not just your new ones.
• Before/after images for any visible change (desktop + narrow).
• What you could not verify — an explicit list. An admitted gap is fine; a hidden one is a bug
  waiting to be found in review.
• Who owns the truth for any claim the repo doesn't — browser behavior, a provider's API, a
  registry, an OS convention. Name the owner and check your proof is one they'd accept: in-page
  automation proves page behavior, not that the browser didn't swallow the event first; a mock
  proves your intent, not the provider's contract; a synthetic fixture proves nothing about the live
  system. The failure mode here isn't knowing you couldn't verify — it's thinking you did.

Following this imperfectly still helps enormously, because the reviewer can see exactly where your
coverage stops instead of finding it the hard way.

Companion to AGENTS.md, CONTRIBUTING.md, and
docs/CONTRACTS.md. For UI/UX specifics see docs/UIUX-GUIDE.md
and DESIGN.md.

ISSUES (`docs/ISSUES.md`) Copy Section

Upstream Issues — Root Cause Analysis

#1256: Browser tools fail with "Playwright not installed" Copy Chapter

Root Cause Copy Section

The check lives in hermes-agent (upstream), not hermes-webui:

hermes-agent/tools/browser_tool.py → check_browser_requirements()

check_browser_requirements() does not recognize CDP (Chrome DevTools Protocol) mode — it only looks for a local Playwright/Puppeteer install. When the agent runs in CDP mode (connecting to an existing browser), the check still fails.

WebUI side Copy Section

The WebUI already passes CLI_TOOLSETS correctly per-request. The enabled_toolsets field in the cron/chat config is dynamic and works as intended.

Fix required Copy Section

The fix must happen in hermes-agent/tools/browser_tool.py:

• check_browser_requirements() should skip the Playwright check when CDP mode is configured
• Or add a BROWSER_MODE=cdp env var that bypasses the local browser requirement

Workaround Copy Section

Use CLOUD_BROWSER=true or configure browser.base_url to point to a remote CDP endpoint. This bypasses the local Playwright requirement.

UIUX GUIDE (`docs/UIUX-GUIDE.md`) Copy Section

UI/UX Guide

This document summarizes UI/UX principles that are already visible in the
repository. It is a contributor guide, not a new design proposal. Source
documents include DESIGN.md, README.md,
THEMES.md, docs/ui-ux/index.html,
docs/ui-ux/two-stage-proposal.html, and
design comments in static/style.css.

Use this guide when a change touches layout, chat rendering, composer chrome,
navigation, theme/skin behavior, responsive behavior, or visual hierarchy. For
purely backend changes, use the runtime/state contracts instead.

Product shape Copy Chapter

Hermes WebUI is a browser workbench for Hermes Agent with near-CLI parity and a
simple implementation shape: Python on the server, vanilla JavaScript in the
browser, no build step, no bundler, and no frontend framework.

The primary layout is three-panel:

• left sidebar for sessions and navigation,
• center panel for chat,
• right panel for workspace file browsing and previews.

Model, profile, workspace, attachments, voice input, context usage, Stop, and
Send controls live in the composer footer. Settings and session-level tools live
in the Hermes Control Center. Preserve this shape unless the change explicitly
justifies a different interaction model.

Core feeling: calm developer console Copy Chapter

The main artifact is the conversation. Tool calls, thinking traces, context
compaction records, token usage, runtime status, and other internals are useful,
but they are transcript metadata. They should sit below user and assistant prose
in visual priority.

Prefer:

• quiet surfaces,
• clear spacing,
• restrained accent use,
• progressive disclosure for debugging detail,
• legible text over decorative chrome.

Avoid turning the interface into a demo page of colorful cards. Errors,
approvals, and other action-required states may be prominent because the user
must notice and respond to them.

Conversation hierarchy Copy Chapter

A chat turn should read as one coherent story:

1. User message: right-aligned, compact bubble.
2. Assistant content: left-aligned, prose-first, not a heavy bubble.
3. Tool, thinking, progress, and context traces: quiet disclosure rows inside or
   adjacent to the assistant turn.
4. Raw logs and verbose details: hidden until explicitly expanded.

Do not render every internal event as a first-class chat card. A turn that used
many tools should summarize the work as inspectable activity, not make the user
read a stack of unrelated-looking cards.

Tool, thinking, and activity traces Copy Chapter

Tool cards are debug event rows, not chat messages. Show the icon, name, short
target or preview, and status first. Arguments, result snippets, and long logs
belong behind expansion, with result snippets truncated and full output behind a
show-more affordance where needed.

Thinking and context cards should share the quiet metadata visual family. They
should not overpower assistant prose. Collapsed activity summaries should be
terse, for example Activity: 4 tools, and should not duplicate the thinking
area, list every tool name in the summary, or add redundant trailing count
badges.

Visible interim assistant progress is part of the live conversation timeline,
not raw debug detail. Compact Activity may collapse tool arguments, long tool
results, and low-level reasoning detail, but it must not make concise
user-visible progress text available only inside a collapsed disclosure.

A live Thinking card follows its own tail while reasoning streams: new text
scrolls into view when the card is open at its bottom, exactly like the message
pane. Scrolling up inside the card holds the reader's place (follow resumes on
returning to the bottom), and collapsing the card mid-stream pauses the inner
follow — expanding again restores it. Settled history cards never auto-scroll;
they open at the top like any other persisted content, and opening one must not
give it follow state: a persisted card that acquired a latch would chase its own
tail on any later re-render, such as a 1280px-to-390px reflow.

Opening a card is a transition, not an instant: the body animates from zero
height, so its position only becomes meaningful once max-height finishes
(opacity ends earlier and means nothing here). While that animation runs the
card is "settling" — no follow state is seeded and no streaming delta may move
it, so a reader who opens a long card and scrolls up is never yanked to the
bottom by text arriving mid-animation. A card closed again before the animation
ends stays unbound and re-measures on the next open.

Follow intent survives rebuilds in both directions: a collapsed following card
carries its latch across a scene-update rebuild and resumes follow when reopened
(never re-measured at its top and put on hold), and a rebuild that interrupts a
card's very first open lets the replacement body finish the open — it seeds
follow state from its real position instead of staying follow-less.

Automatic compression is a live-only context barrier, not a special branded
tool card. Render it as a centered, non-interactive divider with quiet horizontal
rules: Compressing context while the compression barrier is active and
Context auto-compressed when the agent has continued or the compression
completion event arrives. Do not give it a caret, click target, leading status
dot, or standalone running badge. In settled final history, remove live-only
automatic compression rows unless they explain a visible recovery or error
state.

The existing two-stage proposal in docs/ui-ux/two-stage-proposal.html records a
compatible direction for long turns: live work can be grouped as a worklog, then
settled history can collapse while the final answer reads as the calm
conclusion. Treat that page as an existing proposal, not as shipped behavior
unless the code and tests prove it is implemented.

Typography and content Copy Chapter

Use three explicit font tokens:

• --font-ui: shell chrome, controls, composer, labels, and ordinary UI text
• --font-conversation: user/assistant message prose; by default this is
  var(--font-ui) in static/style.css
• --font-mono: code, file paths, command lines, tool payloads, technical logs,
  and terminal output

Use semantic tokens for typography. Keep prose on --font-conversation by
default so it tracks --font-ui whenever a skin intentionally retunes UI type.
Override --font-conversation only for a skin that intentionally wants a
distinct prose face.
Conversation prose must remain the system sans by default. Do not introduce a
global conversation serif through the --font-conversation token or
selector-level overrides without explicit design approval plus code and test
evidence; keep distinct editorial prose typography explicitly opt-in or
skin-scoped.
Avoid hard-coding selector-level font stacks when a token already carries the
intent.

Keep scale tight. Avoid introducing near-duplicate one-off font sizes, colors,
radius values, or spacing values when an existing token works.

Color, depth, and shape Copy Chapter

Use one accent at a time. Semantic colors are for semantic state: success,
warning, error, and info. Do not mix many bright colors decoratively in the same
viewport.

Use almost no shadows in the transcript. Reserve shadows for popovers,
dropdowns, modals, and floating controls. Chat cards should usually use either a
subtle border or a subtle tint, not aggressive combinations of both.

Avoid stacks of nested rounded rectangles. Rows and list items should feel
compact; panels and cards may be slightly rounder; true pills are reserved for
chips and badges.

Composer and controls Copy Chapter

The composer is the command surface. Keep it legible, stable, and focused:

• no theatrical hover scaling for routine controls,
• no ambient chrome that crowds the model/workspace/profile controls,
• no new footer buttons on tight layouts without a clear value tradeoff,
• keep Stop/Send and context feedback easy to find while composing.

When adding a control, consider where users will find it on both wide desktop and
mobile. If a setting or quota/control surface does not fit in the composer, route
it through the appropriate Control Center panel instead of squeezing the footer.

Composer sizing Copy Section

The composer grows with its content up to a 200px cap. Where the browser supports
field-sizing: content (the stylesheet sets it on textarea#msg, with
field-sizing: fixed while the placeholder shows) CSS owns that; everywhere else
the JavaScript fallback (autoResize() in static/messages.js) measures, and it
runs on every keystroke - so treat it as a hot path and keep these invariants when
touching it (regression coverage:
tests/test_long_session_composer_typing_latency.py, which derives every
dimension from static/style.css, and
tests/test_issue5514_composer_grow_scroll_pin.py):

• A single-row append that already fits its box skips the height round trip. That
  round trip reads scrollHeight, which forces a synchronous layout of the whole
  document, so its cost grows with the rendered transcript - this is the
  long-session typing-lag class. Do not remove the skip.
• The skip's ceiling is the textarea's natural ONE-ROW height (line-height +
  vertical padding + borders) or the CSS min-height, whichever is larger.
  Compare against that natural row, never against min-height alone: the natural
  row follows the appearance font size (44px at the 16px default, 48px at
  data-font-size=large, 51px at xlarge), while min-height stays 44px, so a
  min-height-only ceiling silently disables the skip for the larger sizes.
• Everything else still fully remeasures: an oversized composer, a replacement, a
  shrink, a multi-line append, and session/draft restore.
• Non-pixel computed values (a percentage, calc(), auto) fail closed to the
  full resize rather than enabling the skip from a bogus pixel parse.

Responsive behavior Copy Chapter

Mobile is not an afterthought. The repository documents a responsive layout with
a hamburger sidebar, mobile-accessible top tabs, a right-edge file slide-over,
full-height chat/composer behavior on phones, and touch-friendly controls.

For UI changes, verify the relevant states:

• wide desktop,
• ordinary laptop width,
• narrow/mobile width,
• open and closed side panels when relevant,
• long chat content and live streaming when relevant.

Controls should remain usable at touch sizes, and mobile navigation should not
steal chat height unnecessarily.

Keyboard and assistive-tech behavior on closed mobile panels Copy Section

On the compact off-canvas bands, the closed sidebar and workspace drawer stay
laid out so their slide-out can animate, which would otherwise leave their whole
subtree in the tab order. Three layers keep a closed mobile panel out of the
keyboard sequence, and changes to this area must keep all three:

1. The panel takes the inert attribute the moment it closes
   (_setPanelInert() in static/boot.js, set by closeMobileSidebar() and
   _setWorkspacePanelMode()), so the 250 ms closing window is inert too — not
   just the settled state.
2. visibility:hidden, delayed past the slide-out
   (visibility 0s linear .25s in static/style.css), removes the settled
   subtree from the tab order without cutting the transform transition.
3. pointer-events:none keeps the parked panel from swallowing clicks aimed at
   the chat underneath it.

Focus handling when a mobile panel closes out from under a focused control
(_releaseFocusFromClosedPanel()) follows the same split as the desktop drawer:

• an explicit dismiss (the "Close menu" X, the overlay, the drawer's Close,
  tapping outside the drawer) returns focus to the control that opened the panel
  — the hamburger, or the band-appropriate workspace toggle;
• content-selection closes (picking a session or a panel item) leave focus on
  the composer, which those paths already move it to.

Browser probes that drive real key events are the only coverage that sees this:
a computed-style or tabIndex assertion cannot observe the browser refusing or
stranding a focus() call, and a static source assertion cannot observe a path
the probes never take. Keep both halves when adding a case.

Themes and skins Copy Chapter

Theme and skin work should use the existing variable system. THEMES.md points
to the core palette variables in static/style.css; skin comments in the CSS
show the expected pattern for full palette rewrites and accent-only changes.

Current implementation has two appearance axes, sourced from static/boot.js:
theme is only light, dark, or system and resolves to the .dark class
for dark mode; skin is a separate axis applied with data-skin and currently
includes default, ares, mono, slate, poseidon, sisyphus,
charizard, sienna, catppuccin, nous, and geist-contrast / Geist Contrast. slate is both an active skin
and a legacy theme-name migration target; solarized, monokai, nord, and
oled are legacy theme names mapped to current theme/skin pairs. Do not follow
stale data-theme-only guidance without first proving the current
static/boot.js, static/index.html, and static/style.css contracts still
support it.

Do not hardcode new colors, radii, shadows, or typography values into isolated
components when a token or existing variable can carry the intent. If a token is
missing, explain why a new one is needed.

Evidence expected for UI changes Copy Chapter

For any interface or interaction change:

• include before/after images or a short video,
• mention the tested viewport sizes and responsive states,
• reference the affected visual inventory or design source when applicable,
• add or update tests for behavior, state persistence, or regression-prone DOM
  structure where practical,
• keep stable class or data hooks when they help future visual regression tests.

Do / don't summary Copy Chapter

Do:

• keep the conversation primary,
• collapse noisy internals by default when settled,
• make debugging details accessible without making them visually dominant,
• use existing tokens, variables, and component patterns,
• protect action-required states such as errors and approvals.

Don't:

• make every tool call look like a separate chat message,
• add decorative color or motion without a user-facing reason,
• introduce a frontend framework, bundler, or build step for ordinary UI work,
• hide important recovery, error, or approval state,
• treat proposal mockups as shipped behavior without code/test evidence.

Advanced Chat Setup (`docs/advanced-chat-setup.md`) Copy Section

Advanced chat setup

Two optional features for self-hosted Hermes WebUI deployments. Most users need neither — the defaults (in-process chat, no prefill) work out of the box.

Session recall prefill Copy Chapter

WebUI can attach ephemeral prefill messages to new browser-originated
agent turns. This is useful when a deployment already has a local recall or
router script for Joplin, Obsidian, Notion, llm-wiki, or another third-party
notes source and wants browser chat to know where durable context lives.

Prefer a compact router-style prefill (for example, "Joplin has the durable
project context; use the available notes/search tools before answering
detail-dependent questions") instead of dumping the full note corpus into every
new browser session. The prefill should point the agent toward retrieval; the
notes/search tools should provide the specific facts on demand.

Static JSON remains supported through prefill_messages_file or
HERMES_PREFILL_MESSAGES_FILE. For dynamic recall, opt in explicitly with a
WebUI-specific script hook:

webui_prefill_messages_script:
  - python3
  - /path/to/notes_recall.py
webui_prefill_messages_script_timeout: 5

or:

HERMES_WEBUI_PREFILL_MESSAGES_SCRIPT="python3 /path/to/notes_recall.py" \
HERMES_WEBUI_PREFILL_MESSAGES_SCRIPT_TIMEOUT=5 \
./ctl.sh restart

The script may print either an OpenAI-style JSON message list, a JSON object with
a messages list, or plain text; plain text is wrapped as one user prefill
message so dynamic recall text becomes ordinary context instead of an extra
system instruction. If the hook must provide system-level guidance, emit JSON
messages with an explicit role: "system" entry instead. Script output is capped
at 256 KiB before parsing. Parsed prefill context is then bounded by
webui_prefill_context_max_chars or HERMES_WEBUI_PREFILL_CONTEXT_MAX_CHARS
(default: 12,000 characters; set to 0 to disable). When a dynamic script
exceeds the budget and a compact static prefill file is configured, WebUI falls
back to that file. If no compact fallback is available, WebUI injects a short
retrieval instruction instead of sending the oversized note/body payload with
every new browser turn. The browser only receives a compact status event
(source, label, message count, compaction metadata, and redacted errors),
never the prefill message bodies.

Session title generation Copy Chapter

Hermes WebUI derives a provisional session title from the first user message
and, after the first response, may call an LLM to generate a better title
(and periodically refresh it for long sessions).

For structured messages containing text and native images, title generation
uses the user text without flattening or modifying the stored message. Title
comparison and title-model inputs remove the internal [Workspace::v1: ...]
prefix and one terminal [Attached files: ...] or
[Attached files for this steer: ...] suffix separated by a blank line.
For structured content, this cleanup applies to the first text part that
provides title content. Literal legacy [Workspace: ...] text and later text
parts remain unchanged. Initial generation, explicit regeneration, and adaptive
refresh use this title-specific cleanup.

Background generation requires user text and a substantive assistant response.
It recognizes the sanitized provisional title as well as the existing raw
placeholder, so internal metadata does not make an image-containing turn look
manually titled. Image-only or metadata-only content does not provide title
text. Existing manual-title protection and the title-generation setting still
apply; this cleanup does not rewrite the transcript or native image parts.

Automatic title-generation LLM calls honor the active Hermes profile's
auxiliary.title_generation.enabled setting (default: true):

auxiliary:
  title_generation:
    enabled: false

When disabled:

• the provisional first-message title stays in place and is never replaced
  or overwritten by an automatic LLM call or local fallback;
• the periodic adaptive refresh is skipped;
• the explicit "regenerate title" action returns a
  title_generation_disabled response instead of calling a title model.

The WebUI's auto_title_refresh_every setting remains a separate control for
periodic refreshes of already-generated titles; it does not re-enable
automatic generation when the auxiliary flag is off.

Pinning the title language Copy Section

auxiliary.title_generation.language pins the language generated titles are
written in, whatever language the conversation itself is in:

auxiliary:
  title_generation:
    language: Japanese

A nonblank value is read once per generation attempt and drives both halves of
that attempt. The prompt instruction becomes Write the title in <language>.
in place of the default "match the language of the user question" rule, and the
post-generation drift check is retargeted to agree with it. Both title routes
honour the pin: the auxiliary-client route and the active-agent route.

Retargeting the validator is the point. The drift check exists to reject a
title whose language wandered away from the conversation (issue #3293), and on
a pinned install that same check would reject the pinned title the prompt had
just asked for. How a generated title is validated therefore depends on the
pin:

• A pin the script map recognises (Japanese, Russian, Amharic,
  Bengali, Brazilian Portuguese, pt-BR) is checked against that
  language's script. The map covers the Latin, Cyrillic, CJK, Arabic, Hebrew,
  Greek, Devanagari, Thai, Georgian, Armenian and Ethiopic scripts, and the
  major Indic and South-East Asian ones.
  A title substantially outside it is still rejected, so an English pin
  rejects a CJK title and a Japanese pin rejects a Cyrillic one. A CJK pin
  keeps borrowed Latin terms (Python, WeChat Pay) as long as the title
  also holds at least two CJK characters, the same exemption the
  conversation-based check applies. "Substantially outside" means more than
  a third of the title's letters, summed across every other script. Styled
  alphabets such as mathematical bold, circled, enclosed or fullwidth letters
  count as the plain letters they decompose to; Roman numerals and circled
  digits are not letters and are left out of the count.
• A pin the script map cannot resolve, and no pin, both keep the
  original behaviour: the title is checked against the language of the
  conversation's opening message. A pin outside the map therefore still
  changes the prompt, and a title that follows it into a script the
  conversation does not use is rejected as drift. Pin a language the map
  knows to get cross-script titles.

A language written in two scripts in majority use accepts either by default:
Punjabi accepts Gurmukhi and Shahmukhi (Arabic script), and Mongolian
accepts Cyrillic and the traditional Mongolian script. Serbian, Bosnian and
Uzbek have no default, because Cyrillic and Latin are both in wide use, so a
bare pin naming one of them keeps the conversation check.

A script qualifier narrows a recognised language to one script. It can be an
ISO 15924 code in a BCP 47 tag (pa-Arab, pa-Guru, mn-Mong, kk-Latn,
sr-Latn, zh-Hant) or an English script name beside the language
(Punjabi (Arabic), Malay (Jawi), Mongolian (Traditional),
Serbian (Cyrillic)). A qualifier is also how a minority script opts in: bare
Kazakh accepts Cyrillic only, and kk-Latn accepts Latin.

Anything ambiguous fails closed to the conversation check instead of widening
what is accepted:

• a qualifier on a language the map does not know (Klingon-Latn, xx-Latn,
  Klingon (Arabic));
• a language named only inside brackets after a word the map does not know
  (Klingon (English), Русский (Russian));
• a pin longer than 256 characters once surrounding whitespace is trimmed,
  or 64 after normalisation;
• two different qualifiers (English-Latn-Cyrl, pa-Arab-Guru), including
  two scripts validated the same way (ja-Hira-Kana,
  Chinese (Simplified, Traditional)), or Latin beside
  another script (Cyrillic Latin); equivalent ones collapse
  (pa-Arab-Aran, Japanese (Kanji, Hani));
• a script code in a tag that the table does not know (ja-Zyyy);
• two languages (English French);
• a two-letter code outside a BCP 47 tag (pt (Brazil), No preference),
  because such codes collide with region codes and ordinary words. Write the
  language name or a tag instead: Portuguese (Brazil) or pt-BR.

Language lookup is diacritic-insensitive. In a BCP 47 tag the language is the
first subtag. A POSIX locale's encoding and modifier are ignored
(en_US.UTF-8), except that every script named in the modifier qualifies
(be_BY@latin, sr_RS@latin; pa_IN@arabic-gurmukhi conflicts), and so does
a piece of the encoding that is exactly a script code (en-Latn.Cyrl
conflicts). Otherwise a
language name counts anywhere outside brackets, so Francais, Français,
Traditional Chinese and Brazilian Portuguese resolve. The same rule
applies to languages whose names are also script names (Arabic, Greek, Thai,
Latin and others), so Egyptian Arabic and Modern Greek resolve, and so do
Klingon Arabic and Klingon-Latin: the unknown word is read as a modifier of
the named language. Klingon (Arabic) stays unresolved, because a bracketed
word only qualifies. A word in brackets only
qualifies: Tamil (Arabic) is Tamil in Arabic script, and mn (Mongolian) is
Mongolian because the code and the name agree. A language's own name for itself
is mostly not recognised, and a bracketed English name beside it does not
rescue it: Русский (Russian) and Klingon (English) are unresolved. Write the
English name or a tag instead: Russian or ru.

A pin longer than 256 characters once surrounding whitespace is trimmed, or
64 characters after
normalisation (lowercasing, diacritic folding, punctuation to spaces), is not
parsed; it is unresolved, so the conversation check applies, and the title
prompt leaves it out.

The pin affects session titles only. It does not change the language the
assistant replies in, and it has no effect when
auxiliary.title_generation.enabled is false, since no LLM title is
generated at all in that case.

Invalid model output and title recovery Copy Section

A title model occasionally replies with an options menu instead of one title
(for example Good title options: "A", "B"). WebUI rejects structurally
multi-candidate replies — a menu preamble followed by two or more list
entries, semicolon/newline-separated candidates, explicitly quoted or
bulleted alternatives, or at least three short standalone comma-separated
alternatives — instead of persisting the raw menu as the title. A plain
two-part comma phrase such as Title Suggestions: OAuth Tokens, Explained
is ambiguous, so it stays valid. A comma joining grammatical clauses or a
comparison within one title (for example
Title Suggestions: Compare REST, GraphQL and gRPC) does not
prove a menu; neither do delimiters inside quoted terms.
Title Suggestions: Comparing "REST" and "GraphQL" stays valid.
A preamble with a single remaining phrase (for example
Title Suggestions: Migration Strategy) is kept, since that is a legitimate
title.

While a rejected reply leaves the automatic title unresolved, the provisional
title stays in place and the next completed exchange is used as the source for
a retry, so a session that opens with a warm-up message can still get a real
title from the substantive request that follows. The same recovery applies to
sessions that already persisted a menu-style title before this behavior
existed: they re-enter self-heal on the next turn. Manual renames always win;
recovery never overrides a user-set title. An unfinished latest turn is never
paired with an older assistant response, including during adaptive refresh.

After compression rotates a session ID (A→B), background title events target
the continuation directly — session_id and target_session_id carry B, and
stream_owner_session_id carries the original SSE owner A. The browser
listener accepts either identifier: a reattached B tab and an A tab that
rotates to B both apply the title, fencing on expectedCurrent so a manual
rename is kept. A title model that keeps returning unusable output is capped
at 3 recovery exchanges per session before it stops retrying. stream_end
still closes the original stream.

Session ID in the system prompt Copy Chapter

WebUI tells the agent which surface it is running on (source, profile and
workspace) in the system text of each turn. The session ID is not part of
that text by default. It is different for every chat, so with it two new chats
never send the same system text, and a provider or local backend that caches
the prompt prefix has to read the rest of the request again for every new
chat.

If a skill, plugin or prompt of yours needs the model to know its own session
ID, turn it back on in config.yaml:

webui:
  pass_session_id: true

true, yes, on and 1 are accepted; anything else, or no key, leaves it
off. This mirrors Hermes Agent's own pass_session_id option, which is also
off by default. When it is on, the ID is the last line of the system text
(- Session ID: ), so everything before it is still the same across
chats.

Gateway-backed browser chat Copy Chapter

By default, browser chat runs through WebUI's in-process legacy runtime. Advanced
self-hosted deployments can opt into routing new browser turns through a running
Hermes Gateway API server while preserving the existing WebUI /api/chat/start
and /api/chat/stream browser contract:

HERMES_WEBUI_CHAT_BACKEND=gateway \
HERMES_WEBUI_GATEWAY_BASE_URL=http://127.0.0.1:8642 \
HERMES_WEBUI_GATEWAY_API_KEY=... \
./ctl.sh restart

Gateway-backed approval prompts need one more explicit opt-in because they use the Gateway runs API path:

HERMES_WEBUI_CHAT_BACKEND=gateway \
HERMES_WEBUI_GATEWAY_BASE_URL=http://127.0.0.1:8642 \
HERMES_WEBUI_GATEWAY_API_KEY=... \
HERMES_WEBUI_GATEWAY_USE_RUNS_API=true \
./ctl.sh restart

Use this when the connected gateway advertises approval support and you want tool approval cards to appear in WebUI. Without HERMES_WEBUI_GATEWAY_USE_RUNS_API=true, gateway chat stays on the legacy chat-completions transport and approval-capable commands can remain pending in the agent without a WebUI approval card.

On the runs API path the turn is executed by the Gateway, so restarting WebUI does not stop it. WebUI stores the Gateway run_id on the pending turn (and submits it with an Idempotency-Key so the Gateway keeps a durable run record). On startup, WebUI reattaches to every such run by polling GET /v1/runs/{run_id} until it settles, then writes the real final answer into the session instead of a "Response interrupted" marker. Stop still cancels a reattached run, and a pending approval is shown again. Token-by-token output from before the restart is not replayed; the reattached turn shows only the final answer. If the Gateway no longer knows the run (for example, it restarted too and the run was interrupted), the turn ends with an error message instead. The legacy chat-completions transport cannot reattach: its turn ends when the WebUI process that holds the HTTP stream exits.

On the runs API path WebUI sends the session's earlier user and assistant turns to the Gateway as the run's conversation_history. Some transcript rows are shown in the conversation but not sent; they are the kinds of row the in-process backend also leaves out: error messages (a provider error, or the "Task cancelled." marker); a turn that left no visible text, such as one stopped while the model was still reasoning or calling a tool, or a reply that carried only reasoning; and a prompt that WebUI restored into the transcript after its turn was interrupted, unless the next row sent is its answer and it follows an assistant turn or opens the history, where it is the question that answer replies to. Where a stopped turn left a partial answer in the transcript, that text is sent, so the model can continue from it. An interrupted turn is reconciled into the model-facing context at the moment of cancellation — the prompt and the partial text the browser saw — whether the cancel came from WebUI's Stop or the Gateway itself, and the next turn's conversation_history carries that snapshot. When a stopped turn is regenerated instead, the retained prompt is sent once (as the new run's input, not duplicated in the history) and the writeback saves a single user row for it.

Live runs-API turns are also guarded while they stream. Each events connection carries a ~120s watchdog budget: a stream that delivers nothing but keepalives for that long is treated as stalled (keepalives are liveness, not progress), and the same budget bounds the per-read wait so a byte-silent connection surfaces within roughly one interval instead of pinning the configured 600s read timeout. When the watchdog trips, or the stream drops, the durable run status (GET /v1/runs/{run_id}) is the success arbiter: terminal status finalizes the turn (a non-empty durable output wins over the streamed text; with an empty output the already-streamed partial is kept), a still-running status reconnects the events stream from the last seen event, and waiting_for_approval surfaces the pending approval card from the status payload. A durable-status 404 gets a small immediate re-probe grace and then fails the turn closed rather than spinning. When the durable status resolves cancelled or interrupted, the streamed partial answer is persisted into the session before the browser-facing cancel event is emitted.

When YOLO is enabled for a gateway-backed browser session, WebUI approves every
approval already parked for that session: Runs API prompts are relayed by their
exact run_id and mirror token, and local/no-run waiters are all released. It
then automatically answers later Runs API approval requests while the WebUI
session flag remains active. The flag is committed only after every currently
parked remote relay succeeds; a later prompt that races that unconfirmed drain
remains visible instead of being speculatively auto-approved. The handoff is
also shared with local approval admission: a local waiter arriving after
the current drain snapshot waits for the same session handoff and is released
immediately if YOLO has committed, rather than being parked behind an enabled
session. This is client-managed compatibility behavior: the current Runs API has
no session-YOLO toggle, so a request briefly reaches the approval boundary before WebUI answers
it, and Agent-owned policy such as unrestricted computer-use mode is unchanged.
Native API session YOLO is tracked in Hermes Agent PR #61946.

HERMES_WEBUI_CHAT_BACKEND is intentionally strict: only gateway,
api_server, or api-server enable the bridge. Generic truthy values such as
1 or true are ignored so existing deployments do not change execution
ownership accidentally. If HERMES_WEBUI_GATEWAY_API_KEY is omitted, WebUI falls
back to API_SERVER_KEY when present. When Gateway returns HTTP 401, WebUI
reports a gateway_auth_error that points at this WebUI↔Gateway key mismatch
rather than showing the Gateway's generic provider-style "Invalid API key" body.
/api/health/agent also includes a redacted gateway_chat block so operators can
see whether gateway mode, base URL, and API-key presence are configured without
exposing the key value. That gateway_chat field is an operator diagnostic
payload only; it is not currently rendered as a user-facing health banner in the
browser UI.

Several profiles behind one Gateway Copy Section

A turn uses the gateway URL and key of the session's own profile, not those of whichever profile the WebUI process loaded.

• A profile that sets nothing of its own (no HERMES_WEBUI_GATEWAY_BASE_URL, HERMES_WEBUI_GATEWAY_API_KEY or API_SERVER_KEY in its own .env, no webui_gateway_base_url in its config.yaml) uses the shared endpoint the WebUI process was given, URL and key together. That includes values exported by the launcher and values the default profile's ~/.hermes/.env put into the process environment. This is what a single-profile setup sends, so named profiles on a shared Gateway keep working unchanged.
• A profile can override the URL and the key independently. The half it does not set comes from the shared pair above. A profile's own URL is HERMES_WEBUI_GATEWAY_BASE_URL in its .env, or webui_gateway_base_url in its config.yaml (an exported HERMES_WEBUI_GATEWAY_BASE_URL takes precedence over config.yaml); a profile with no URL of its own keeps the shared URL. A profile's own key is HERMES_WEBUI_GATEWAY_API_KEY or API_SERVER_KEY in its .env.
• The shared key is only ever sent to the shared Gateway. On a URL that is not the shared one, a profile sends its own key or none, never the launcher's or the shared key. On the shared URL the order is: the profile's own HERMES_WEBUI_GATEWAY_API_KEY, then the shared HERMES_WEBUI_GATEWAY_API_KEY (exported by the launcher, or set in the root profile's ~/.hermes/.env), then the profile's API_SERVER_KEY (the key of its own Gateway), then the shared key. A global HERMES_WEBUI_GATEWAY_API_KEY combined with per-profile HERMES_WEBUI_GATEWAY_API_KEY values therefore works: each profile with its own alias sends that alias.
• A ${VAR} in a profile's webui_gateway_base_url is expanded from that profile's .env, read fresh from the file on every turn, plus any launcher export that did not come from another profile's .env. If the variable is not set anywhere, the turn ends with an error naming the unresolved variable and no request is sent.

The bridge is best used by operators who already run Hermes Gateway/API Server
locally and want browser-originated chat to use the same runtime/tool path as
messaging surfaces. Attachments, cancellation, approvals, and clarify prompts
still follow WebUI's current compatibility path and may not match every messaging
surface until the runtime-adapter migration is complete.

Docker (`docs/docker.md`) Copy Section

Hermes WebUI — Docker setup guide

This is the comprehensive Docker reference. For a 5-minute quickstart, see the README Docker section.

TL;DR — pick one Copy Chapter

Available Docker tags Copy Section

The WebUI Docker image is published to ghcr.io/nesquena/hermes-webui with these tags:

To track experimental builds in Docker Compose, use the :experimental tag:

services:
  hermes-webui:
    image: ghcr.io/nesquena/hermes-webui:experimental

Note: updating between :experimental builds requires docker compose pull followed by docker compose up -d — the floating tag is updated only when a new exp-v* release is pushed. Experimental builds are not pushed on every commit to the default branch.

When update checks are enabled, a Docker-installed WebUI compares its baked release tag with the selected stable or experimental channel. Settings shows the number of newer channel releases and the matching docker pull command even though the image does not contain .git history.

Note (v0.14+): If you use docker-compose.three-container.yml, both
hermes-agent and hermes-dashboard initialise from the same image and write
to the same hermes-home volume simultaneously. This can cause overlapping lock
files and stale gateway_state.json entries. The unified pattern described in
Three-service unified setup (v0.14+) below
avoids this by running a single hermes-agent process that serves both the
gateway and the dashboard.

If something stops working, start with the single-container setup — it's the simplest path and fixes most permission/UID/path-mismatch issues by construction.

Production image security model Copy Chapter

The production Docker image is hardened for the normal single-tenant container threat model:
Hermes WebUI assumes one operator controls the container, mounted Hermes home, and workspace.
The image does not install sudo, does not add runtime users to a sudo group, and does not
grant NOPASSWD escalation. If an agent/tool process gains a shell as hermeswebui, it should
not be able to become root with a passwordless sudo command.

The entrypoint still starts as root for a narrow init phase because Docker bind mounts often need
UID/GID alignment and ownership preparation before the app can read ~/.hermes, /workspace,
/app, and /uv_cache. After that setup, docker_init.bash re-execs itself as the unprivileged
hermeswebui user and starts the server there. Init scratch files under /tmp/hermeswebui_init
are owner-only (0700 directory, 0600 files), not world-writable.

For multi-tenant or hostile-container environments, rebuild with your own runtime user, mount policy,
and supervisor assumptions. Development images that need package-manager convenience should add
those tools in a dev-only Dockerfile instead of reintroducing passwordless sudo to production.

5-minute quickstart (single container) Copy Chapter

git clone https://github.com/nesquena/hermes-webui
cd hermes-webui
cp .env.docker.example .env
# Edit .env if needed (most users can skip this on Linux)
docker compose up -d
open http://localhost:8787

That's it for a real personal Docker install. Your existing ~/.hermes
directory is mounted, your ~/workspace is browsable, and the WebUI
auto-detects your UID/GID from the mounted volume.

The single-container setup runs the WebUI only. It can create cron jobs and run
them manually from the Tasks panel. In Docker, scheduled jobs require the Hermes gateway daemon
to tick while you are away. If System Settings shows Gateway not configured,
use docker-compose.two-container.yml,
docker-compose.three-container.yml, or run hermes gateway separately before
relying on offline scheduled runs. See Scheduled jobs and the gateway daemon below for the full background and verification steps.

For troubleshooting, reinstall, or onboarding reproduction trials, do not mount
your real ~/.hermes unless you intentionally want to test real state. Use an
isolated Hermes home and follow
docs/onboarding-agent-checklist.md instead.

Linux note: run Compose as the user who owns the Hermes home. The command
sudo docker compose up -d can make Compose expand ${HOME} as /root, so
the default ${HOME}/.hermes bind mount becomes /root/.hermes instead of
your user's real Hermes directory. Prefer adding your user to the docker group
and running docker compose up -d; if you must preserve the caller environment
for a one-off root run, use sudo -E docker compose up -d and verify the
rendered mount with docker compose config first.

Optional GPU runtime image Copy Chapter

The default Hermes WebUI Docker image stays CPU-only. GPU user-space packages
are installed only when you build a custom image with the opt-in build arg:

docker build --build-arg INSTALL_GPU_LIBS=1 -t hermes-webui:gpu .

That build path installs VA-API basics (libva2, vainfo), AMD Mesa VA-API
drivers (mesa-va-drivers), and the Intel non-free media driver when that
package is available from the configured Debian repositories. NVIDIA host
runtime tooling is not installed into the app image; use the NVIDIA Container
Toolkit on the host and pass GPUs through at runtime.

GPU passthrough still depends on host drivers, Docker runtime support, and
device mappings. The commands below are configuration guidance for a suitable
Linux Docker host; they are not a claim that native GPU passthrough was verified
in this workspace.

Intel and AMD VA-API Copy Section

Expose the host render devices and add the runtime user to the common video and
render groups:

docker run --rm \
  --device /dev/dri:/dev/dri \
  --group-add video \
  --group-add render \
  hermes-webui:gpu vainfo

For Compose, add the same mapping to a custom service definition:

services:
  hermes-webui:
    image: hermes-webui:gpu
    devices:
      - /dev/dri:/dev/dri
    group_add:
      - video
      - render

vainfo should list the VA-API driver and supported profiles when the host
driver stack and container permissions are correct. The container entrypoint
preserves Docker-provided supplemental groups before it drops privileges to the
hermeswebui runtime user, so the WebUI process keeps access to /dev/dri.

NVIDIA Copy Section

Install and configure the NVIDIA Container Toolkit on the host first, then use
Docker's GPU runtime flag:

docker run --rm --gpus all hermes-webui:gpu nvidia-smi

For Compose, use a custom service with GPU access enabled:

services:
  hermes-webui:
    image: hermes-webui:gpu
    gpus: all

If nvidia-smi is unavailable or reports no devices, fix the host NVIDIA driver
and container toolkit setup before debugging Hermes WebUI. The container image
only supplies the WebUI plus optional user-space media libraries; it cannot
provide host kernel drivers or the NVIDIA runtime.

Scheduled jobs and the gateway daemon Copy Chapter

Symptom: Cron jobs created in the Tasks panel never fire. System Settings or Tasks shows:

• Orange "Gateway not configured", or
• Red "Gateway metadata stale" when runtime metadata is stale, or
• Red "Gateway endpoint not reachable" when WebUI has a gateway URL configured but cannot reach its health endpoint.

Cause: Scheduled cron ticks are not driven by the WebUI itself. The gateway daemon ticks the scheduler every 60 seconds; without one running, scheduled jobs sit idle. "Run now" / "Trigger" buttons still work because the WebUI handles those in-process.

The cron list itself is still read from the shared HERMES_HOME volume, not
from the gateway HTTP API. If the Tasks panel shows a gateway warning while the
job list loads, the warning is about scheduled ticking / gateway health, not
about the list endpoint.

In older gateway builds, or when the daemon runs in a separate container, gateway_state.json can become stale and WebUI may lose confidence even if the daemon is up. This is especially visible if the WebUI container has no gateway URL and can only inspect local state files from its own container.

Fix: Run a gateway container alongside the WebUI. The two-container compose file is the recommended path:

cp .env.docker.example .env
docker compose -f docker-compose.two-container.yml up -d

The compose files forward API_SERVER_KEY from .env into the hermes-agent
container. The agent only starts the gateway API listener (port 8642) when
API_SERVER_KEY is a usable value (>=16 chars) — API_SERVER_ENABLED alone
does nothing. Without a key, the gateway daemon still runs but port 8642 stays
unbound and the WebUI keeps showing "Gateway endpoint not reachable". To
enable scheduled ticking and the green gateway pill, set a long random string
in .env:

echo "API_SERVER_KEY=$(openssl rand -hex 24)" >> .env
docker compose -f docker-compose.two-container.yml up -d --force-recreate

The compose file forwards the same value to the WebUI as
HERMES_WEBUI_GATEWAY_API_KEY, so the health probe authenticates automatically.

The three-container layout adds the dashboard but is otherwise the same shape. If you must stay single-container, you can run hermes gateway inside the container as a long-lived background process, but the compose split is sturdier.

If you maintain a custom compose file, make sure the WebUI service points at
the gateway service over the compose network:

services:
  hermes-webui:
    environment:
      - HERMES_API_URL=http://hermes-agent:8642
      # HERMES_WEBUI_GATEWAY_BASE_URL=http://hermes-agent:8642 also works.

If WebUI browser chat is routed through that gateway and you expect approval prompts for guarded tools, set the gateway chat backend and opt into the runs API path in the WebUI service:

services:
  hermes-webui:
    environment:
      - HERMES_WEBUI_CHAT_BACKEND=gateway
      - HERMES_WEBUI_GATEWAY_BASE_URL=http://hermes-agent:8642
      - HERMES_WEBUI_GATEWAY_USE_RUNS_API=true
      # HERMES_WEBUI_GATEWAY_API_KEY=... when the gateway requires API auth.

HERMES_WEBUI_GATEWAY_USE_RUNS_API=true is required for gateway approval cards because approval-capable gateway runs emit approval requests on the runs API transport. Leaving it unset keeps browser chat on the legacy chat-completions path.

Do not copy only API_SERVER_ENABLED=true / API_SERVER_HOST=0.0.0.0 into the
agent service as a standalone fix. If you intentionally enable the agent API
server, the agent also requires a real API_SERVER_KEY (at least 8 characters),
and the WebUI still needs HERMES_API_URL or HERMES_WEBUI_GATEWAY_BASE_URL to
reach that service from its container.

Verify: Once the gateway is up, the System Settings pill should turn green and the Tasks banner disappear. From the host:

export GATEWAY_BASE_URL="${HERMES_API_URL:-${HERMES_WEBUI_GATEWAY_BASE_URL:-http://hermes-agent:8642}}"
docker compose -f docker-compose.two-container.yml exec hermes-agent hermes gateway status
curl -sS "${GATEWAY_BASE_URL%/}/health/detailed" | jq '.gateway_state, .state'

If the service name differs in your compose file, docker compose -f docker-compose.two-container.yml ps lists the running services.
For container-to-container diagnostics, set one of HERMES_API_URL or HERMES_WEBUI_GATEWAY_BASE_URL in the WebUI environment, then restart WebUI.

Refs #2785, #4483.

Three-service unified setup (v0.14+) Copy Chapter

Since v0.14, hermes-agent can serve the gateway API and the built-in dashboard
from the same process by setting HERMES_DASHBOARD_HOST and
HERMES_DASHBOARD_PORT. Running agent and dashboard in one container means a
single writer to hermes-home, eliminating the concurrent-init write conflicts
that occur when hermes-agent and hermes-dashboard both start from the same
image against the same volume.

The three-service pattern uses two containers:

Example compose snippet (save as docker-compose.three-service.yml or inline into your own file):

services:
  hermes-agent:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-agent
    command: gateway run
    ports:
      - "127.0.0.1:8642:8642"
      - "127.0.0.1:9119:9119"
    volumes:
      - hermes-home:/home/hermes/.hermes
      - hermes-agent-src:/opt/hermes
    environment:
      - HERMES_HOME=/home/hermes/.hermes
      - HERMES_UID=${UID:-1000}
      - HERMES_GID=${GID:-1000}
      - HERMES_DASHBOARD_HOST=0.0.0.0
      - HERMES_DASHBOARD_PORT=9119
    restart: unless-stopped
    networks:
      - hermes-net

  hermes-webui:
    image: ghcr.io/nesquena/hermes-webui:latest
    container_name: hermes-webui
    depends_on:
      - hermes-agent
    ports:
      - "127.0.0.1:8787:8787"
    volumes:
      - hermes-home:/home/hermeswebui/.hermes
      - hermes-agent-src:/home/hermeswebui/.hermes/hermes-agent:ro
      - ${HERMES_WORKSPACE:-${HOME}/workspace}:/workspace
    environment:
      - HERMES_WEBUI_HOST=0.0.0.0
      - HERMES_WEBUI_PORT=8787
      - HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui
      - WANTED_UID=${UID:-1000}
      - WANTED_GID=${GID:-1000}
    restart: unless-stopped
    networks:
      - hermes-net

networks:
  hermes-net:
    driver: bridge

volumes:
  hermes-home:
  hermes-agent-src:

Open http://localhost:8787 for chat and http://localhost:9119 for the dashboard.
Check hermes gateway run --help for the exact flag names for your agent release —
the env-var equivalents shown above (HERMES_DASHBOARD_HOST, HERMES_DASHBOARD_PORT)
are available in recent releases alongside the CLI flags.

If you need the separate dashboard container (e.g. resource limits per service),
docker-compose.three-container.yml still works. Add a depends_on from
hermes-dashboard to hermes-agent with a condition: service_healthy healthcheck
so the dashboard waits for the gateway to finish initialising agent-home before it
starts its own init pass.

What goes wrong (and how to fix it) Copy Chapter

Compatibility policy and version pinning Copy Section

WebUI shows the version it is currently running, but that display does not in itself guarantee tested compatibility with your agent release.

Until the compatibility boundary work in #1925 and #2491 land, the WebUI and Hermes Agent deployment should be treated as a release pair: the WebUI release is tested against its matching agent release and should be upgraded/pinned together.

If you use latest, use it consistently on both sides and avoid mixing a fixed tag with latest:

• fixed WebUI tag + hermes-agent:latest
• hermes-webui:latest + fixed hermes-agent tag

In multi-container setups, if you must run a pinned pair, prefer the matching tag in docker-compose.two-container.yml/docker-compose.three-container.yml and perform the agent-volume refresh workflow in Upgrading the agent container whenever you upgrade the agent image.

If you see behavior issues after a mixed-version upgrade, capture both WebUI and hermes-agent versions and the compose layout in the issue.

1. "Permission denied" at startup Copy Section

Symptom: Container starts but immediately crashes, logs show:

PermissionError: [Errno 13] Permission denied: '/home/hermeswebui/.hermes/...'

Cause: The container's user (UID 1000 by default) can't read your bind-mounted directory because your host files are owned by a different UID.

Fix: Set UID and GID in .env to match your host:

echo "UID=$(id -u)" >> .env
echo "GID=$(id -g)" >> .env
docker compose down && docker compose up -d

On macOS, host UIDs start at 501. On Linux, the first interactive user is usually UID 1000.

macOS Docker Desktop: if UID mapping still misbehaves after the env fix, try toggling Settings → General → File sharing implementation between VirtioFS and gRPC-FUSE. Different implementations preserve UIDs across the host/container boundary differently.

2. ".env file mode 0640 → permission denied" (#1389) Copy Section

Symptom: You set HERMES_HOME_MODE=0640 (or some other group-readable mode) on your host .env file, container starts, then errors out:

[security] fixed permissions on .env (0o640 -> 0600)
failed to load .env: open .env: permission denied

Cause: WebUI's fix_credential_permissions() startup hook enforces 0600 by default. This is the right thing for a clean install but conflicts with operator-set modes.

Fix: Set one of these env vars in your .env:

• HERMES_SKIP_CHMOD=1 — bypass the fixer entirely
• HERMES_HOME_MODE=0640 — allow group bits, only strip world-readable

Both are documented in api/startup.py::fix_credential_permissions().

⚠️ Multi-container warning: HERMES_HOME_MODE has DIFFERENT semantics in the agent image vs. the WebUI:

• WebUI: credential FILE mode threshold (0640 allows group bits on .env)
• Agent: HERMES_HOME directory mode (default 0700)

0640 on a directory has no owner-execute bit, so the agent can't traverse its own home → bricked. For multi-container setups, use HERMES_HOME_MODE=0750 (group-traversable) or 0701 (x-only). The compose files have per-service comments that match each side's semantics.

3. "Workspace appears empty even though my files are there" Copy Section

Symptom: WebUI loads but /workspace shows no files.

Cause: Same as #1 — UID mismatch on the bind mount.

Fix: Same as #1 — match host UID/GID via .env.

4. "Two-container setup: WebUI can't find agent source" (#858) Copy Section

Symptom: WebUI logs at startup:

!! WARNING: hermes-agent source not found.
!!   Looked in: /home/hermeswebui/.hermes/hermes-agent
!!              /opt/hermes

Cause: The agent's source (/opt/hermes inside the agent container) needs to be exposed to the WebUI container via a shared volume. The two-container compose file does this via hermes-agent-src named volume, but if you're using bind mounts incorrectly the path won't resolve.

Fix: Use the named volumes that ship with docker-compose.two-container.yml — don't replace them with bind mounts unless you know what you're doing. The agent container writes its source to /opt/hermes, and the WebUI mounts that volume at /home/hermeswebui/.hermes/hermes-agent.

If you must use a bind mount: pick a host path, then mount it to /opt/hermes in the agent container AND /home/hermeswebui/.hermes/hermes-agent in the WebUI container.

5. "Tools (git, node, etc.) missing in two-container setup" (#681) Copy Section

Symptom: You ask the agent to run git status in chat and it errors with command not found.

Cause: This is architectural, not a bug. In the two-container setup, agent processes started by the WebUI run inside the WebUI container, not the agent container. The WebUI image doesn't include git/node by design (it's a UI image, not a tool host).

Workarounds:

• Single-container setup (docker-compose.yml) — everything in one container, no boundary
• Custom WebUI image — extend the Dockerfile to install the tools you need
• Combined image (sunnysktsang/hermes-suite) — community fork that ships agent+webui+dashboard in one container

6. "config.yaml not loaded" Copy Section

Symptom: You have a config.yaml in your host ~/.hermes/, but the WebUI shows "no model configured" or doesn't pick up your custom providers.

Cause: Either the file isn't readable (UID/GID issue, see #1) or it's not in the expected path inside the container.

Fix:

• Verify: docker exec hermes-webui ls -la /home/hermeswebui/.hermes/config.yaml
• If it doesn't exist: your host bind mount is pointing at the wrong directory.
• If it exists but is unreadable: see #1 for the UID/GID fix.

7. "On Podman: can't share .hermes between containers" Copy Section

Symptom: Two-container setup works on Docker but fails on Podman with permission errors no matter what UID/GID you set.

Cause: Podman 3.4 (Ubuntu 22.04 default) has limited support for userns_mode: keep-id across multiple containers — files written by one container appear with a different UID in the other.

Fix: Either upgrade to Podman 4+ (which fixes this), or use the single-container setup, or use the community all-in-one image.

8. "API base URL set to localhost fails from Docker" (#3012) Copy Section

Symptom: A provider, local model server, webhook, or custom API works on the host at http://localhost:, but fails when the same URL is configured in Hermes WebUI running in Docker.

Cause: Inside a container, localhost means that container, not your laptop/host. The WebUI process cannot reach host services through 127.0.0.1 unless the service is running inside the same container.

Fix: Point Docker-hosted WebUI at the host gateway name instead:

• Docker Desktop on macOS/Windows: http://host.docker.internal:
• Podman: http://host.containers.internal:
• Linux Docker Engine: either publish the host service on the Docker bridge address, or add a host-gateway alias to your compose service:

services:
  hermes-webui:
    extra_hosts:
      - "host.docker.internal:host-gateway"

Then configure the URL as http://host.docker.internal:. Also ensure the host service binds to an address reachable from containers (not only a loopback interface the Docker bridge cannot reach) and that your host firewall allows the connection.

9. "Failed to verify state directory" / restart loop on a bind-mounted state dir (#7027) Copy Section

Symptom: Single-container deploy with the state directory bind-mounted from a
host directory, no WANTED_UID set. The container exits 1 and restart-loops:

-- Auto-detected workspace UID: 1024 (from /workspace)
touch: cannot touch '/app/data/.testfile': Permission denied
!! ERROR: Failed to verify state directory at /app/data

Cause: UID auto-detection used to read /workspace before the configured
state directory. In a stock image /workspace exists and is owned by the
image's own build-time 1024:1024, so detection returned a value that carries
no information about the host — and because 1024 is also the fallback default,
the log read as if detection had found nothing.

Fix: Fixed in the init script — the configured HERMES_WEBUI_STATE_DIR is
now probed first. The full order is:

1. $HERMES_WEBUI_STATE_DIR (default /app/data) — a bind mount by definition
   in a single-container deploy, so its owner is the host identity to match
2. /home/hermeswebui/.hermes, $HERMES_HOME, /opt/data — the hermes-home
   shared volume in two-container setups (#668)
3. /workspace — used only when nothing above resolves
4. 1024 — fallback default

Root-owned candidates (UID 0, e.g. a freshly created named volume) are skipped
at every step. An explicitly supplied WANTED_UID/WANTED_GID always wins and
is never overwritten by detection — including the value 1024, which earlier
versions treated as "unset".

If you are on an older image, the workaround is to set the IDs explicitly:

docker run -e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) ...

Multi-container architecture Copy Chapter

The two- and three-container setups use named Docker volumes (not bind mounts) by default for a reason: named volumes solve the UID/GID problem by construction. Docker creates the volume's root directory with the correct ownership, all containers reading/writing to it see the same files, no host-side permission setup required.

┌─────────────────────────────────┐
                 │      hermes-home (volume)       │
                 │  (config, sessions, state, ...)  │
                 └─────────────────────────────────┘
                          ↑              ↑
                          │ rw           │ rw
                          │              │
      ┌──────────────┐    │              │    ┌──────────────┐
      │ hermes-agent │────┘              └────│ hermes-webui │
      │  (port 8642) │                        │  (port 8787) │
      └──────────────┘                        └──────────────┘
              │                                       ↑
              │ rw                                    │ ro
              ↓                                       │
      ┌─────────────────────────┐                     │
      │ hermes-agent-src (vol)  │─────────────────────┘
      │ (agent's Python source) │
      └─────────────────────────┘

The WebUI container doesn't ship with the agent's Python deps — at startup it runs uv pip install /home/hermeswebui/.hermes/hermes-agent to install them from the shared volume. The WebUI mount is read-only; the agent container is the only writer.

Upgrading the agent container Copy Chapter

The hermes-agent-src named volume is initialised from the agent image's /opt/hermes on first up. Docker reuses the volume verbatim on every subsequent up — even after docker pull of a newer agent image. The cached volume content masks the new image's source tree, so a fresh docker pull of nousresearch/hermes-agent:latest does not by itself give you the new agent code, dependencies, or entrypoint.

This is the root cause of #1416: the symptom looked like a missing entrypoint, but the entrypoint was actually present in the new image and hidden behind the stale named volume.

To upgrade the agent image cleanly, drop the source volume before recreating:

# Two-container setup
docker compose -f docker-compose.two-container.yml down
docker volume rm <project>_hermes-agent-src
docker compose -f docker-compose.two-container.yml pull
docker compose -f docker-compose.two-container.yml up -d

# Three-container setup
docker compose -f docker-compose.three-container.yml down
docker volume rm <project>_hermes-agent-src
docker compose -f docker-compose.three-container.yml pull
docker compose -f docker-compose.three-container.yml up -d

Replace `` with your Compose project name (the parent directory by default; check with docker volume ls). The hermes-home volume (config, sessions, state) is left untouched — only hermes-agent-src (the agent's installed Python source) is recreated.

The single-container setup (docker-compose.yml) does not use hermes-agent-src and is not affected by this upgrade pattern — pulling a newer WebUI image and docker compose up -d --force-recreate is sufficient.

What the multi-container setup isolates (and what it doesn't) Copy Chapter

The two- and three-container setups give you process, network, and resource isolation between the gateway and the chat UI:

• Each service has its own PID namespace and lifecycle — the agent process can crash without taking down the chat UI and vice versa.
• The gateway API (port 8642) is bound by the agent service only; the WebUI cannot bind it. Other containers reach the gateway via the hermes-net Docker network.
• Resource limits (deploy.resources.limits in docker-compose.three-container.yml) apply per service, so you can cap the agent independently of the dashboard.
• Restart policies, log streams, and container health checks are scoped per service.

What multi-container does not isolate:

• Filesystem boundary. Both services share hermes-home (config, sessions, state), and the WebUI mounts the agent's installed source from hermes-agent-src. The WebUI mount is read-only (since v0.51.84), but the agent service still has write access, and both services share the home volume.
• UID/GID boundary. Both services default to ${UID:-1000} so files written by one are readable by the other. If you align them to different UIDs you'll get permission errors on the shared volume.
• Trust boundary on the agent source. The WebUI installs Python dependencies from the shared hermes-agent-src volume at startup. The read-only mount means a compromised WebUI cannot rewrite the agent source, but it does run code from that volume.

If you need filesystem isolation between the chat UI and the agent (e.g. you don't trust the WebUI to read agent state), the multi-container setup is not enough — run the agent on a separate host and connect the WebUI to it via the gateway HTTP API. If you don't need any boundary, the single-container setup is simpler.

The direct source mount is a compatibility bridge, not the long-term API contract. The current source/API boundary inventory and decoupling task list live in docs/rfcs/agent-source-boundary.md for #2453. If you customize the compose files with bind mounts, keep the WebUI-side agent source mount read-only unless you are intentionally doing local development; docker_init.bash warns at startup when that path is writable.

Bind-mount migration (advanced) Copy Chapter

If you really need to bind-mount an existing host ~/.hermes (e.g. you're keeping config in dotfiles, sharing with a non-Docker hermes install, etc.):

volumes:
  hermes-home:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /home/youruser/.hermes
  hermes-agent-src:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /opt/hermes-agent-source

Critical requirements:

1. The host directory MUST be readable by your container UID. Run id -u on the host and ensure ~/.hermes is owned by that UID (or readable via group bits).
2. ALL containers sharing the volume must run as the SAME UID/GID. Set UID=$(id -u) and GID=$(id -g) in .env.
3. If you run Compose with sudo, do not rely on ${HOME} defaults: sudo often changes $HOME to /root, so ${HERMES_HOME:-${HOME}/.hermes} becomes /root/.hermes. Prefer running Docker as your user; otherwise pass absolute paths with sudo -E, for example HERMES_HOME=/home/youruser/.hermes HERMES_WORKSPACE=/home/youruser/workspace sudo -E docker compose up -d, and confirm the rendered bind mount with docker compose config.
4. If your host .env is mode 0640, set HERMES_SKIP_CHMOD=1 or HERMES_HOME_MODE=0640 so the startup hook doesn't try to enforce 0600.

Reference Copy Chapter

• docker-compose.yml — single container (recommended)
• docker-compose.two-container.yml — agent + webui
• docker-compose.three-container.yml — agent + dashboard + webui
• .env.docker.example — environment variable template
• Dockerfile — single-container build
• docker_init.bash — container entrypoint script

Related issues Copy Chapter

• #1416 — agent-image upgrade requires removing hermes-agent-src named volume (see Upgrading the agent container)
• #1389 — HERMES_HOME_MODE override (fixed in v0.50.254 — agent honors HERMES_SKIP_CHMOD and HERMES_HOME_MODE)
• #1399 — UID alignment in compose files (fixed in v0.50.260 via PR #1428 + this guide)
• #3012 — host localhost API URLs fail from Docker containers (use host.docker.internal / host.containers.internal)
• #3006 — sudo docker compose can mount /root/.hermes instead of the user's Hermes home
• #3243 — optional GPU runtime image/docs for containerized acceleration workloads
• #858 — two-container /opt/hermes path confusion
• #681 — tools running in WebUI container, not agent container (architectural)
• #668 — auto-detect UID/GID from mounted volume
• #569 — UID/GID detection priority order
• #7027 — state dir probed before /workspace in UID/GID detection (see #9 above)

If you hit a new failure mode not covered here, please open an issue with:

1. Which compose file you used
2. The error from docker logs hermes-webui
3. docker exec hermes-webui id output
4. docker exec hermes-webui ls -la /home/hermeswebui/.hermes output

Kanban (`docs/kanban.md`) Copy Section

Kanban board status flow

The Kanban panel (static/panels.js) is a view over the Hermes Agent's
hermes_cli.kanban_db; api/kanban_bridge.py handles WebUI task writes.
Structured transitions use the Agent's own verbs; the claim-aware direct
write _set_status_direct() (api/kanban_bridge.py:281) still covers triage,
todo and some moves to ready. Scheduled (#7900) is covered in detail below.

Columns Copy Chapter

BOARD_COLUMNS (api/kanban_bridge.py:32) fixes the board order:

triage → todo → scheduled → ready → running → blocked → done

archived is also accepted as a status by _validate_status
(api/kanban_bridge.py:272) but is rendered as a terminal flag rather than a
column.

running is never entered from the UI: the bridge rejects
PATCH {"status": "running"} with HTTP 400 (api/kanban_bridge.py:431)
because the dispatcher/claim_task protocol owns claim_lock,
claim_expires and worker_pid.

Where status can be changed Copy Chapter

All of those funnel into _patch_task() (api/kanban_bridge.py:380), which
switches on the target status and calls the matching Agent verb. The bulk
endpoint does the same per id (api/kanban_bridge.py:719), so a multi-select
move to Scheduled is refused exactly like a single-card move would be.

Scheduled Copy Chapter

A Scheduled card is a time-delayed task: it is visible in its column but the
dispatcher does not claim it while it stays there.

Entering Scheduled Copy Section

PATCH /api/kanban/tasks/ with {"status": "scheduled"} — what the
detail-view button, a drag onto the Scheduled column and the bulk select all
send. The scheduled branch (api/kanban_bridge.py:458) then:

1. raises scheduling requires a newer Hermes Agent when the installed Agent
   exposes no schedule_task — HTTP 409, with no mutation, so an Agent
   that cannot schedule never ends up with a raw status write;
2. delegates to kb.schedule_task(conn, task_id, reason=...), the Agent's own
   verb, which accepts todo / ready / running / blocked → scheduled.
   A Done → Scheduled move is refused by the Agent and surfaces here as HTTP
   400 cannot schedule task from status: done, and an active run is settled
   by the Agent with outcome="scheduled" rather than left orphaned;
3. passes reason only when the caller actually sent one, so a plain status
   move never synthesizes a run record that never happened and never
   overwrites the task's latest worker summary.

Leaving Scheduled Copy Section

• → ready (api/kanban_bridge.py:443): when the current status is
  blocked or scheduled, the bridge calls kb.unblock_task() instead of
  a direct write. unblock_task re-gates on parent completion — a child whose
  parent is still unfinished lands in todo (not ready) and emits an
  unblocked event, while a child with all parents complete lands in ready.
• → triage / todo: _set_status_direct() (api/kanban_bridge.py:281),
  the claim-aware direct write.
• → done / blocked / archived: the Agent's complete_task / block_task
  / archive_task.
• Unblock button on the detail view (api/kanban_bridge.py:768): also
  calls kb.unblock_task(), so it applies the same parent re-gating.

The task editor follows the Blocked precedent Copy Section

scheduled is deliberately not in the modal's status <select>.
_kanbanEditableStatusFor() (static/panels.js:3484) maps it to triage for
display exactly like blocked / running / done / archived, so opening a
Scheduled card shows Triage together with the
Actual status: Scheduled hint (static/panels.js:3541), and an untouched
save omits status from the PATCH payload entirely
(static/panels.js:3711) — saving without touching the field keeps the card
Scheduled instead of silently demoting it to Triage.

Changing status on a Scheduled card from the modal is therefore explicit: the
payload carries status only when the user picked a value different from the
displayed default, and that value still goes through _patch_task() and the
Agent's verb for the target status.

Onboarding Agent Checklist (`docs/onboarding-agent-checklist.md`) Copy Section

Agent-assisted onboarding checklist

This checklist is for an AI assistant helping a human install, reinstall, or
debug Hermes WebUI onboarding. It does not replace the human first-run wizard.
Use it before running bootstrap commands, inspecting logs, or recommending a
cleanup path.

If you are an AI assistant, read this file before assisting with onboarding,
bootstrap, provider setup, reinstall, or first-run support.

Role split Copy Chapter

The human operator owns:

• choosing the install path
• choosing the provider and model
• entering API keys, OAuth codes, and passwords
• approving any cleanup of a real Hermes home
• approving any external exposure outside localhost

The assistant owns:

• using isolated trial directories unless the human explicitly says otherwise
• checking non-secret status endpoints and logs
• explaining which step passed or failed
• collecting redacted evidence for Discord or GitHub support
• stopping before destructive cleanup, credential handling, or public exposure

Hard safety rules Copy Chapter

• Do not delete, move, or overwrite the real ~/.hermes directory unless the
  human explicitly asks for that exact action.
• Do not print API keys, OAuth tokens, cookies, full .env files, full
  auth.json files, or password hashes.
• Do not modify real cron jobs, real sessions, real profiles, or real memory
  files during an onboarding trial.
• Do not expose WebUI on a public interface without password protection and
  explicit human approval.
• Do not proxy or tunnel local service checks such as localhost,
  127.0.0.1, private LAN addresses, or Docker container loopback paths.

Pre-flight Copy Chapter

Confirm the basic context:

pwd
git branch --show-current
git rev-parse --short HEAD
python3 --version

Check whether repo-local environment overrides will affect bootstrap:

test -f .env && grep -n 'HERMES_HOME\|HERMES_WEBUI_STATE_DIR\|HERMES_WEBUI_PORT\|HERMES_WEBUI_HOST' .env

If .env exists, do not print the full file. Inspect only the specific
non-secret keys needed to understand the active Hermes home, WebUI state
directory, port, or host.

Isolated local trial Copy Chapter

Use an isolated Hermes home and WebUI state directory for a reinstall or support
trial. This keeps the test away from the operator's real memory, sessions,
profiles, credentials, and cron state.

mkdir -p ~/hermes-onboarding-test
HERMES_HOME=~/hermes-onboarding-test/.hermes \
HERMES_WEBUI_STATE_DIR=~/hermes-onboarding-test/webui \
HERMES_WEBUI_PORT=8789 \
python3 bootstrap.py

Open:

http://127.0.0.1:8789

The bootstrap writes a port-specific log under the selected WebUI state
directory:

~/hermes-onboarding-test/webui/bootstrap-8789.log

For daemon-style installs, ctl.sh writes the daemon log to the active
HERMES_HOME by default:

~/.hermes/webui.log

When using the isolated trial environment, prefer the bootstrap command above
unless the human specifically wants to validate ctl.sh.

Non-secret evidence commands Copy Chapter

After the server starts, collect status without secrets:

curl -sS http://127.0.0.1:8789/health
curl -sS http://127.0.0.1:8789/api/onboarding/status
find ~/hermes-onboarding-test -maxdepth 3 -type f | sort
tail -n 120 ~/hermes-onboarding-test/webui/bootstrap-8789.log

When summarizing /api/onboarding/status, focus on:

• completed
• system.hermes_found
• system.imports_ok
• system.config_path
• system.config_exists
• system.setup_state
• system.provider_configured
• system.provider_ready
• system.chat_ready
• system.current_provider
• system.current_model
• system.current_base_url
• system.env_path

Do not paste the full payload if it contains unexpected sensitive local paths
or values. Redact paths and provider details when the human asks for a public
GitHub or Discord support report.

Pass criteria Copy Chapter

A local onboarding trial passes when:

• /health returns successfully.
• /api/onboarding/status returns JSON.
• The wizard appears when completed is false.
• The wizard stays out of the way when completed is true or
  HERMES_WEBUI_SKIP_ONBOARDING=1 is intentionally set.
• system.hermes_found and system.imports_ok match the expected bootstrap
  state.
• system.provider_ready and system.chat_ready become true after the human
  completes a provider path that should support chat.
• system.config_path and system.env_path point inside the intended isolated
  HERMES_HOME during a trial.
• WebUI files are written under the intended HERMES_WEBUI_STATE_DIR.

If the human chooses a provider that must be completed in the CLI, passing can
mean the wizard correctly points them to hermes model or hermes auth rather
than trying to collect unsupported credentials in the browser.

Failure triage Copy Chapter

If the server does not start:

• check the bootstrap log
• check for a port conflict on 8789
• confirm Python can run bootstrap.py
• confirm .env is not overriding the isolated directories or port

If onboarding reports agent_unavailable:

• confirm the bootstrap found or installed Hermes Agent
• check whether the running Python can import run_agent.AIAgent
• use docs/troubleshooting.md, especially the AIAgent not available flow

If onboarding reports provider_incomplete:

• confirm whether the provider is API-key based, OAuth based, or local
• let the human enter credentials or run the CLI auth flow
• do not ask the human to paste secrets into chat

If a local model server does not probe successfully:

• from native macOS/Linux, use http://127.0.0.1:/v1 when the server is
  on the same host
• from Docker Desktop, use http://host.docker.internal:/v1
• from another LAN machine, use the server's LAN IP and /v1
• remember that localhost inside a container is the container itself

If password or reverse-proxy behavior is confusing:

• keep the first pass on 127.0.0.1
• require password protection before exposing WebUI beyond localhost
• include the reverse proxy shape in the support report without pasting tokens
  or cookies

Final support report Copy Chapter

Use this shape when reporting results to the human, Discord, or GitHub:

Install path:
OS / Python:
Repo commit:
Command used:
WebUI URL:
State isolation:
Health result:
Onboarding status summary:
Files created or changed:
Log excerpt:
Pass/fail:
Next recommended action:

Redact secrets and private paths before posting publicly.

Onboarding (`docs/onboarding.md`) Copy Section

First-run onboarding guide

This guide explains what happens the first time Hermes WebUI starts, which
setup path to choose, and how to recover when the wizard cannot finish.

If an AI assistant is helping with install, reinstall, bootstrap, provider
setup, or first-run support, read
docs/onboarding-agent-checklist.md before
running commands or inspecting logs.

The short version: run the bootstrap, open the WebUI, choose a provider, choose
a workspace, optionally set a password, then start a chat. If you are using a
local model server from Docker, pay special attention to the Base URL section
below.

Before you start Copy Chapter

Hermes WebUI is only the browser interface. The actual agent runtime, memory,
skills, config, cron jobs, and provider credentials belong to Hermes Agent.

The bootstrap supports Linux, macOS, and WSL2. Native Windows is not supported
by the bootstrap yet. A community native Windows setup is being tracked in
#1952, including:

• Native Windows guide
• Native Windows setup scripts

For Windows users who want the supported path today, use WSL2 and see
Windows / WSL auto-start.

Install path choices Copy Chapter

If a Docker install gets confusing, start again with the single-container setup.
It avoids most UID/GID, source-volume, and tool-location surprises. See
Docker setup guide for the full container reference.

Re-running onboarding safely Copy Chapter

Do not delete ~/.hermes just to see the wizard again. That directory can hold
your real Hermes config, credentials, memory, skills, profiles, sessions, and
cron state.

For a clean local trial, use an isolated Hermes home and WebUI state directory:

mkdir -p ~/hermes-onboarding-test
HERMES_HOME=~/hermes-onboarding-test/.hermes \
HERMES_WEBUI_STATE_DIR=~/hermes-onboarding-test/webui \
HERMES_WEBUI_PORT=8789 \
python3 bootstrap.py

Then open http://127.0.0.1:8789.

For an assistant-led trial run, follow the safety rules, evidence commands, and
pass/fail criteria in
docs/onboarding-agent-checklist.md.

If your repo has a .env file, remember that the bootstrap loads it. Remove or
adjust any HERMES_HOME, HERMES_WEBUI_STATE_DIR, or HERMES_WEBUI_PORT
entries there before using the isolated command above.

For managed hosting or fully preconfigured images, set
HERMES_WEBUI_SKIP_ONBOARDING=1 to bypass the wizard.

If the port is already in use Copy Chapter

The bootstrap checks the resolved host and port before it installs the agent,
sets up dependencies, or creates state. When another service already holds
the port, it stops there and reports the address it could not bind together
with a free alternative it verified, for example:

Port 8787 on 127.0.0.1 is already in use by another service. Try an available port instead: ./start.sh 8789 Or set HERMES_WEBUI_PORT=8789 in /path/to/hermes-webui/.env. The existing service was left untouched; no configuration was changed.

Nothing is reconfigured for you: the running service is untouched and .env
is not rewritten. Re-run with the suggested port as the argument
(./start.sh 8789) or put HERMES_WEBUI_PORT=8789 in .env.

A port held by a healthy WebUI is not a conflict: re-running bootstrap (or
start.sh falling back to it without curl/wget) reports the already-running
instance ready and exits 0. Only a foreground/supervisor launch, which
would be a second server on the same port, reports the duplicate start.

Only the WebUI's own /health payload counts as that running instance: any
other service, including one answering a generic {"status": "ok"}, is
reported as the conflict above. A bind address that cannot be used at all
(--host naming another machine, for example) stays a hard error, so a
bootstrap that started nothing never claims to be running.

What the wizard checks Copy Chapter

The first screen reports the runtime state WebUI can see:

• Hermes Agent importability: whether WebUI can import and run AIAgent.
• Provider status: whether config.yaml and credential state are enough for a
  chat request.
• Password status: whether WebUI password protection is enabled.
• Config paths: the active config.yaml and .env locations for this profile.

If the agent check fails, use Troubleshooting, especially
the AIAgent not available section. If provider setup is incomplete, continue
through the wizard or run hermes model in the same machine environment that
will run WebUI.

Choosing a provider Copy Chapter

The setup step groups providers by how much information they usually need.

For API-key providers, the wizard writes the key to the active Hermes .env
file and writes the default model/provider to config.yaml.

For local providers, the API key field can be blank when the server is keyless.
Most LM Studio, Ollama, vLLM, llama-server, and TabbyAPI installs run this way.
Use Test connection to verify the Base URL and populate the model list
before continuing.

After reload, a saved self-hosted Base URL is shown as Configured even when
the provider has no API key. This label means that an endpoint is saved; it does
not mean the endpoint is reachable now or that it is the active runtime
provider. Use Test connection to verify reachability.

AIML API uses the existing custom OpenAI-compatible setup path, not a
first-class built-in Hermes provider id. Configure it under the
custom-provider flow with Base URL https://api.aimlapi.com/v1, then use
either the normal custom-provider API key field or a config entry that points
at AIMLAPI_API_KEY if you want the custom provider to read its key from the
environment. Create or manage keys at https://aimlapi.com/app/keys. Model
discovery comes from the live /v1/models response for that endpoint, not from
a static WebUI-maintained model list.

Advanced provider flows such as Nous Portal and GitHub Copilot are still
terminal-first. OpenAI Codex and Anthropic Claude Code OAuth can be started in
the onboarding flow when your Hermes config selects the corresponding provider.
If the wizard points you back to hermes model, use that CLI flow first, then
refresh WebUI.

Base URL rules for local model servers Copy Chapter

For self-hosted providers, the Base URL should point to the OpenAI-compatible
API root. Common examples:

Inside Docker, localhost means the WebUI container itself, not your Mac,
Windows host, Linux host, or another machine on your LAN. If LM Studio or Ollama
is running outside the container, use host.docker.internal on Docker Desktop,
use the server's LAN IP address, or add a Linux Docker host alias:

services:
  hermes-webui:
    extra_hosts:
      - "api.local:host-gateway"

Then use http://api.local:/v1 as the Base URL. The alias avoids writing
localhost in WebUI config where it would resolve to the container loopback
instead of the host service.

The wizard probes /models before saving. A successful probe fills
the model dropdown. A failed probe blocks the setup step and shows an inline
error such as DNS failure, connection refused, timeout, HTTP error, or
unexpected response shape.

Workspace step Copy Chapter

The workspace is the filesystem location Hermes should use for new sessions.
It can be a source checkout, a project directory, or a general workspace folder.

In Docker, the default browsable path is /workspace, which maps to the host
directory mounted by the compose file. If the workspace appears empty, check the
Docker UID/GID and mount guidance in Docker setup guide.

Password step Copy Chapter

Password protection is optional for localhost-only installs. Enable it if you
expose WebUI outside 127.0.0.1, behind a reverse proxy, or on a LAN.

For installed PWAs, prefer WebUI's built-in password over proxy basic auth. Reverse proxies are supported, but HTTP basic-auth challenges in front of the WebUI origin can interrupt the service-worker and shell-asset fetches the installed app relies on during updates. If you keep proxy auth, scope it so same-origin sw.js, manifest, and shell update requests can complete.

The password is stored through the normal WebUI settings path and hashed
server-side. You can change it later from Settings.

What gets written Copy Chapter

The wizard uses the same files and APIs as the normal app:

• Active Hermes config.yaml: provider, default model, and Base URL when
  relevant. A self-hosted provider keeps its saved Base URL independently of
  the active model; activating a selection updates the existing active
  provider/default-model/Base-URL tuple.
• Active Hermes .env: provider API keys when you entered one.
• WebUI settings.json: onboarding completion, workspace, password state, and
  other WebUI preferences.

State normally lives outside the repository. By default:

• Hermes Agent state: Windows %LOCALAPPDATA%\hermes; POSIX ~/.hermes
• WebUI state: $HERMES_HOME/webui (Windows default %LOCALAPPDATA%\hermes\webui, POSIX default ~/.hermes/webui)

Override these with HERMES_HOME and HERMES_WEBUI_STATE_DIR when you need an
isolated test install.

When to file an issue Copy Chapter

File an issue when the diagnostics point to WebUI rather than local
configuration. Include:

1. Install path: local bootstrap, Docker single-container, Docker
   two-container, Docker three-container, WSL2, or community native Windows.
2. Output from /health, or the startup banner if the server never starts.
3. The provider selected in onboarding and the Base URL shape, with secrets
   redacted.
4. For Docker provider problems, the result of probing from inside the
   container, for example:

docker exec hermes-webui sh -c 'curl -sS -w "\nHTTP %{http_code}\n" http://host.docker.internal:1234/v1/models | head -50'

5. Any inline wizard error text and relevant logs.

Never paste API keys, OAuth tokens, or full .env contents into an issue.

Remote Access Zh (`docs/remote-access-zh.md`) Copy Section

远程访问（中文指南）

本文是 docs/remote-access.md 的中文姊妹篇，面向中文用户，
重点覆盖 Windows 原生环境。命令与安全约定以官方脚本（start.sh / start.ps1 /
scripts/windows/setup_webui_autostart.ps1）为准。

Hermes WebUI 默认只绑定 127.0.0.1（仅本机回环），这是刻意的安全默认值。
要从手机或另一台电脑访问，需要显式选择一条安全通道。本文按推荐程度排序：

一、SSH 隧道（Linux / macOS / VPS） Copy Chapter

服务器保持默认回环绑定不变，从本地机器开一条 SSH 隧道：

ssh -N -L <本地端口>:127.0.0.1:<远程端口> <用户>@<服务器地址>

示例（远程 8787 → 本地 8787）：

ssh -N -L 8787:127.0.0.1:8787 [email protected]

然后浏览器打开 http://localhost:8787。

start.sh 检测到你在 SSH 会话中运行时会自动打印这条命令。

二、Tailscale 私有网络访问（推荐） Copy Chapter

Tailscale 是基于 WireGuard 的零配置组网工具：
服务器和手机装上后自动进入同一个私有网络，无需端口转发、无需公网暴露。
Hermes WebUI 自带移动端适配布局（汉堡侧栏、抽屉式顶部标签、触控友好的控件），
作为手机的日常 AI 助手界面非常合适。

方案 A：Tailscale Serve（首选） Copy Section

WebUI 保持绑定回环，只把端口"发布"到你的 tailnet：

1. 在服务器和手机上都安装 Tailscale 并登录同一账号。

2. 启用密码认证后启动 WebUI（保持回环绑定）：

   bash Copy

   HERMES_WEBUI_PASSWORD=你的密码 ./start.sh

   Windows 原生环境见下文"三、Windows 原生部署"。

3. 通过 Tailscale Serve 发布本地端口：

   bash Copy

   tailscale serve --bg 8787

4. 用 Tailscale 打印的 HTTPS MagicDNS 地址在手机浏览器打开。

要点：

• Tailscale Serve 让 WebUI 继续待在回环上，同时为你的 tailnet 提供 HTTPS
  MagicDNS 域名，不需要改 HERMES_WEBUI_HOST，也不需要开防火墙端口。

• Linux 上修改 Serve 配置可能需要提权。若报 Access denied: serve config denied，
  用 sudo 执行：

  bash Copy

  sudo -S -p '' tailscale serve --bg 8787

  或者把运行 WebUI 的非 root 用户设为 Tailscale operator：

  bash Copy

  sudo -S -p '' tailscale set --operator=$USER
  tailscale serve --bg 8787

方案 B：直连 Tailscale IP（备选） Copy Section

Serve 不可用/被禁用时，直接走 tailnet IP。因为这会超出回环绑定，必须启用密码认证：

HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PASSWORD=你的密码 ./start.sh

然后在手机浏览器打开 http://<服务器Tailscale-IP>:8787（服务器上执行
tailscale ip -4 查看自己的 Tailscale IP）。

流量全程由 WireGuard 端到端加密，密码认证在应用层保护界面。
可以把它添加到手机主屏，获得近似原生 App 的体验。

三、Windows 原生部署 Copy Chapter

Windows 用户不要直接 python server.py——请用仓库自带的原生启动器
start.ps1，它会自动完成：加载 .env、发现 Python、
定位 hermes-agent 安装目录、设置默认环境变量，然后拉起 server.py。

1. 首次准备 Copy Section

原生 Windows 路径要求 Python 3.11+ 与 hermes-agent 已安装。
关键：依赖要装在 start.ps1 实际使用的那个解释器里。 start.ps1
启动时会优先用 <hermes-agent>\venv\Scripts\python.exe，找不到才回退
到 PATH 上的 python——WebUI 仓库本地的 venv\ 永远不会被它挑中。
所以把 requirements.txt 装到 hermes-agent 的 venv，而不是在 WebUI
仓库下新建一个 venv。

hermes-agent 的常见安装位置（任选其一，取决于当初的安装方式）：

%USERPROFILE%\.hermes\hermes-agent            # 官方安装器默认
%LOCALAPPDATA%\hermes\hermes-agent            # 备选
%ProgramW6432%\hermes\hermes-agent           # 全局安装

在该目录下创建 venv 并装依赖（下面以默认的 %USERPROFILE%\.hermes\hermes-agent
为例）：

cd $env:USERPROFILE\.hermes\hermes-agent
python -m venv venv
.\venv\Scripts\pip.exe install -r C:\path\to\hermes-webui\requirements.txt

如果 hermes-agent 装在其它位置，把第一行 cd 换成对应目录即可。

备选：在 WebUI 仓库本地建 venv 也可以（python -m venv venv +
venv\Scripts\pip install -r requirements.txt），但这只在
<hermes-agent>\venv\Scripts\python.exe 不存在、且 PATH 上的
python.exe 恰好指向你装依赖时用的那个解释器时，start.ps1 才
会用上你装的依赖——非常容易踩坑。最稳的路径仍然是装到 hermes-agent
的 venv。

如果机器上同时存在多个 hermes-agent（例如仓库旁边还有一个源码检出），
start.ps1 只会在少数“被挤掉的布局”里改选已安装的 Agent：裸源码检出、仓库旁
sibling、仓库父目录上的 Agent 根（源码或 pip 形态），或 %USERPROFILE%\hermes-agent，且该选中项没
有自己的 venv\Scripts\python.exe。布局回退场景下，即使安装项没有 venv（依赖
已可由当前解释器导入）也可能改选；其它情况仍要求安装项带 venv。源码检出自带
venv 时仍然优先，符合 api/config.py 的源码优先顺序。想完全指定位置就设
HERMES_WEBUI_AGENT_DIR。

2. 带密码启动（前台） Copy Section

$env:HERMES_WEBUI_PASSWORD = "你的密码"
.\start.ps1

默认绑定 127.0.0.1:8787。常用参数：

绑定 0.0.0.0 前先设密码：一旦绑定所有接口，任何能路由到该端口的设备
都能触达界面，密码认证是唯一防线。参见文末"安全边界"。

改完密码先验证一下：start.ps1 会加载仓库根目录的 .env，但
已经设置的环境变量优先——上面用 $env:HERMES_WEBUI_PASSWORD
设的值会生效，.env 里的同名项被跳过。Linux / WSL 下的 start.sh
恰好相反：它会先 source 一遍 .env，.env 里的值会覆盖命令行
内联的 HERMES_WEBUI_PASSWORD=。无论用哪个启动脚本，改完密码后都用
浏览器打开登录页，确认真的要求输入密码且新密码能登录；不对的话，
先检查仓库根目录的 .env 里是否还留着旧值。

3. Windows 防火墙 Copy Section

用 Tailscale Serve（方案 A）时不需要任何防火墙放行——连接发生在
Tailscale 虚拟网卡与回环之间，Windows 防火墙不会拦截回环流量。

用"直连 Tailscale IP（方案 B）"时，Windows 防火墙可能会拦下从手机进来的
8787 连接。此时请只对 Tailscale 接口/网络放行，而不是对所有网络放行：

# 允许 Tailscale 网段访问 8787（按你的实际 tailnet CIDR 调整）
New-NetFirewallRule -DisplayName "Hermes WebUI (Tailscale only)" `
  -Direction Inbound -Protocol TCP -LocalPort 8787 `
  -RemoteAddress 100.64.0.0/10 -Action Allow

要点：

• 100.64.0.0/10 是 CGNAT 保留段，Tailscale 的虚拟 IP 都落在这个范围；
  这样规则只对 tailnet 生效，公网接口依然拒绝。
• 不要写 -Profile Any -RemoteAddress Any 这类全放行规则——那是把服务
  直接暴露到公网的行为，见"安全边界"。

四、WSL 用户：Windows 开机自启 Copy Chapter

本节只适用于在 WSL2 内运行 WebUI 的用户。 原生 Windows 启动请看
上一节"三、Windows 原生部署"——start.ps1 本身不自带开机自启
（Windows 登录时不会自动拉起 PowerShell 脚本），需要自启的话请改
用 WSL 路径或自行配置 NSSM / Task Scheduler 启动 start.ps1。

官方 WSL 自启通道是 Windows 任务计划程序 + WSL 启动脚本，配套脚本在
scripts/windows/setup_webui_autostart.ps1。
它注册一个"登录时启动"的计划任务，通过 wsl.exe 在 WSL 发行版内执行启动脚本。
该脚本幂等：重复运行只更新已有任务，不会创建重复项。

前置：WSL2 内已能手动启动 WebUI（见 docs/wsl-autostart.md），
并确保启动脚本可执行：

chmod +x /path/to/hermes-webui/scripts/wsl/hermes_webui_autostart.sh

然后回到 Windows PowerShell 注册计划任务（-WslScriptPath 是 WSL 内部路径）：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\windows\setup_webui_autostart.ps1 `
  -WslScriptPath "/home/你的用户名/hermes-webui/scripts/wsl/hermes_webui_autostart.sh" `
  -Distro "Ubuntu"

参数说明：

• -Distro 可省略，省略时使用默认 WSL 发行版。
• 任务默认名 HermesWebUIAutoStart，需要改名传 -TaskName。
• 加 -RunNow 注册后立即启动；加 -WhatIf 只预览不注册；
  仅当 WSL 路径尚不存在时才需要 -SkipValidation。

事后查看或移除任务：

Get-ScheduledTask -TaskName HermesWebUIAutoStart
Unregister-ScheduledTask -TaskName HermesWebUIAutoStart -Confirm:$false

自启日志位置（WSL 内）：

$HOME/.hermes/webui/logs/webui_autostart.log
$HOME/.hermes/webui/logs/hermes_webui.log

五、常见问题 Copy Chapter

六、安全边界（重要） Copy Chapter

区分三种暴露范围：

1. Tailscale 私有（推荐）：仅你的 tailnet 设备可达。Serve 方案连端口都不用开；
   直连 IP 方案（"二、方案 B"）则要看 HERMES_WEBUI_HOST 设的是什么：

   • 首选： HERMES_WEBUI_HOST=$(tailscale ip -4)——只绑 Tailscale
     虚拟网卡，其他接口根本不开 8787，连防火墙关了也安全。
   • 次选： HERMES_WEBUI_HOST=0.0.0.0 + Windows 防火墙只对
     100.64.0.0/10 放行（"三、3 防火墙"）。"仅 tailnet 可达"
     这条结论完全靠这条防火墙规则兜底——一旦放行规则被改回
     Any、或防火墙被关闭，WebUI 立刻对 LAN/公网开放，因为
     0.0.0.0 是所有接口，不是只绑 Tailscale 网卡。

   WireGuard 端到端加密 + 应用层密码认证是双层保险。

2. 局域网（LAN）：HERMES_WEBUI_HOST=0.0.0.0 且防火墙对私有网段放行。
   同一 WiFi 下的其他设备都能触达——密码认证是必需品，且不建议用于公共 WiFi。

3. 公网：端口对互联网开放。不推荐。WebUI 本身只做简单的登录限速（每个 IP
   每 60 秒最多 5 次失败尝试），但直连时没有传输加密（HTTP 明文）；若确有需要，
   应放在 HTTPS 反向代理（Caddy/Nginx）之后并启用强密码。

所有超出回环的绑定，第一守则：先设 HERMES_WEBUI_PASSWORD，再改绑定地址。

原文：docs/remote-access.md · 部署相关：docs/docker.md · Windows/WSL 自启：docs/wsl-autostart.md

Remote Access (`docs/remote-access.md`) Copy Section

Remote access

How to reach a self-hosted Hermes WebUI from another machine or your phone.

Accessing from a remote machine Copy Chapter

The server binds to 127.0.0.1 by default (loopback only). If you are running
Hermes on a VPS or remote server, use an SSH tunnel from your local machine:

ssh -N -L <local-port>:127.0.0.1:<remote-port> <user>@<server-host>

Example:

ssh -N -L 8787:127.0.0.1:8787 [email protected]

Then open http://localhost:8787 in your local browser.

start.sh will print this command for you automatically when it detects you
are running over SSH.

Accessing on your phone with Tailscale Copy Chapter

Tailscale is a zero-config mesh VPN built on
WireGuard. Install it on your server and your phone, and they join the same
private network -- no port forwarding, no SSH tunnels, no public exposure.

The Hermes Web UI is fully responsive with a mobile-optimized layout
(hamburger sidebar, sidebar top tabs in the drawer, touch-friendly controls),
so it works well as a daily-driver agent interface from your phone.

Preferred setup: Tailscale Serve

1. Install Tailscale on your server and
   your iPhone/Android.
2. Keep the WebUI bound to localhost and enable password auth:

HERMES_WEBUI_PASSWORD=your-secret ./start.sh

3. Publish the local WebUI port through Tailscale Serve:

tailscale serve --bg 8787

4. Open the HTTPS MagicDNS URL that Tailscale prints in your phone's browser.

Tailscale Serve keeps WebUI on loopback while giving your tailnet an HTTPS
MagicDNS hostname. On Linux, changing Serve configuration may require elevated
permissions. If tailscale serve --bg 8787 reports Access denied: serve config denied, either run it with sudo:

sudo -S -p '' tailscale serve --bg 8787

Or allow the supervised non-root WebUI/Hermes user to manage Tailscale:

sudo -S -p '' tailscale set --operator=$USER
tailscale serve --bg 8787

Fallback: direct tailnet IP

Use direct tailnet access when Tailscale Serve is unavailable, disabled, or not
permitted. Because this binds WebUI beyond loopback, always enable password
auth:

HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PASSWORD=your-secret ./start.sh

Then open http://<server-tailscale-ip>:8787 in your phone's browser (find
your server's Tailscale IP in the Tailscale app or with tailscale ip -4 on
the server).

That's it. Traffic is encrypted end-to-end by WireGuard, and password auth
protects the UI at the application level. You can add it to your home screen
for an app-like experience.

Community field report: ARM64 Android via AVF Copy Section

A community report in #2364
documents Hermes Agent + WebUI running on a mid-range ARM64 Android phone inside
a Debian 12 VM via Android Virtualization Framework (AVF). The reported setup
used a Xiaomi Redmi Note 13 Pro 4G, 3.8 GiB RAM allocated to the VM, 8 visible
CPU cores, Chrome on Android at localhost:8787, and cloud-hosted inference.

This is not an official support baseline or provider/model benchmark, but it is
a useful compatibility signal for mobile ARM64 experiments: the WebUI rendered
smoothly in Chrome, ARM64 Debian worked for the agent stack, and the total local
footprint was about 1.7 GB. Practical caveats from the report: first install can
take longer when dependencies compile from source, Android browser tabs may
reload when switching apps, and disabling battery optimization for the terminal
or VM host may be needed for longer-running sessions.

Tip: If using Docker, set HERMES_WEBUI_HOST=0.0.0.0 in your
docker-compose.yml environment (already the default) and set
HERMES_WEBUI_PASSWORD.

Remote Workspaces (`docs/remote-workspaces.md`) Copy Section

Remote Terminal Workspaces

Architecture contract and path-resolution semantics for remote terminal profiles (SSH, Docker) in Hermes WebUI.

1. Overview Copy Chapter

When a Hermes profile is configured with a remote terminal backend (e.g. terminal.backend: "ssh" or "docker"), its working directory (terminal.cwd) lives on the remote target host rather than the local WebUI host filesystem.

On hosts such as macOS, local path resolution via Path.resolve() or os.path.realpath() expands synthetic firmlinks (e.g. rewriting /home/ to /System/Volumes/Data/home/). Because the target-side path does not exist on the local macOS server, unconstrained local resolution causes runtime validation failures and session corruption.

2. Path Resolution Contract Copy Chapter

1. Target-side POSIX Path Preservation:

   • Any valid POSIX path at or beneath a remote profile's configured terminal.cwd is preserved verbatim as a Path object without calling host-local Path.resolve().
   • Traversal escapes (..), null bytes (\0), and blocked system roots (/etc, /usr, /var, /sys, /proc, /dev) continue to be strictly rejected.

2. Profile Isolation & Boundary Enforcement:

   • Remote path recognition is strictly scoped to the target/active profile.
   • If an active profile has a local backend, target-side remote paths belonging to inactive named profiles are not treated as remote for the active local profile.
   • For local profiles, workspace addition (/api/workspaces/add) enforces host-local directory existence and permissions.
   • For remote profiles, workspace addition validates against the profile's remote terminal.cwd and skips host-local directory creation (mkdir).

3. Session & Streaming Lifecycle:

   • Session.__init__ and Session.load normalize session workspace paths through _resolve_path(..., profile=profile), preserving target-side paths for remote profiles and preventing corruption of session.workspace or session.created_workspace.
   • Streaming execution (_run_agent_streaming) and multimodal asset root resolution preserve the remote session workspace when updating runtime run state.

Sse Streams (`docs/sse-streams.md`) Copy Section

SSE streams and capability signaling

Cross-client reference for the server-sent events (SSE) endpoints Hermes WebUI
exposes. Browser and non-browser clients (Android wrapper, CLI observers)
should integrate against this page so every client describes the same
behavior.

All endpoints below are served by the WebUI origin and sit behind the same
authentication as every other /api/* route: when a WebUI password or OIDC
is configured, clients must authenticate before opening any stream.

Endpoint inventory Copy Chapter

The authoritative event: names on /api/chat/stream are listed in the
Authoritative emitted events table of
docs/rfcs/session-sse-contract-v1.md.

Gateway probe scope (important for non-browser clients) Copy Chapter

GET /api/sessions/gateway/stream?probe=1 returns a JSON capability payload
for the optional gateway stream only instead of holding an SSE connection:

{
  "enabled": false,
  "ok": false,
  "watcher_running": false,
  "fallback_poll_ms": 30000,
  "error": "agent sessions not enabled",
  "scope": "gateway_sessions",
  "session_stream_available": true,
  "session_stream_path": "/api/session/stream"
}

• 404 + error: "agent sessions not enabled" means only that the optional
  gateway/agent-sessions stream is disabled on this server.
• 503 + error: "watcher not started" means the setting is on but the
  gateway watcher thread is not running.
• 200 with ok: true means gateway SSE is usable.

A negative gateway probe result must not be treated as "SSE unavailable".
The persistent per-session stream (/api/session/stream) and the chat-turn
relay (/api/chat/stream) are always on and are not gated by the Agent
sessions setting. The scope, session_stream_available, and
session_stream_path fields make this explicit so clients do not need to
infer it from the status code. Clients that only need session updates should
use /api/session/stream directly; the gateway probe is only relevant for
clients that display CLI/TUI/messaging sessions.

Gateway watcher projection lifecycle Copy Chapter

The optional gateway stream's watcher owns a cheap database fingerprint and a
timestamp for its last full session projection. While clients are subscribed,
an unchanged fingerprint can skip the expensive read until the bounded parity
interval. With no subscribers the poll loop parks instead of reading the DB.
When the final subscriber leaves (including eviction of a full or failed
consumer queue), the watcher invalidates both cache fields. A reconnect must
therefore trigger a fresh projection even when the database fingerprint has not
changed and the parity interval has not elapsed. Final removal also advances a
subscriber epoch: an older in-flight DB read cannot restore the invalidated
cache or publish its result to a later subscriber cohort. The subscriber lock
protects removal, epoch checks and cache commits, but is not held during DB
reads, so disconnect is not blocked by a slow projection.

Reasoning settlement Copy Chapter

When a /api/chat/stream turn settles, _settle_turn_reasoning() in
api/streaming.py persists a reasoning trace on each of the turn's new
assistant messages before the session is saved. Assistant messages from
earlier turns are never modified.

• Non-empty agent reasoning wins. The agent writes the key on every
  assistant message it builds, but None only means the provider did not
  return final reasoning. It is not evidence the step had no thinking, so
  stream-only providers fall through to the stream.
• Stream segments are bound to the step that owns them. When a tool
  starts, on_tool_start() binds its tool_call_id to the segment streamed
  since the previous tool, or to None if that step streamed no thinking.
  Each start is bound separately: an id repeated across steps (agents derive
  ids deterministically when providers omit them) keeps one binding per start,
  and settlement consumes them in step order.
  A visible interim message (on_interim_assistant()) also closes its step:
  the open segment is bound to that message's text, so the next tool call
  cannot claim it. Settlement resolves a tool-call step through its call ids:
  from tool_calls, else from the following tool results' tool_call_id,
  else from the next unclaimed live tool starts in order. A step with
  commentary can also resolve through its interim binding. Other
  steps are matched to interim bindings by their content, in order. The final
  step takes the segment still open at settlement. The positional index is
  used only when there are no bindings, as with older agents that lack
  tool_start_callback. It is not authoritative on its own: it advances
  only at a tool boundary that already holds reasoning, so with
  adaptive-thinking models segment k can hold step k+1's trace.
• Inline `` blocks in the content are always split into reasoning
  and merged with the value chosen above.

Regression coverage: tests/test_settlement_agent_reasoning_authoritative.py.

Heartbeats and proxy behavior Copy Chapter

• All long-lived streams emit SSE keepalive comment lines on the
  _SSE_HEARTBEAT_INTERVAL_SECONDS cadence (currently 5 seconds), which is
  short enough to survive typical reverse-proxy idle timeouts.
• Handlers send X-Accel-Buffering: no so nginx-style proxies pass events
  through unbuffered.
• Deployments behind buffering proxies that read-until-close (notably
  Tornado-based jupyter-server-proxy) can set HERMES_WEBUI_SSE_CHUNKED=1
  to frame each event as an HTTP/1.1 chunk. The default wire format is
  unchanged when the flag is unset.

Supervisor (`docs/supervisor.md`) Copy Section

Running Hermes Web UI under a process supervisor

Use a process supervisor (launchd, systemd, supervisord, runit, s6) when you
want the Web UI to start at boot, restart on crash, or be managed alongside
other services.

TL;DR Copy Chapter

Pass --foreground to bootstrap.py (or bash start.sh):

bash start.sh --foreground

Or set HERMES_WEBUI_FOREGROUND=1 in the environment. The Web UI will
auto-detect launchd / systemd / supervisord even without the flag, but being
explicit is safer.

Important (launchd on macOS): if the com.parantoux.hermes-webui LaunchAgent is enabled, treat launchd as the single source of truth for WebUI lifecycle. Do not also run ./ctl.sh start, bash start.sh, python bootstrap.py, or python server.py against the same state dir/port, or you can create a second WebUI instance and trigger port-8787 restart churn.

Why ``--foreground`` matters Copy Chapter

Without it, bootstrap.py does this:

1. Spawn server.py as a detached subprocess (start_new_session=True)
2. Probe /health until the server is up
3. Exit 0

That works for an interactive shell run (./start.sh returns to your
prompt with the server alive in the background). It is broken under any
process supervisor: the supervisor sees its tracked PID exit, marks the job
as completed, and respawns bootstrap.py. The respawn fails to bind port
8787 (the orphaned server still has it), exits non-zero, supervisor
respawns again — loop.

In foreground mode, bootstrap.py does its setup work and then calls
os.execv to replace its own process with server.py. The supervisor
sees the long-lived server as the original child. KeepAlive=true /
Restart=always work correctly.

launchd (macOS) Copy Chapter

~/Library/LaunchAgents/com.example.hermes-webui.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.example.hermes-webui</string>

    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>/Users/yourname/hermes-webui/start.sh</string>
        <string>--foreground</string>
    </array>

    <key>WorkingDirectory</key>
    <string>/Users/yourname/hermes-webui</string>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/Users/yourname/.hermes/webui/launchd-stdout.log</string>

    <key>StandardErrorPath</key>
    <string>/Users/yourname/.hermes/webui/launchd-stderr.log</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>HOME</key>
        <string>/Users/yourname</string>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin</string>
    </dict>
</dict>
</plist>

Load:

launchctl load ~/Library/LaunchAgents/com.example.hermes-webui.plist
launchctl print gui/$(id -u)/com.example.hermes-webui   # check state

Reload after editing the plist:

launchctl unload ~/Library/LaunchAgents/com.example.hermes-webui.plist
launchctl load   ~/Library/LaunchAgents/com.example.hermes-webui.plist

launchd sets XPC_SERVICE_NAME automatically, so even without the
--foreground argument the Web UI will auto-promote to foreground mode.
The flag is still recommended as documentation of intent.

systemd (Linux) Copy Chapter

~/.config/systemd/user/hermes-webui.service:

[Unit]
Description=Hermes Web UI
After=network.target

[Service]
Type=simple
WorkingDirectory=%h/hermes-webui
ExecStart=/bin/bash %h/hermes-webui/start.sh --foreground
Restart=on-failure
RestartSec=5

# Optional: route stdout/stderr to journald instead of files
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

Enable + start:

systemctl --user daemon-reload
systemctl --user enable --now hermes-webui.service
journalctl --user -u hermes-webui.service -f

systemd sets INVOCATION_ID and JOURNAL_STREAM (when stdio is wired to
the journal), both of which auto-promote to foreground mode.

supervisord (cross-platform) Copy Chapter

/etc/supervisor/conf.d/hermes-webui.conf:

[program:hermes-webui]
command=/bin/bash /home/youruser/hermes-webui/start.sh --foreground
directory=/home/youruser/hermes-webui
user=youruser
autostart=true
autorestart=true
stopsignal=TERM
stopwaitsecs=10
stdout_logfile=/var/log/hermes-webui.out.log
stderr_logfile=/var/log/hermes-webui.err.log
environment=HOME="/home/youruser",PATH="/usr/local/bin:/usr/bin:/bin"

Reload + start:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status hermes-webui

supervisord sets SUPERVISOR_ENABLED, which auto-promotes to foreground
mode.

Auto-detected env vars (full list) Copy Chapter

These trigger --foreground behavior even when the flag is not passed:

XPC_SERVICE_NAME noise filter Copy Section

macOS launchd sets XPC_SERVICE_NAME in every Terminal-spawned shell,
not just real services. Typical noise values:

• 0 — set on launchd descendants generally
• application.com.apple.Terminal. — Terminal.app shells
• application.com.googlecode.iterm2 — iTerm2
• application.com.microsoft.VSCode — VSCode integrated terminal

A bare existence check on this var would auto-promote interactive
./start.sh runs to foreground mode on every Mac dev machine, breaking
the most common installation path. We narrow detection to launchd
Label-style names (typically reverse-DNS like com.example.foo).
Real launchd plists always use this form. If you ever see
XPC_SERVICE_NAME=0 in your service environment, the auto-detect will
ignore it — set HERMES_WEBUI_FOREGROUND=1 or pass --foreground
explicitly to be safe.

Supervisors that are NOT auto-detected Copy Section

The following set no env var that we can reliably detect. Pass
--foreground (or HERMES_WEBUI_FOREGROUND=1) explicitly:

• runit (without sd_notify) — pure runit chains
• daemontools / svc
• PM2 (Node.js process manager occasionally repurposed for Python)
• Foreman / Honcho (Procfile-style)
• Docker with a custom CMD entrypoint that doesn't already use exec
• Custom shell-script supervisors that fork-and-wait

If your supervisor isn't in the auto-detect list and you see the orphan-PID
respawn loop, set HERMES_WEBUI_FOREGROUND=1 in the service environment.

Diagnostic recipe Copy Chapter

If the Web UI keeps getting respawned and you suspect the double-fork loop:

# Check the running PID for the server
lsof -iTCP:8787 -sTCP:LISTEN

# Get its parent — should be the supervisor itself, NOT init (PID 1)
PID=$(lsof -tiTCP:8787 -sTCP:LISTEN)
ps -p "$PID" -o pid,ppid,cmd
ps -p "$(ps -o ppid= -p "$PID" | tr -d ' ')" -o pid,cmd

A healthy foreground-mode setup looks like:

PID    PPID  CMD
12345  6789  /path/to/python /path/to/server.py
6789   1     /sbin/launchd        # or /usr/lib/systemd/systemd, etc.

If PPID is 1 (init) when it should be the supervisor, the orphan-server
loop is happening — re-check that --foreground (or one of the env vars)
is reaching the process.

HTTP watchdog / deep health Copy Chapter

KeepAlive / Restart=always only recover a process that exits. If the
process is still listening on the port but request handling is wedged, pair your
supervisor with an HTTP probe and force a restart when the probe fails.

Hermes Web UI exposes two health levels:

• /health — cheap liveness probe with active_streams, uptime, and an
  accept_loop heartbeat counter.
• /health?deep=1 — readiness probe that briefly acquires the stream lock,
  reads the sidebar/session path, reads projects state, and touches Hermes
  state.db if it exists. Use this for watchdogs.

At startup the server also tries to raise its file-descriptor soft limit to
4096 on platforms that support RLIMIT_NOFILE. That is defense in depth for
persistent hosts: leaks should still be fixed, but a higher soft limit gives
you more diagnostic headroom before request handling falls over.

Minimal macOS launchd watchdog script:

#!/usr/bin/env bash
set -euo pipefail
LABEL="com.example.hermes-webui"
BASE="http://127.0.0.1:8787"

if ! curl -fsS --max-time 10 "$BASE/health?deep=1" >/dev/null; then
  launchctl kickstart -k "gui/$(id -u)/$LABEL"
fi

Run it every few minutes from a separate StartInterval LaunchAgent. For
systemd, prefer a timer/service pair that runs the same curl probe and
systemctl --user restart hermes-webui.service on failure.

The accept_loop.requests_total value should increase when probes arrive. If
it stays flat while the process is still alive, the server accept loop is not
making progress; capture logs/thread samples before restarting if you are
collecting diagnostics for a bug report.

Troubleshooting (`docs/troubleshooting.md`) Copy Section

Troubleshooting

Concrete diagnostic flows for the most common failure modes when running Hermes WebUI. Each entry has the symptom, the diagnostic commands you should run before opening an issue, and the fix that has worked for past reporters.

If your symptom isn't listed and the diagnostics don't narrow it down, file a bug at https://github.com/nesquena/hermes-webui/issues — include the relevant command output after redacting secrets, private paths, full .env files, full auth.json files, cookies, tokens, and password hashes.

Requests succeed but access records disappear during agent work Copy Chapter

The server emits [webui] JSON access records to its original process stdout,
using a private duplicate captured before agent imports. This keeps request and
HTTP error logs visible when an in-process tool redirects or closes sys.stdout.
Logging failures still must not interrupt HTTP responses.

Check the service's captured stdout (for example, docker logs <container> or
the journal for your WebUI unit). Verify successful POST /api/chat/start and
GET /api/chat/stream records, not only health probes or rejected requests.
Records include method, path, status, and ms: elapsed time until response
headers, not the lifetime of an SSE stream or the agent turn. A missing record
before response headers does not distinguish a pending request from a logging
failure. Keep the launcher's output destination open for the process lifetime.

Scheduled cron execution belongs to the Hermes Agent gateway scheduler, not the
WebUI HTTP server. Investigate cron outcomes in the gateway's logs and the
active Hermes home's cron/executions.db; WebUI access records show HTTP cron
management requests, not every scheduled execution.

"AIAgent not available -- check that hermes-agent is on sys.path" Copy Chapter

Symptom. WebUI starts, shows the chat interface, but every chat request fails immediately with this error in the response or the server log. As of v0.51.6 the error includes a diagnostic block with the running Python interpreter, the relevant sys.path entries, and the most-common fix; on older versions the message is bare.

Why it happens. The WebUI imports the agent class at chat time via from run_agent import AIAgent. That import only succeeds if the running Python's sys.path contains either the hermes-agent checkout or a pip-installed copy of the agent. Four common failure modes:

1. Agent installed but not on sys.path. Most common. The agent is checked out somewhere (e.g. ~/Programmes/hermes-agent), the WebUI was launched with a Python that doesn't know about it, and there's no pip install -e . linking the two.
2. Symlink with a typo or wrong target. A symlink to the agent looks correct on ls, but readlink resolves to a path that doesn't exist or doesn't contain agent/__init__.py.
3. HERMES_WEBUI_AGENT_DIR set to the wrong directory. Override env var beats auto-discovery and points at a directory that has no agent code.
4. Agent installed as root, under the FHS layout. When the Hermes Agent installer runs as root on Linux it places the agent at /usr/local/lib/hermes-agent (CLI linked into /usr/local/bin), not ~/.hermes/hermes-agent. Older bootstrap.py didn't probe that path, so it built a WebUI-only .venv and failed at launch with "Python environment cannot import both WebUI dependencies and Hermes Agent." git pull to update the WebUI (current bootstrap.py auto-discovers the FHS layout and follows the hermes launcher to the agent), and let the launcher pick the interpreter: when relaunch is enabled (the default: HERMES_DISABLE_LAZY_INSTALLS unset, updateMechanism=self, checkout with .git/pyproject.toml), launch preparation re-exec's a non-store interpreter into the store python before activation, so leaving HERMES_WEBUI_PYTHON unset lands on the managed interpreter. When the service suppresses relaunch instead, no re-exec corrects the seed interpreter, and an unset override falls through discover_launcher_python() to whatever non-managed python it finds (agent_dir/venv/bin/python if it exists, else the WebUI .venv, else system python3) — every turn then fails while the pre-flight check still passes. Those services must resolve the store python fresh at every start and export it as HERMES_WEBUI_PYTHON (see step 2) — never the in-tree venv, and never a saved path of any kind — see Hermes package-managed runtime bootstrap order.