diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md index 07a2f76eb8..7086f07030 100644 --- a/website/docs/reference/cli-commands.md +++ b/website/docs/reference/cli-commands.md @@ -57,6 +57,7 @@ hermes [global-options] [subcommand/options] | `hermes sessions` | Browse, export, prune, rename, and delete sessions. | | `hermes insights` | Show token/cost/activity analytics. | | `hermes claw` | OpenClaw migration helpers. | +| `hermes web` | Launch the web dashboard for managing config, API keys, and sessions. | | `hermes profile` | Manage profiles — multiple isolated Hermes instances. | | `hermes completion` | Print shell completion scripts (bash/zsh). | | `hermes version` | Show version information. | @@ -701,6 +702,28 @@ hermes claw migrate --preset user-data --overwrite hermes claw migrate --source /home/user/old-openclaw ``` +## `hermes web` + +```bash +hermes web [options] +``` + +Launch the web dashboard — a browser-based UI for managing configuration, API keys, and monitoring sessions. Requires `pip install hermes-agent[web]` (FastAPI + Uvicorn). See [Web Dashboard](/docs/user-guide/features/web-dashboard) for full documentation. + +| Option | Default | Description | +|--------|---------|-------------| +| `--port` | `9119` | Port to run the web server on | +| `--host` | `127.0.0.1` | Bind address | +| `--no-open` | — | Don't auto-open the browser | + +```bash +# Default — opens browser to http://127.0.0.1:9119 +hermes web + +# Custom port, no browser +hermes web --port 8080 --no-open +``` + ## `hermes profile` ```bash diff --git a/website/docs/reference/slash-commands.md b/website/docs/reference/slash-commands.md index a695d8dc12..1d9aebd463 100644 --- a/website/docs/reference/slash-commands.md +++ b/website/docs/reference/slash-commands.md @@ -63,6 +63,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in | `/skills` | Search, install, inspect, or manage skills from online registries | | `/cron` | Manage scheduled tasks (list, add/create, edit, pause, resume, run, remove) | | `/reload-mcp` (alias: `/reload_mcp`) | Reload MCP servers from config.yaml | +| `/reload` | Reload `.env` variables into the running session (picks up new API keys without restarting) | | `/plugins` | List installed plugins and their status | ### Info @@ -133,6 +134,7 @@ The messaging gateway supports the following built-in commands inside Telegram, | `/background ` | Run a prompt in a separate background session. Results are delivered back to the same chat when the task finishes. See [Messaging Background Sessions](/docs/user-guide/messaging/#background-sessions). | | `/plan [request]` | Load the bundled `plan` skill to write a markdown plan instead of executing the work. Plans are saved under `.hermes/plans/` relative to the active workspace/backend working directory. | | `/reload-mcp` (alias: `/reload_mcp`) | Reload MCP servers from config. | +| `/reload` | Reload `.env` variables into the running session. | | `/yolo` | Toggle YOLO mode — skip all dangerous command approval prompts. | | `/commands [page]` | Browse all commands and skills (paginated). | | `/approve [session\|always]` | Approve and execute a pending dangerous command. `session` approves for this session only; `always` adds to permanent allowlist. | diff --git a/website/docs/user-guide/features/web-dashboard.md b/website/docs/user-guide/features/web-dashboard.md new file mode 100644 index 0000000000..7c01070307 --- /dev/null +++ b/website/docs/user-guide/features/web-dashboard.md @@ -0,0 +1,192 @@ +--- +sidebar_position: 15 +title: "Web Dashboard" +description: "Browser-based dashboard for managing configuration, API keys, and monitoring sessions" +--- + +# Web Dashboard + +The web dashboard is a browser-based UI for managing your Hermes Agent installation. Instead of editing YAML files or running CLI commands, you can configure settings, manage API keys, and monitor sessions from a clean web interface. + +## Quick Start + +```bash +hermes web +``` + +This starts a local web server and opens `http://127.0.0.1:9119` in your browser. The dashboard runs entirely on your machine — no data leaves localhost. + +### Options + +| Flag | Default | Description | +|------|---------|-------------| +| `--port` | `9119` | Port to run the web server on | +| `--host` | `127.0.0.1` | Bind address | +| `--no-open` | — | Don't auto-open the browser | + +```bash +# Custom port +hermes web --port 8080 + +# Bind to all interfaces (use with caution on shared networks) +hermes web --host 0.0.0.0 + +# Start without opening browser +hermes web --no-open +``` + +## Prerequisites + +The web dashboard requires FastAPI and Uvicorn. Install them with: + +```bash +pip install hermes-agent[web] +``` + +If you installed with `pip install hermes-agent[all]`, the web dependencies are already included. + +When you run `hermes web` without the dependencies, it will tell you what to install. If the frontend hasn't been built yet and `npm` is available, it builds automatically on first launch. + +## Pages + +### Status + +The landing page shows a live overview of your installation: + +- **Agent version** and release date +- **Gateway status** — running/stopped, PID, connected platforms and their state +- **Active sessions** — count of sessions active in the last 5 minutes +- **Recent sessions** — list of the 20 most recent sessions with model, message count, token usage, and a preview of the conversation + +The status page auto-refreshes every 5 seconds. + +### Config + +A form-based editor for `config.yaml`. All 150+ configuration fields are auto-discovered from `DEFAULT_CONFIG` and organized into tabbed categories: + +- **model** — default model, provider, base URL, reasoning settings +- **terminal** — backend (local/docker/ssh/modal), timeout, shell preferences +- **display** — skin, tool progress, resume display, spinner settings +- **agent** — max iterations, gateway timeout, service tier +- **delegation** — subagent limits, reasoning effort +- **memory** — provider selection, context injection settings +- **approvals** — dangerous command approval mode (ask/yolo/deny) +- And more — every section of config.yaml has corresponding form fields + +Fields with known valid values (terminal backend, skin, approval mode, etc.) render as dropdowns. Booleans render as toggles. Everything else is a text input. + +**Actions:** + +- **Save** — writes changes to `config.yaml` immediately +- **Reset to defaults** — reverts all fields to their default values (doesn't save until you click Save) +- **Export** — downloads the current config as JSON +- **Import** — uploads a JSON config file to replace the current values + +:::tip +Config changes take effect on the next agent session or gateway restart. The web dashboard edits the same `config.yaml` file that `hermes config set` and the gateway read from. +::: + +### API Keys + +Manage the `.env` file where API keys and credentials are stored. Keys are grouped by category: + +- **LLM Providers** — OpenRouter, Anthropic, OpenAI, DeepSeek, etc. +- **Tool API Keys** — Browserbase, Firecrawl, Tavily, ElevenLabs, etc. +- **Messaging Platforms** — Telegram, Discord, Slack bot tokens, etc. +- **Agent Settings** — non-secret env vars like `API_SERVER_ENABLED` + +Each key shows: +- Whether it's currently set (with a redacted preview of the value) +- A description of what it's for +- A link to the provider's signup/key page +- An input field to set or update the value +- A delete button to remove it + +Advanced/rarely-used keys are hidden by default behind a toggle. + +:::warning Security +The web dashboard reads and writes your `.env` file, which contains API keys and secrets. It binds to `127.0.0.1` by default — only accessible from your local machine. If you bind to `0.0.0.0`, anyone on your network can view and modify your credentials. The dashboard has no authentication of its own. +::: + +## `/reload` Slash Command + +The dashboard PR also adds a `/reload` slash command to the interactive CLI. After changing API keys via the web dashboard (or by editing `.env` directly), use `/reload` in an active CLI session to pick up the changes without restarting: + +``` +You → /reload + Reloaded .env (3 var(s) updated) +``` + +This re-reads `~/.hermes/.env` into the running process's environment. Useful when you've added a new provider key via the dashboard and want to use it immediately. + +## REST API + +The web dashboard exposes a REST API that the frontend consumes. You can also call these endpoints directly for automation: + +### GET /api/status + +Returns agent version, gateway status, platform states, and active session count. + +### GET /api/sessions + +Returns the 20 most recent sessions with metadata (model, token counts, timestamps, preview). + +### GET /api/config + +Returns the current `config.yaml` contents as JSON. + +### GET /api/config/defaults + +Returns the default configuration values. + +### GET /api/config/schema + +Returns a schema describing every config field — type, description, category, and select options where applicable. The frontend uses this to render the correct input widget for each field. + +### PUT /api/config + +Saves a new configuration. Body: `{"config": {...}}`. + +### GET /api/env + +Returns all known environment variables with their set/unset status, redacted values, descriptions, and categories. + +### PUT /api/env + +Sets an environment variable. Body: `{"key": "VAR_NAME", "value": "secret"}`. + +### DELETE /api/env + +Removes an environment variable. Body: `{"key": "VAR_NAME"}`. + +## CORS + +The web server restricts CORS to localhost origins only: + +- `http://localhost:9119` / `http://127.0.0.1:9119` (production) +- `http://localhost:3000` / `http://127.0.0.1:3000` +- `http://localhost:5173` / `http://127.0.0.1:5173` (Vite dev server) + +If you run the server on a custom port, that origin is added automatically. + +## Development + +If you're contributing to the web dashboard frontend: + +```bash +# Terminal 1: start the backend API +hermes web --no-open + +# Terminal 2: start the Vite dev server with HMR +cd web/ +npm install +npm run dev +``` + +The Vite dev server at `http://localhost:5173` proxies `/api` requests to the FastAPI backend at `http://127.0.0.1:9119`. + +The frontend is built with React 19, TypeScript, Tailwind CSS v4, and shadcn/ui-style components. Production builds output to `hermes_cli/web_dist/` which the FastAPI server serves as a static SPA. + +## Automatic Build on Update + +When you run `hermes update`, the web frontend is automatically rebuilt if `npm` is available. This keeps the dashboard in sync with code updates. If `npm` isn't installed, the update skips the frontend build and `hermes web` will build it on first launch. diff --git a/website/sidebars.ts b/website/sidebars.ts index 973cfe89cb..eb695657a4 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -73,6 +73,13 @@ const sidebars: SidebarsConfig = { 'user-guide/features/tts', ], }, + { + type: 'category', + label: 'Management', + items: [ + 'user-guide/features/web-dashboard', + ], + }, { type: 'category', label: 'Advanced',