mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-07-04 12:33:08 +00:00
docs: reconcile docs with code across last 3 releases (#54254)
Audited the last 3 releases (v2026.5.28..main) against the docs site and fixed code-vs-docs drift: - slash-commands: add /moa, /prompt, /pet, /hatch, /timestamps - cli-commands: add hermes pets / project / desktop / whatsapp-cloud + dashboard register; correct --insecure (now a deprecated no-op); add gateway migrate-legacy + enroll --wake-url + dashboard --skip-build - environment-variables: document the remaining ~48 env vars (SimpleX, Photon, Teams adapter, per-platform *_ALLOW_ALL_USERS, home-channel vars, IRC, Brave/Krea/Notion/Linear/Airtable/Tenor keys, QQ_SANDBOX) — full OPTIONAL_ENV_VARS (265) now covered - configuration: document tool_loop_guardrails, goals, prompt_caching, network, onboarding, dashboard config blocks - toolsets/tools-reference + tools.md: add coding/project toolsets and read_terminal/project_* tools; remove the stale messaging toolset and send_message agent tool (removed in #47856); drop stale RL-training prose - messaging: new IRC channel page (adapter shipped without docs) + index row + sidebar + env vars - pets: document the /hatch AI generation pipeline + Nous/OpenRouter image backend - web-dashboard: document the bearer-token / TokenPrincipal service auth path - purge agent-callable send_message references across guides/features and the research-paper-writing skill (tool removed in #47856) Verified: docusaurus build succeeds; all authored internal links resolve.
This commit is contained in:
Teknium
GitHub
parent
b699d27a4a
commit
b31b0b9d95
26 changed files with 426 additions and 46 deletions
BIN
infographic/docs-audit-3releases/infographic.png
Normal file
BIN
infographic/docs-audit-3releases/infographic.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.7 MiB |
|
|
@ -2148,7 +2148,7 @@ Compose this skill with other Hermes skills for specific phases:
|
|||
| **`memory`** | Persist key decisions across sessions: contribution framing, venue choice, reviewer feedback. |
|
||||
| **`cronjob`** | Schedule experiment monitoring, deadline countdowns, automated arXiv checks. |
|
||||
| **`clarify`** | Ask the user targeted questions when blocked (venue choice, contribution framing). |
|
||||
| **`send_message`** | Notify user when experiments complete or drafts are ready, even if user isn't in chat. |
|
||||
| **cron `deliver:`** | Notify the user when experiments complete or drafts are ready even if they're not in chat — schedule the check as a cron job with a messaging `deliver:` target (the agent no longer has a `send_message` tool; outbound delivery is handled by cron/`hermes send`). |
|
||||
|
||||
### Tool Usage Patterns
|
||||
|
||||
|
|
@ -2159,7 +2159,7 @@ terminal("ps aux | grep <pattern>")
|
|||
→ terminal("ls results/")
|
||||
→ execute_code("analyze results JSON, compute metrics")
|
||||
→ terminal("git add -A && git commit -m '<descriptive message>' && git push")
|
||||
→ send_message("Experiment complete: <summary>")
|
||||
→ (final response auto-delivers "Experiment complete: <summary>"; for unattended runs, schedule via cron with a deliver: target)
|
||||
```
|
||||
|
||||
**Parallel section drafting** (using delegation):
|
||||
|
|
@ -2259,7 +2259,7 @@ cronjob("create", {
|
|||
|
||||
### Communication Patterns
|
||||
|
||||
**When to notify the user** (via `send_message` or direct response):
|
||||
**When to notify the user** (via your direct/final response, or a cron `deliver:` target for unattended runs):
|
||||
- Experiment batch completed (with results table)
|
||||
- Unexpected finding or failure requiring decision
|
||||
- Draft section ready for review
|
||||
|
|
|
|||
|
|
@ -185,7 +185,7 @@ When you call `ctx.register_platform()`, the following integration points are ha
|
|||
| YAML config bridge | `apply_yaml_config_fn` translates `config.yaml` keys into env vars / extras |
|
||||
| Cron delivery | `cron_deliver_env_var` makes `deliver=<name>` work |
|
||||
| `hermes config` UI entries | `requires_env` / `optional_env` in `plugin.yaml` auto-populate |
|
||||
| send_message tool | Routes through live gateway adapter |
|
||||
| send engine (`tools/send_message_tool.py`) | Routes through live gateway adapter |
|
||||
| Webhook cross-platform delivery | Registry checked for known platforms |
|
||||
| `/update` command access | `allow_update_command` flag |
|
||||
| Channel directory | Plugin platforms included in enumeration |
|
||||
|
|
|
|||
|
|
@ -193,7 +193,7 @@ Outgoing deliveries (`gateway/delivery.py`) handle:
|
|||
|
||||
- **Direct reply** — send response back to the originating chat
|
||||
- **Home channel delivery** — route cron job outputs and background results to a configured home channel
|
||||
- **Explicit target delivery** — `send_message` tool specifying `telegram:-1001234567890`, or the [`hermes send` CLI](/guides/pipe-script-output) wrapping the same tool for shell scripts
|
||||
- **Explicit target delivery** — the send engine specifying `telegram:-1001234567890`, exposed via the [`hermes send` CLI](/guides/pipe-script-output) for shell scripts and via cron `deliver:` targets
|
||||
- **Cross-platform delivery** — deliver to a different platform than the originating message
|
||||
|
||||
Cron job deliveries are NOT mirrored into gateway session history — they live in their own cron session only. This is a deliberate design choice to avoid message alternation violations.
|
||||
|
|
|
|||
|
|
@ -218,7 +218,7 @@ Restricting toolsets keeps the subagent focused and prevents accidental side eff
|
|||
## Constraints
|
||||
|
||||
- **Default 3 parallel tasks**: batches default to 3 concurrent subagents (configurable via `delegation.max_concurrent_children` in config.yaml, no hard ceiling, only a floor of 1)
|
||||
- **Nested delegation is opt-in**: leaf subagents (default) cannot call `delegate_task`, `clarify`, `memory`, `send_message`, or `execute_code`. Orchestrator subagents (`role="orchestrator"`) retain `delegate_task` for further delegation, but only when `delegation.max_spawn_depth` is raised above the default of 1 (floor 1, no ceiling); the other four remain blocked. Disable globally via `delegation.orchestrator_enabled: false`.
|
||||
- **Nested delegation is opt-in**: leaf subagents (default) cannot call `delegate_task`, `clarify`, `memory`, or `execute_code`. Orchestrator subagents (`role="orchestrator"`) retain `delegate_task` for further delegation, but only when `delegation.max_spawn_depth` is raised above the default of 1 (floor 1, no ceiling); the other three remain blocked. Disable globally via `delegation.orchestrator_enabled: false`.
|
||||
|
||||
### Tuning Concurrency and Depth
|
||||
|
||||
|
|
|
|||
|
|
@ -229,11 +229,11 @@ IDs.
|
|||
| `hermes send` | ✅ | ✅ | No (bot-token) | Everything below |
|
||||
| Raw `curl` to each platform | Each scripted separately | Manual | No | Critical watchdogs |
|
||||
| `cron` job with `--deliver` | ✅ | ✅ | No | Scheduled agent tasks |
|
||||
| `send_message` agent tool | ✅ | ✅ | No | Inside an agent loop |
|
||||
|
||||
`hermes send` is intentionally the simplest possible surface. If you need
|
||||
an agent to decide what to say, use the `send_message` tool from within a
|
||||
chat or cron job. If you need a scheduled run with LLM-generated content,
|
||||
an agent to decide what to say, schedule a cron job — the agent's final
|
||||
response is auto-delivered to the configured `deliver:` target (the agent
|
||||
no longer fires messages itself). If you need a scheduled run with LLM-generated content,
|
||||
use `cronjob(action='create', prompt=...)` with `deliver='telegram:...'`.
|
||||
If you just need to pipe a raw string, reach for `hermes send`.
|
||||
|
||||
|
|
|
|||
|
|
@ -46,6 +46,7 @@ hermes [global-options] <command> [subcommand/options]
|
|||
| `hermes lsp` | Manage Language Server Protocol integration (semantic diagnostics for write_file/patch). |
|
||||
| `hermes setup` | Interactive setup wizard for all or part of the configuration. |
|
||||
| `hermes whatsapp` | Configure and pair the WhatsApp bridge. |
|
||||
| `hermes whatsapp-cloud` | Configure the official Meta WhatsApp Business Cloud API adapter (Business account + public webhook required). Distinct from `hermes whatsapp` (Baileys personal-account bridge). |
|
||||
| `hermes slack` | Slack helpers (currently: generate the app manifest with every command as a native slash). |
|
||||
| `hermes auth` | Manage credentials — add, list, remove, reset, status, logout. Handles OAuth flows for Codex/Nous/Anthropic. |
|
||||
| `hermes login` / `logout` | **Deprecated** — use `hermes auth` instead. |
|
||||
|
|
@ -55,6 +56,7 @@ hermes [global-options] <command> [subcommand/options]
|
|||
| `hermes status` | Show agent, auth, and platform status. |
|
||||
| `hermes cron` | Inspect and tick the cron scheduler. |
|
||||
| `hermes kanban` | Multi-profile collaboration board (tasks, links, dispatcher). |
|
||||
| `hermes project` | Manage named, multi-folder workspaces (projects). Anchors desktop session grouping and, when bound to a kanban board, gives tasks a deterministic worktree + branch convention. State is per-profile. |
|
||||
| `hermes webhook` | Manage dynamic webhook subscriptions for event-driven activation. |
|
||||
| `hermes hooks` | Inspect, approve, or remove shell-script hooks declared in `config.yaml`. |
|
||||
| `hermes doctor` | Diagnose config and dependency issues. |
|
||||
|
|
@ -78,10 +80,12 @@ hermes [global-options] <command> [subcommand/options]
|
|||
| `hermes portal` | Nous Portal status, subscription link, and Tool Gateway routing. See [Tool Gateway](../user-guide/features/tool-gateway.md). |
|
||||
| `hermes tools` | Configure enabled tools per platform. |
|
||||
| `hermes computer-use` | Install or check the cua-driver backend (macOS Computer Use). |
|
||||
| `hermes pets` | Browse, install, and select [petdex](../user-guide/features/pets.md) animated pets shown across the CLI, TUI, and desktop app. Subcommands: `list`, `install`, `select`, `show`, `off`, `scale`, `remove`, `doctor`. |
|
||||
| `hermes sessions` | Browse, export, prune, rename, and delete sessions. |
|
||||
| `hermes insights` | Show token/cost/activity analytics. |
|
||||
| `hermes claw` | OpenClaw migration helpers. |
|
||||
| `hermes dashboard` | Launch the web dashboard for managing config, API keys, and sessions. |
|
||||
| `hermes desktop` (alias `gui`) | Build and launch the native Electron desktop app. |
|
||||
| `hermes profile` | Manage profiles — multiple isolated Hermes instances. |
|
||||
| `hermes completion` | Print shell completion scripts (bash/zsh/fish). |
|
||||
| `hermes version` | Show version information. |
|
||||
|
|
@ -226,6 +230,7 @@ Subcommands:
|
|||
| `install` | Install as a systemd (Linux) or launchd (macOS) background service. |
|
||||
| `uninstall` | Remove the installed service. |
|
||||
| `setup` | Interactive messaging-platform setup. |
|
||||
| `migrate-legacy` | Remove legacy `hermes.service` units left over from pre-rename installs. Profile units (`hermes-gateway-<profile>.service`) and unrelated services are never touched. Flags: `--dry-run`, `-y`/`--yes`. |
|
||||
| `enroll` | Experimental: enroll this gateway with a relay connector and save relay credentials for connector-backed platforms. |
|
||||
|
||||
Options:
|
||||
|
|
@ -235,7 +240,7 @@ Options:
|
|||
| `--all` | On `start` / `restart` / `stop`: act on **every profile's** gateway, not just the active `HERMES_HOME`. Useful if you run multiple profiles side-by-side and want to restart them all after `hermes update`. |
|
||||
| `--no-supervise` | On `run`: inside the s6-overlay Docker image, opt out of auto-supervision and use pre-s6 foreground semantics — gateway runs as the container's main process with no auto-restart. No-op outside the s6 image. Equivalent to setting `HERMES_GATEWAY_NO_SUPERVISE=1`. |
|
||||
|
||||
`hermes gateway enroll` accepts `--token`, `--connector-url`, and `--gateway-id`. It exchanges the enrollment token with the connector and writes the resulting `GATEWAY_RELAY_ID`, `GATEWAY_RELAY_SECRET`, `GATEWAY_RELAY_DELIVERY_KEY`, and optional `GATEWAY_RELAY_URL` values to the active profile's `.env`.
|
||||
`hermes gateway enroll` accepts `--token`, `--connector-url`, `--gateway-id`, and `--wake-url`. It exchanges the enrollment token with the connector and writes the resulting `GATEWAY_RELAY_ID`, `GATEWAY_RELAY_SECRET`, `GATEWAY_RELAY_DELIVERY_KEY`, optional `GATEWAY_RELAY_URL`, and (when `--wake-url` is given) `GATEWAY_RELAY_WAKE_URL` values to the active profile's `.env`.
|
||||
|
||||
:::tip WSL users
|
||||
Use `hermes gateway run` instead of `hermes gateway start` — WSL's systemd support is unreliable. Wrap it in tmux for persistence: `tmux new -s hermes 'hermes gateway run'`. See [WSL FAQ](/reference/faq#wsl-gateway-keeps-disconnecting-or-hermes-gateway-start-fails) for details.
|
||||
|
|
@ -613,6 +618,28 @@ All actions are also available as a slash command in the gateway (`/kanban …`)
|
|||
|
||||
For the full design — comparison with Cline Kanban / Paperclip / NanoClaw / Gemini Enterprise, eight collaboration patterns, four user stories, concurrency correctness proof — see `docs/hermes-kanban-v1-spec.pdf` in the repository or the [Kanban user guide](/user-guide/features/kanban).
|
||||
|
||||
## `hermes project`
|
||||
|
||||
```bash
|
||||
hermes project <create|list|show|add-folder|remove-folder|rename|set-primary|use|archive|restore|bind-board>
|
||||
```
|
||||
|
||||
Projects are human-named workspaces that can span multiple folders / repos. They anchor desktop session grouping and, when bound to a kanban board, give tasks a deterministic worktree + branch convention. State is per-profile.
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `create` | Create a new project. |
|
||||
| `list` (alias `ls`) | List projects. |
|
||||
| `show` | Show a project's details. |
|
||||
| `add-folder` | Add a folder / repo to a project. |
|
||||
| `remove-folder` | Remove a folder from a project. |
|
||||
| `rename` | Rename a project. |
|
||||
| `set-primary` | Set the primary folder. |
|
||||
| `use` | Set the active project. |
|
||||
| `archive` | Archive a project (recoverable). |
|
||||
| `restore` | Restore an archived project. |
|
||||
| `bind-board` | Bind a kanban board to this project. |
|
||||
|
||||
## `hermes webhook`
|
||||
|
||||
```bash
|
||||
|
|
@ -1299,6 +1326,27 @@ of the update if cua-driver is on PATH, so most users will not need to
|
|||
call `--upgrade` manually. Use it when upstream ships a fix you want
|
||||
right now without waiting for the next Hermes update.
|
||||
|
||||
## `hermes pets`
|
||||
|
||||
```bash
|
||||
hermes pets <list|install|select|show|off|scale|remove|doctor>
|
||||
```
|
||||
|
||||
[Petdex](https://github.com/crafter-station/petdex) is a public gallery of animated sprite pets for coding agents. Install one and Hermes shows it reacting to agent activity across the CLI, TUI, and desktop app.
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `list` | Browse the petdex gallery. |
|
||||
| `install` | Install a pet from the gallery. |
|
||||
| `select` | Set the active pet (writes `display.pet.*`). |
|
||||
| `show` | Animate the active pet in the terminal. |
|
||||
| `off` | Disable the pet display. |
|
||||
| `scale` | Resize the pet everywhere (`display.pet.scale`). |
|
||||
| `remove` | Delete an installed pet. |
|
||||
| `doctor` | Check pet setup + terminal graphics support. |
|
||||
|
||||
You can also generate a brand-new pet from a text description with the `/hatch` slash command. See [Pets](../user-guide/features/pets.md).
|
||||
|
||||
## `hermes sessions`
|
||||
|
||||
```bash
|
||||
|
|
@ -1392,11 +1440,22 @@ Launch the web dashboard — a browser-based UI for managing configuration, API
|
|||
| `--port` | `9119` | Port to run the web server on |
|
||||
| `--host` | `127.0.0.1` | Bind address |
|
||||
| `--no-open` | — | Don't auto-open the browser |
|
||||
| `--insecure` | off | Allow binding to non-localhost hosts. Exposes dashboard credentials on the network; use only behind trusted network controls. |
|
||||
| `--insecure` | off | **Deprecated / no-op.** Formerly bypassed auth on a non-loopback bind. Since the June 2026 hardening a public bind *always* requires an auth provider (password or OAuth). Bind `127.0.0.1` and tunnel to keep it local. |
|
||||
| `--skip-build` | off | Skip the web UI build step and serve the existing `dist` directly. Useful for non-interactive contexts (Windows Scheduled Tasks, CI) where npm isn't available. Pre-build with `cd web && npm run build`. |
|
||||
| `--isolated` | off | When launched from a named profile (`worker dashboard`), run a dedicated per-profile server instead of routing to the machine dashboard. |
|
||||
| `--stop` | — | Stop running `hermes dashboard` processes and exit. |
|
||||
| `--status` | — | List running `hermes dashboard` processes and exit. |
|
||||
|
||||
### `hermes dashboard register`
|
||||
|
||||
Register this install as a self-hosted dashboard with your Nous Portal account. Creates an OAuth client, writes `HERMES_DASHBOARD_OAUTH_CLIENT_ID` into `~/.hermes/.env`, and prints how to engage the login gate. Requires being logged in (`hermes setup`).
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--name` | Human-readable label for the dashboard (default: auto-generated). |
|
||||
| `--redirect-uri` | Public HTTPS OAuth redirect URI (e.g. `https://hermes.example.com/auth/callback`). Omit for localhost-only use. |
|
||||
| `--portal-url` | Override the Nous Portal base URL for registration (default: the portal you logged into). Also settable via `HERMES_DASHBOARD_PORTAL_URL`. |
|
||||
|
||||
```bash
|
||||
# Default — opens browser to http://127.0.0.1:9119
|
||||
hermes dashboard
|
||||
|
|
|
|||
|
|
@ -134,6 +134,7 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe
|
|||
| `SEARXNG_URL` | SearXNG instance URL for free self-hosted web search — no API key required ([searxng.github.io](https://searxng.github.io/searxng/)) |
|
||||
| `TAVILY_BASE_URL` | Override the Tavily API endpoint. Useful for corporate proxies and self-hosted Tavily-compatible search backends. Same pattern as `GROQ_BASE_URL`. |
|
||||
| `EXA_API_KEY` | Exa API key for AI-native web search and contents ([exa.ai](https://exa.ai/)) |
|
||||
| `BRAVE_SEARCH_API_KEY` | Brave Search API subscription token for web search (free tier available) ([brave.com/search/api](https://brave.com/search/api/)) |
|
||||
| `BROWSERBASE_API_KEY` | Browser automation ([browserbase.com](https://browserbase.com/)) |
|
||||
| `BROWSERBASE_PROJECT_ID` | Browserbase project ID |
|
||||
| `BROWSER_USE_API_KEY` | Browser Use cloud browser API key ([browser-use.com](https://browser-use.com/)) |
|
||||
|
|
@ -145,7 +146,9 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe
|
|||
| `CAMOFOX_ADOPT_EXISTING_TAB` | Set to `true` to reuse an existing Camofox tab before creating a new one |
|
||||
| `BROWSER_INACTIVITY_TIMEOUT` | Browser session inactivity timeout in seconds |
|
||||
| `AGENT_BROWSER_ARGS` | Extra Chromium launch flags (comma- or newline-separated). Hermes auto-injects `--no-sandbox,--disable-dev-shm-usage` when running as root or on AppArmor-restricted unprivileged user namespaces (Ubuntu 23.10+, DGX Spark, many container images); set this manually only to override or add other flags. |
|
||||
| `AGENT_BROWSER_ENGINE` | Browser engine for local mode: `auto` (default — Chromium-family via CDP), or a specific engine override. |
|
||||
| `FAL_KEY` | Image generation ([fal.ai](https://fal.ai/)) |
|
||||
| `KREA_API_KEY` | Krea API key for Krea 2 image generation ([krea.ai](https://krea.ai/)) |
|
||||
| `GROQ_API_KEY` | Groq Whisper STT API key ([groq.com](https://groq.com/)) |
|
||||
| `ELEVENLABS_API_KEY` | ElevenLabs premium TTS voices ([elevenlabs.io](https://elevenlabs.io/)) |
|
||||
| `STT_GROQ_MODEL` | Override the Groq STT model (default: `whisper-large-v3-turbo`) |
|
||||
|
|
@ -159,6 +162,17 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe
|
|||
| `SUPERMEMORY_API_KEY` | Semantic long-term memory with profile recall and session ingest ([supermemory.ai](https://supermemory.ai)) |
|
||||
| `DAYTONA_API_KEY` | Daytona cloud sandboxes ([daytona.io](https://daytona.io/)) |
|
||||
|
||||
### Skill API Keys
|
||||
|
||||
Secrets consumed by specific bundled / optional skills. Each is only needed if you use the corresponding skill.
|
||||
|
||||
| Variable | Used by skill | Description |
|
||||
|----------|---------------|-------------|
|
||||
| `NOTION_API_KEY` | `notion` | Notion integration token. |
|
||||
| `LINEAR_API_KEY` | `linear` | Linear personal API key. |
|
||||
| `AIRTABLE_API_KEY` | `airtable` | Airtable personal access token. |
|
||||
| `TENOR_API_KEY` | `gif-search` | Tenor API key for GIF search. |
|
||||
|
||||
### Langfuse Observability
|
||||
|
||||
Environment variables for the bundled [`observability/langfuse`](/user-guide/features/built-in-plugins#observabilitylangfuse) plugin. Set these in `~/.hermes/.env`. The plugin must also be enabled (`hermes plugins enable observability/langfuse`, or check the box in `hermes plugins`) before any of these take effect.
|
||||
|
|
@ -240,6 +254,7 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI
|
|||
|----------|-------------|
|
||||
| `TELEGRAM_BOT_TOKEN` | Telegram bot token (from @BotFather) |
|
||||
| `TELEGRAM_ALLOWED_USERS` | Comma-separated user IDs allowed to use the bot (applies to DMs, groups, and forums) |
|
||||
| `TELEGRAM_ALLOW_ALL_USERS` | Allow any Telegram user to trigger the bot (dev only). |
|
||||
| `TELEGRAM_GROUP_ALLOWED_USERS` | Comma-separated sender user IDs authorized in groups/forums only (does NOT grant DM access). Chat-ID-shaped values (starting with `-`) are still honored as chat IDs for backward compat with pre-#17686 configs, with a deprecation warning. |
|
||||
| `TELEGRAM_GROUP_ALLOWED_CHATS` | Comma-separated group/forum chat IDs; any member is authorized |
|
||||
| `TELEGRAM_HOME_CHANNEL` | Default Telegram chat/channel for cron delivery |
|
||||
|
|
@ -257,6 +272,7 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI
|
|||
| `TELEGRAM_PROXY` | Proxy URL for Telegram connections — overrides `HTTPS_PROXY`. Supports `http://`, `https://`, `socks5://` |
|
||||
| `DISCORD_BOT_TOKEN` | Discord bot token |
|
||||
| `DISCORD_ALLOWED_USERS` | Comma-separated Discord user IDs allowed to use the bot |
|
||||
| `DISCORD_ALLOW_ALL_USERS` | Allow any Discord user to trigger the bot (dev only). |
|
||||
| `DISCORD_ALLOWED_ROLES` | Comma-separated Discord role IDs allowed to use the bot (OR with `DISCORD_ALLOWED_USERS`). Auto-enables the Members intent. Useful when moderation teams churn — role grants propagate automatically. |
|
||||
| `DISCORD_ALLOWED_CHANNELS` | Comma-separated Discord channel IDs. When set, the bot only responds in these channels (plus DMs if allowed). Overrides `config.yaml` `discord.allowed_channels`. |
|
||||
| `DISCORD_PROXY` | Proxy URL for Discord connections — overrides `HTTPS_PROXY`. Supports `http://`, `https://`, `socks5://` |
|
||||
|
|
@ -279,6 +295,7 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI
|
|||
| `SLACK_BOT_TOKEN` | Slack bot token (`xoxb-...`) |
|
||||
| `SLACK_APP_TOKEN` | Slack app-level token (`xapp-...`, required for Socket Mode) |
|
||||
| `SLACK_ALLOWED_USERS` | Comma-separated Slack user IDs |
|
||||
| `SLACK_ALLOW_ALL_USERS` | Allow any Slack user to trigger the bot (dev only). |
|
||||
| `SLACK_HOME_CHANNEL` | Default Slack channel for cron delivery |
|
||||
| `SLACK_HOME_CHANNEL_NAME` | Display name for the Slack home channel |
|
||||
| `GOOGLE_CHAT_PROJECT_ID` | GCP project hosting the Pub/Sub topic (falls back to `GOOGLE_CLOUD_PROJECT`) |
|
||||
|
|
@ -296,6 +313,8 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI
|
|||
| `WHATSAPP_MODE` | `bot` (separate number) or `self-chat` (message yourself) |
|
||||
| `WHATSAPP_ALLOWED_USERS` | Comma-separated phone numbers (with country code, no `+`), or `*` to allow all senders |
|
||||
| `WHATSAPP_ALLOW_ALL_USERS` | Allow all WhatsApp senders without an allowlist (`true`/`false`) |
|
||||
| `WHATSAPP_HOME_CHANNEL` | Default chat ID for cron / notification delivery. |
|
||||
| `WHATSAPP_HOME_CHANNEL_NAME` | Display name for the WhatsApp home channel. |
|
||||
| `WHATSAPP_DEBUG` | Log raw message events in the bridge for troubleshooting (`true`/`false`) |
|
||||
| `WHATSAPP_CLOUD_PHONE_NUMBER_ID` | Meta Phone Number ID from the WhatsApp Business Cloud API (15–17 digits; **not** the phone number itself) |
|
||||
| `WHATSAPP_CLOUD_ACCESS_TOKEN` | Meta access token (starts with `EAA`); temporary tokens expire after 24h, System User tokens are permanent |
|
||||
|
|
@ -346,6 +365,9 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI
|
|||
| `DINGTALK_CLIENT_ID` | DingTalk bot AppKey from developer portal ([open.dingtalk.com](https://open.dingtalk.com)) |
|
||||
| `DINGTALK_CLIENT_SECRET` | DingTalk bot AppSecret from developer portal |
|
||||
| `DINGTALK_ALLOWED_USERS` | Comma-separated DingTalk user IDs allowed to message the bot |
|
||||
| `DINGTALK_WEBHOOK_URL` | Static robot webhook URL for cross-platform / cron delivery. |
|
||||
| `DINGTALK_HOME_CHANNEL` | Default conversation ID for cron / notification delivery. |
|
||||
| `DINGTALK_HOME_CHANNEL_NAME` | Display name for the DingTalk home channel. |
|
||||
| `FEISHU_APP_ID` | Feishu/Lark bot App ID from [open.feishu.cn](https://open.feishu.cn/) |
|
||||
| `FEISHU_APP_SECRET` | Feishu/Lark bot App Secret |
|
||||
| `FEISHU_DOMAIN` | `feishu` (China) or `lark` (international). Default: `feishu` |
|
||||
|
|
@ -356,6 +378,8 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI
|
|||
| `FEISHU_ALLOW_BOTS` | `none` (default) / `mentions` / `all` — accept inbound messages from other bots. See [bot-to-bot messaging](../user-guide/messaging/feishu.md#bot-to-bot-messaging) |
|
||||
| `FEISHU_REQUIRE_MENTION` | `true` (default) / `false` — whether group messages must @mention the bot. Override per-chat via `group_rules.<chat_id>.require_mention`. |
|
||||
| `FEISHU_HOME_CHANNEL` | Feishu chat ID for cron delivery and notifications |
|
||||
| `FEISHU_HOME_CHANNEL_NAME` | Display name for the Feishu home channel. |
|
||||
| `FEISHU_ALLOW_ALL_USERS` | Allow any Feishu user to trigger the bot (dev only). |
|
||||
| `WECOM_BOT_ID` | WeCom AI Bot ID from admin console |
|
||||
| `WECOM_SECRET` | WeCom AI Bot secret |
|
||||
| `WECOM_WEBSOCKET_URL` | Custom WebSocket URL (default: `wss://openws.work.weixin.qq.com`) |
|
||||
|
|
@ -399,9 +423,12 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI
|
|||
| `QQBOT_HOME_CHANNEL` | QQ user/group openID for cron delivery and notifications |
|
||||
| `QQBOT_HOME_CHANNEL_NAME` | Display name for the QQ home channel |
|
||||
| `QQ_PORTAL_HOST` | Override the QQ portal host (set to `sandbox.q.qq.com` to route through the sandbox gateway; default: `q.qq.com`). |
|
||||
| `QQ_SANDBOX` | Enable QQ sandbox mode for development testing (`true`/`false`) |
|
||||
| `MATTERMOST_URL` | Mattermost server URL (e.g. `https://mm.example.com`) |
|
||||
| `MATTERMOST_TOKEN` | Bot token or personal access token for Mattermost |
|
||||
| `MATTERMOST_ALLOWED_USERS` | Comma-separated Mattermost user IDs allowed to message the bot |
|
||||
| `MATTERMOST_ALLOW_ALL_USERS` | Allow any Mattermost user to trigger the bot (dev only). |
|
||||
| `MATTERMOST_ALLOWED_CHANNELS` | If set, the bot only responds in these channels (whitelist). |
|
||||
| `MATTERMOST_HOME_CHANNEL` | Channel ID for proactive message delivery (cron, notifications) |
|
||||
| `MATTERMOST_REQUIRE_MENTION` | Require `@mention` in channels (default: `true`). Set to `false` to respond to all messages. |
|
||||
| `MATTERMOST_FREE_RESPONSE_CHANNELS` | Comma-separated channel IDs where bot responds without `@mention` |
|
||||
|
|
@ -411,6 +438,9 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI
|
|||
| `MATRIX_USER_ID` | Matrix user ID (e.g. `@hermes:matrix.org`) — required for password login, optional with access token |
|
||||
| `MATRIX_PASSWORD` | Matrix password (alternative to access token) |
|
||||
| `MATRIX_ALLOWED_USERS` | Comma-separated Matrix user IDs allowed to message the bot (e.g. `@alice:matrix.org`) |
|
||||
| `MATRIX_ALLOW_ALL_USERS` | Allow any Matrix user to trigger the bot (dev only). |
|
||||
| `MATRIX_HOME_CHANNEL` | Default room ID for cron / notification delivery. |
|
||||
| `MATRIX_HOME_CHANNEL_NAME` | Display name for the Matrix home room. |
|
||||
| `MATRIX_ALLOWED_ROOMS` | Comma-separated Matrix room IDs allowed to trigger bot responses |
|
||||
| `MATRIX_HOME_ROOM` | Room ID for proactive message delivery (e.g. `!abc123:matrix.org`) |
|
||||
| `MATRIX_ENCRYPTION` | Enable end-to-end encryption (`true`/`false`, default: `false`) |
|
||||
|
|
@ -429,6 +459,7 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI
|
|||
| `MATRIX_TOOLS_ALLOW_ROOM_CREATE` | Allow Matrix room creation tool execution (default: `false`) |
|
||||
| `MATRIX_ALLOW_ROOM_MENTIONS` | Allow outbound `@room` mentions to notify all room members (default: `false`) |
|
||||
| `MATRIX_AUTO_THREAD` | Auto-create threads for room messages (default: `true`) |
|
||||
| `MATRIX_DM_AUTO_THREAD` | Auto-create threads for DM messages in Matrix (default: `false`) |
|
||||
| `MATRIX_DM_MENTION_THREADS` | Create a thread when bot is `@mentioned` in a DM (default: `false`) |
|
||||
| `MATRIX_APPROVAL_REQUIRE_SENDER` | Require approval/model-picker reactions to come from the original requester when known (default: `true`) |
|
||||
| `MATRIX_APPROVAL_TIMEOUT_SECONDS` | Timeout for Matrix reaction approval/model-picker prompts (default: `300`) |
|
||||
|
|
@ -554,6 +585,81 @@ Used by the bundled LINE platform plugin (`plugins/platforms/line/`). See [Messa
|
|||
|
||||
See [the ntfy messaging guide](/user-guide/messaging/ntfy) — particularly the **identity model** section — before deploying with untrusted topics.
|
||||
|
||||
### IRC
|
||||
|
||||
Connect Hermes to an IRC server. No external dependencies. See [the IRC messaging guide](/user-guide/messaging/irc).
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `IRC_SERVER` | IRC server hostname (e.g. `irc.libera.chat`). Required. |
|
||||
| `IRC_CHANNEL` | Channel(s) to join (e.g. `#hermes`); comma-separate for multiple. Required. |
|
||||
| `IRC_NICKNAME` | Bot nickname (default: `hermes-bot`). Required. |
|
||||
| `IRC_PORT` | Server port (default: `6697` with TLS, `6667` without). |
|
||||
| `IRC_USE_TLS` | Use TLS (`true`/`false`; default `true` on port 6697). |
|
||||
| `IRC_SERVER_PASSWORD` | Server password for the `PASS` command (optional). |
|
||||
| `IRC_NICKSERV_PASSWORD` | NickServ password for automatic IDENTIFY on connect (optional). |
|
||||
| `IRC_ALLOWED_USERS` | Comma-separated nicks allowed to talk to the bot. |
|
||||
| `IRC_ALLOW_ALL_USERS` | Allow anyone in the channel to talk to the bot (dev only). |
|
||||
| `IRC_HOME_CHANNEL` | Channel for cron / notification delivery (defaults to `IRC_CHANNEL`). |
|
||||
|
||||
### SimpleX
|
||||
|
||||
Connect Hermes to a [SimpleX Chat](https://simplex.chat/) network via a local `simplex-chat` daemon. See [the SimpleX messaging guide](/user-guide/messaging/simplex).
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `SIMPLEX_WS_URL` | WebSocket URL of the simplex-chat daemon (e.g. `ws://127.0.0.1:5225`). |
|
||||
| `SIMPLEX_ALLOWED_USERS` | Comma-separated SimpleX contact IDs allowed to talk to the bot. |
|
||||
| `SIMPLEX_ALLOW_ALL_USERS` | Allow any contact to talk to the bot (dev only — disables allowlist). |
|
||||
| `SIMPLEX_AUTO_ACCEPT` | Auto-accept incoming contact requests (default: `true`). |
|
||||
| `SIMPLEX_GROUP_ALLOWED` | Comma-separated SimpleX group IDs the bot should participate in, or `*` to allow any group. Omit to ignore group messages entirely (safer default — a bot in a group otherwise processes every member's traffic). |
|
||||
| `SIMPLEX_HOME_CHANNEL` | Default contact/group ID for cron / notification delivery. |
|
||||
| `SIMPLEX_HOME_CHANNEL_NAME` | Human label for the home channel (defaults to the ID). |
|
||||
|
||||
### Photon
|
||||
|
||||
Connect Hermes to [Photon](https://photon.codes/) / Spectrum (iMessage and other Spectrum platforms) via the Node sidecar. See [the Photon messaging guide](/user-guide/messaging/photon).
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `PHOTON_PROJECT_ID` | Spectrum project id (the project's `spectrumProjectId`; set by `hermes photon setup`). |
|
||||
| `PHOTON_PROJECT_SECRET` | Project secret paired with the Spectrum project id (set by `hermes photon setup`). |
|
||||
| `PHOTON_ALLOWED_USERS` | Comma-separated E.164 phone numbers allowed to talk to the bot. |
|
||||
| `PHOTON_ALLOW_ALL_USERS` | Allow any sender to trigger the bot (dev only — disables allowlist). |
|
||||
| `PHOTON_REQUIRE_MENTION` | Ignore group-chat messages unless they match a mention wake word (`true`/`false`, default `false`). |
|
||||
| `PHOTON_MENTION_PATTERNS` | Mention wake-word regexes for group chats (JSON list or comma/newline-separated; defaults to Hermes wake words). |
|
||||
| `PHOTON_HOME_CHANNEL` | Default Photon target for cron / notification delivery: Spectrum space id, DM GUID, or bare E.164 phone number. |
|
||||
| `PHOTON_HOME_CHANNEL_NAME` | Human label for the home channel. |
|
||||
| `PHOTON_MARKDOWN` | Send agent replies as markdown — iMessage renders it natively, other Spectrum platforms degrade to plain text (`true`/`false`, default `true`). |
|
||||
| `PHOTON_REACTIONS` | Tapback 👀/👍/👎 on messages as processing status and route tapbacks on bot messages to the agent (`true`/`false`, default `false`). |
|
||||
| `PHOTON_TELEMETRY` | Enable Spectrum SDK telemetry in the sidecar (`true`/`false`, default `false`; toggle with `hermes photon telemetry on|off`). |
|
||||
| `PHOTON_SIDECAR_PORT` | Loopback port for the Node sidecar control + inbound channel (default `8789`). |
|
||||
| `PHOTON_SIDECAR_AUTOSTART` | Spawn the Node sidecar on connect (`true`/`false`, default `true`). |
|
||||
| `PHOTON_NODE_BIN` | Path to the node binary (default: `shutil.which('node')`). |
|
||||
| `PHOTON_DASHBOARD_HOST` | Photon Dashboard API host (default `https://app.photon.codes`). |
|
||||
| `PHOTON_SPECTRUM_HOST` | Photon Spectrum API host (default `https://spectrum.photon.codes`). |
|
||||
|
||||
### Microsoft Teams (adapter)
|
||||
|
||||
The Microsoft Teams platform adapter (Bot Framework / Azure AD), distinct from the [Microsoft Graph (Teams Meetings)](#microsoft-graph-teams-meetings) integration above. See [the Teams messaging guide](/user-guide/messaging/teams).
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `TEAMS_CLIENT_ID` | Azure AD application (Bot Framework) client ID. |
|
||||
| `TEAMS_CLIENT_SECRET` | Azure AD application client secret. |
|
||||
| `TEAMS_TENANT_ID` | Azure AD tenant ID hosting the bot application. |
|
||||
| `TEAMS_PORT` | Webhook listen port (Bot Framework default: `3978`). |
|
||||
| `TEAMS_ALLOWED_USERS` | Comma-separated Teams user IDs / UPNs allowed to talk to the bot. |
|
||||
| `TEAMS_ALLOW_ALL_USERS` | Allow any Teams user to trigger the bot (dev only). |
|
||||
| `TEAMS_HOME_CHANNEL` | Default chat/channel ID for cron / notification delivery. |
|
||||
| `TEAMS_HOME_CHANNEL_NAME` | Display name for the Teams home channel. |
|
||||
|
||||
### Raft
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `RAFT_PROFILE` | Raft agent profile slug — auto-enables the adapter when set. |
|
||||
|
||||
### Advanced Messaging Tuning
|
||||
|
||||
Advanced per-platform knobs for throttling the outbound message batcher. Most users never need to touch these; defaults are set to respect each platform's rate limits without feeling sluggish.
|
||||
|
|
@ -562,6 +668,7 @@ Advanced per-platform knobs for throttling the outbound message batcher. Most us
|
|||
|----------|-------------|
|
||||
| `HERMES_TELEGRAM_TEXT_BATCH_DELAY_SECONDS` | Grace window before flushing a queued Telegram text chunk (default: `0.6`). |
|
||||
| `HERMES_TELEGRAM_TEXT_BATCH_SPLIT_DELAY_SECONDS` | Delay between split chunks when a single Telegram message exceeds the length limit (default: `2.0`). |
|
||||
| `HERMES_SIMPLEX_TEXT_BATCH_DELAY` | Quiet-period seconds (default: `0.8`) used to concatenate rapid-fire inbound text messages into a single MessageEvent — same pattern as Telegram's text batching. |
|
||||
| `HERMES_TELEGRAM_MEDIA_BATCH_DELAY_SECONDS` | Grace window before flushing queued Telegram media (default: `0.6`). |
|
||||
| `HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS` | Delay before sending a follow-up after the agent finishes, to avoid racing the last stream chunk. |
|
||||
| `HERMES_TELEGRAM_HTTP_CONNECT_TIMEOUT` / `_READ_TIMEOUT` / `_WRITE_TIMEOUT` / `_POOL_TIMEOUT` | Override the underlying `python-telegram-bot` HTTP timeouts (seconds). |
|
||||
|
|
|
|||
|
|
@ -40,6 +40,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
|
|||
| `/clear` | Clear screen and start a new session |
|
||||
| `/history` | Show conversation history |
|
||||
| `/save` | Save the current conversation |
|
||||
| `/prompt` (alias: `/compose`) | Compose your next prompt in `$EDITOR` (markdown) instead of the inline input — useful for long, multi-line, or carefully-formatted prompts. |
|
||||
| `/retry` | Retry the last message (resend to agent) |
|
||||
| `/undo` | Remove the last user/assistant exchange |
|
||||
| `/title` | Set a title for the current session (usage: /title My Session Name) |
|
||||
|
|
@ -51,6 +52,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
|
|||
| `/steer <prompt>` | Inject a mid-run note that arrives at the agent **after the next tool call** — no interrupt, no new user turn. The text is appended to the last tool result's content once the current tool completes, giving the agent new context without breaking the current tool-calling loop. Use this to nudge direction mid-task (e.g. "focus on the auth module" while the agent is running tests). |
|
||||
| `/goal <text>` | Set a standing goal Hermes works toward across turns — our take on the Ralph loop. After each turn an auxiliary judge model decides whether the goal is done; if not, Hermes auto-continues. Subcommands: `/goal status`, `/goal pause`, `/goal resume`, `/goal clear`. Budget defaults to 20 turns (`goals.max_turns`); any real user message preempts the continuation loop, and state survives `/resume`. See [Persistent Goals](/user-guide/features/goals) for the full walkthrough. |
|
||||
| `/subgoal <text>` | Append a user-supplied criterion to the active goal mid-loop. The continuation prompt surfaces all subgoals to the agent verbatim, and the judge factors them into its DONE/CONTINUE verdict — so the goal isn't marked done until the original goal **and** every subgoal are met. Subcommands: `/subgoal` (list), `/subgoal remove <N>`, `/subgoal clear`. Requires an active `/goal`. |
|
||||
| `/moa <prompt>` | Run a single prompt through the default [Mixture of Agents](/user-guide/features/mixture-of-agents) preset, then restore your current model. One-shot — does not change your session model. |
|
||||
| `/resume [name]` | Resume a previously-named session |
|
||||
| `/sessions` (TUI alias: `/switch`) | Classic CLI: browse and resume previous sessions in an interactive picker. TUI: open the live session switcher for currently open TUI sessions. Use `/sessions new` in the TUI to start another live session immediately. |
|
||||
| `/redraw` | Force a full UI repaint (recovers from terminal drift after tmux resize, mouse selection artifacts, etc.) |
|
||||
|
|
@ -78,6 +80,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
|
|||
| `/footer [on\|off\|status]` | Toggle the gateway runtime-metadata footer on final replies (shows model, context %, and cwd). |
|
||||
| `/busy [queue\|steer\|interrupt\|status]` | CLI-only: control what pressing Enter does while Hermes is working — queue the new message, steer mid-turn, or interrupt immediately. |
|
||||
| `/indicator [kaomoji\|emoji\|unicode\|ascii]` | CLI-only: pick the TUI busy-indicator style. |
|
||||
| `/timestamps [on\|off\|status]` | CLI-only: toggle `[HH:MM]` timestamps on messages and in `/history`. |
|
||||
|
||||
### Tools & Skills
|
||||
|
||||
|
|
@ -99,6 +102,8 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
|
|||
| `/reload-skills` (alias: `/reload_skills`) | Re-scan `~/.hermes/skills/` for newly installed or removed skills |
|
||||
| `/reload` | Reload `.env` variables into the running session (picks up new API keys without restarting) |
|
||||
| `/plugins` | List installed plugins and their status |
|
||||
| `/pet [list\|<slug>]` | Toggle or adopt a [petdex](/user-guide/features/pets) mascot. `/pet` toggles the pane, `/pet list` shows installed pets, `/pet <slug>` adopts a specific one. |
|
||||
| `/hatch <description>` (alias: `/generate-pet`) | Generate a brand-new petdex pet from a text description, using the configured image backend (OpenRouter / Nous Portal). See [Pets](/user-guide/features/pets). |
|
||||
|
||||
### Info
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ description: "Authoritative reference for Hermes built-in tools, grouped by tool
|
|||
|
||||
This page documents Hermes' built-in tools, grouped by toolset. Availability varies by platform, credentials, and enabled toolsets.
|
||||
|
||||
**Quick counts (current registry):** ~71 tools — 10 browser tools (core) + 2 CDP-gated browser tools, 4 file tools, 4 Home Assistant tools, 2 terminal tools, 2 web tools, 5 Feishu tools, 7 Spotify tools (registered by the bundled `spotify` plugin), 5 Yuanbao tools, 9 kanban tools (registered when the kanban dispatcher spawns the agent), 2 Discord tools, and a handful of standalone tools (`memory`, `clarify`, `delegate_task`, `execute_code`, `cronjob`, `session_search`, `skill_view`/`skill_manage`/`skills_list`, `text_to_speech`, `image_generate`, `video_generate`, `vision_analyze`, `video_analyze`, `send_message`, `todo`, `computer_use`, `process`).
|
||||
**Quick counts (current registry):** ~73 tools — 10 browser tools (core) + 2 CDP-gated browser tools, 4 file tools, 4 Home Assistant tools, 3 terminal tools (`terminal`, `process`, `read_terminal`), 2 web tools, 5 Feishu tools, 7 Spotify tools (registered by the bundled `spotify` plugin), 5 Yuanbao tools, 9 kanban tools (registered when the kanban dispatcher spawns the agent), 3 project tools (desktop/GUI sessions), 2 Discord tools, and a handful of standalone tools (`memory`, `clarify`, `delegate_task`, `execute_code`, `cronjob`, `session_search`, `skill_view`/`skill_manage`/`skills_list`, `text_to_speech`, `image_generate`, `video_generate`, `vision_analyze`, `video_analyze`, `todo`, `computer_use`).
|
||||
|
||||
:::tip MCP Tools
|
||||
In addition to built-in tools, Hermes can load tools dynamically from MCP servers. MCP tools appear with the prefix `mcp_<server>_` (e.g., `mcp_github_create_issue` for the `github` MCP server). See [MCP Integration](/user-guide/features/mcp) for configuration.
|
||||
|
|
@ -132,18 +132,22 @@ Registered when the agent is either (a) spawned by the kanban dispatcher (`HERME
|
|||
| `kanban_link` | Link tasks with a parent → child dependency edge. | `HERMES_KANBAN_TASK` or `kanban` toolset |
|
||||
| `kanban_unblock` | Return a blocked task to `ready`. Orchestrator-only; hidden from dispatcher-spawned task workers. | profile with `kanban` toolset |
|
||||
|
||||
## `project` toolset
|
||||
|
||||
Tools for driving desktop [Projects](../user-guide/cli.md) — named, multi-folder workspaces. Registered when the `project` toolset is enabled (primarily the desktop app / dashboard surfaces).
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `project_create` | Create a desktop Project (a named workspace) and switch this chat into it. Pass `path` to anchor it to a repo/folder. | — |
|
||||
| `project_list` | List the desktop Projects and which one is active. | — |
|
||||
| `project_switch` | Switch this chat into an existing Project (by name, slug, or id); moves the session workspace to the project's primary folder. | — |
|
||||
|
||||
## `memory` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `memory` | Save important information to persistent memory that survives across sessions. Your memory appears in your system prompt at session start -- it's how you remember things about the user and your environment between conversations. WHEN TO SA… | — |
|
||||
|
||||
## `messaging` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `send_message` | Send a message to a connected messaging platform, or list available targets. IMPORTANT: When the user asks to send to a specific channel or person (not just a bare platform name), call send_message(action='list') FIRST to see available tar… | — |
|
||||
|
||||
## `session_search` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|
|
@ -164,6 +168,7 @@ Registered when the agent is either (a) spawned by the kanban dispatcher (`HERME
|
|||
|------|-------------|----------------------|
|
||||
| `process` | Manage background processes started with terminal(background=true). Actions: 'list' (show all), 'poll' (check status + new output), 'log' (full output with pagination), 'wait' (block until done or timeout), 'kill' (terminate), 'write' (sen… | — |
|
||||
| `terminal` | Execute shell commands on a Linux environment. Filesystem persists between calls. Set `background=true` for long-running servers. Set `notify_on_complete=true` (with `background=true`) to get an automatic notification when the process finishes — no polling needed. Do NOT use cat/head/tail — use read_file. Do NOT use grep/rg/find — use search_files. | — |
|
||||
| `read_terminal` | Read what's currently shown in the in-app terminal pane of the Hermes desktop GUI (the embedded shell beside this chat). Desktop-app only. | — |
|
||||
|
||||
## `todo` toolset
|
||||
|
||||
|
|
|
|||
|
|
@ -55,6 +55,7 @@ Or in-session:
|
|||
| `browser` | `browser_back`, `browser_cdp`, `browser_click`, `browser_console`, `browser_dialog`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `web_search` | Core browser automation. Includes `web_search` as a fallback for quick lookups. `browser_cdp` and `browser_dialog` are gated at runtime — registered only when a CDP endpoint is reachable at session start (via `/browser connect`, `browser.cdp_url` config, Browserbase, or Camofox). `browser_dialog` works together with the `pending_dialogs` and `frame_tree` fields that `browser_snapshot` adds when a CDP supervisor is attached. |
|
||||
| `clarify` | `clarify` | Ask the user a question when the agent needs clarification. |
|
||||
| `code_execution` | `execute_code` | Run Python scripts that call Hermes tools programmatically. |
|
||||
| `coding` | composite (`file` + `terminal` + `search` + `web` + `skills` + `browser` + `todo` + `memory` + `session_search` + `clarify` + `code_execution` + `delegation` + `vision`) | Coding-focused bundle for software work: file editing, terminal, search, web docs, skills, browser, delegate, and code execution. |
|
||||
| `cronjob` | `cronjob` | Schedule and manage recurring tasks. |
|
||||
| `debugging` | composite (`file` + `terminal` + `web`) | Debug bundle — file, process/terminal, web extract/search. |
|
||||
| `delegation` | `delegate_task` | Spawn isolated subagent instances for parallel work. |
|
||||
|
|
@ -70,7 +71,7 @@ Or in-session:
|
|||
| `video_gen` | `video_generate` | Text-to-video and image-to-video via plugin-registered backends (xAI Grok-Imagine, FAL.ai Veo 3.1 / Pixverse v6 / Kling O3). Pass `image_url` to animate an image; omit it for text-to-video. |
|
||||
| `kanban` | `kanban_block`, `kanban_comment`, `kanban_complete`, `kanban_create`, `kanban_heartbeat`, `kanban_link`, `kanban_list`, `kanban_show`, `kanban_unblock` | Multi-agent coordination tools. Registered for dispatcher-spawned task workers (`HERMES_KANBAN_TASK`) and for profiles that explicitly list the `kanban` toolset by name (the `all`/`*` wildcard does **not** enable it). Workers mark tasks done, block, heartbeat, comment, and create/link follow-up tasks; orchestrator profiles additionally get board-routing tools like list/unblock. |
|
||||
| `memory` | `memory` | Persistent cross-session memory management. |
|
||||
| `messaging` | `send_message` | Send messages to other platforms (Telegram, Discord, etc.) from within a session. |
|
||||
| `project` | `project_create`, `project_list`, `project_switch` | Create and switch desktop [Projects](../user-guide/cli.md) (named, multi-folder workspaces). GUI / desktop sessions only. |
|
||||
| `safe` | `image_generate`, `vision_analyze`, `web_extract`, `web_search` (via `includes`) | Read-only research + media generation. No file writes, no terminal, no code execution. |
|
||||
| `search` | `web_search` | Web search only (without extract). |
|
||||
| `session_search` | `session_search` | Search past conversation sessions. |
|
||||
|
|
@ -91,9 +92,9 @@ Platform toolsets define the complete tool configuration for a deployment target
|
|||
|
||||
| Toolset | Differences from `hermes-cli` |
|
||||
|---------|-------------------------------|
|
||||
| `hermes-cli` | Full toolset — the default for interactive CLI sessions. Includes file, terminal, web, browser, memory, skills, vision, image_gen, todo, tts, delegation, code_execution, cronjob, session_search, clarify, and `safe` (read-only) bundles plus the standard messaging tools. |
|
||||
| `hermes-acp` | Drops `clarify`, `cronjob`, `image_generate`, `send_message`, `text_to_speech`, and all four Home Assistant tools. Focused on coding tasks in IDE context. |
|
||||
| `hermes-api-server` | Drops `clarify`, `send_message`, and `text_to_speech`. Keeps everything else — suitable for programmatic access where user interaction isn't possible. |
|
||||
| `hermes-cli` | Full toolset — the default for interactive CLI sessions. Includes file, terminal, web, browser, memory, skills, vision, image_gen, todo, tts, delegation, code_execution, cronjob, session_search, and clarify, plus the `safe` (read-only) bundle. |
|
||||
| `hermes-acp` | Drops `clarify`, `cronjob`, `image_generate`, `text_to_speech`, and all four Home Assistant tools. Focused on coding tasks in IDE context. |
|
||||
| `hermes-api-server` | Drops `clarify` and `text_to_speech`. Keeps everything else — suitable for programmatic access where user interaction isn't possible. |
|
||||
| `hermes-cron` | Same as `hermes-cli`. |
|
||||
| `hermes-telegram` | Same as `hermes-cli`. |
|
||||
| `hermes-discord` | Adds `discord` and `discord_admin` on top of `hermes-cli`. |
|
||||
|
|
|
|||
|
|
@ -842,6 +842,17 @@ When the iteration budget is fully exhausted, the CLI shows a notification to th
|
|||
|
||||
`agent.api_max_retries` controls how many times Hermes retries a provider API call on transient errors (rate limits, connection drops, 5xx) **before** fallback-provider switching engages. The default is `3` — four attempts total. If you have [fallback providers](/user-guide/features/fallback-providers) configured and want to fail over faster, drop this to `0` so the first transient error on your primary immediately hands off to the fallback instead of churning retries against the flaky endpoint.
|
||||
|
||||
## Standing Goals (`/goal`)
|
||||
|
||||
When a standing goal is active, Hermes judges whether each assistant response satisfies it. If not, it feeds a continuation prompt back into the same session and keeps working until the goal is done, the turn budget is exhausted, or the user pauses/clears it. The turn budget is the real backstop — judge failures fail **open** (continue) so a flaky judge never wedges progress.
|
||||
|
||||
```yaml
|
||||
goals:
|
||||
max_turns: 20 # Max continuation turns before Hermes auto-pauses the goal (default: 20)
|
||||
```
|
||||
|
||||
`max_turns` caps how many continuation turns a goal can drive before Hermes auto-pauses it and asks the user to `/goal resume`. It protects against judge false negatives (goal actually done but judge says continue) and unbounded model spend on fuzzy or unachievable goals. See [Goals](/user-guide/features/goals) for the full feature.
|
||||
|
||||
### API Timeouts
|
||||
|
||||
Hermes has separate timeout layers for streaming, plus a stale detector for non-streaming calls. The stale detectors auto-adjust for local providers only when you leave them at their implicit defaults.
|
||||
|
|
@ -906,6 +917,15 @@ The Qwen Cloud (Alibaba DashScope) upstream caps cache TTL at 5 minutes, so Herm
|
|||
|
||||
No knob exists to disable this — caching is always-on and saves money even on single-turn conversations because the system prompt alone is a meaningful fraction of the input token count.
|
||||
|
||||
The one explicit knob is the cache TTL tier Hermes requests on Anthropic-style breakpoints:
|
||||
|
||||
```yaml
|
||||
prompt_caching:
|
||||
cache_ttl: "5m" # "5m" or "1h" (Anthropic-supported tiers); other values are ignored
|
||||
```
|
||||
|
||||
`cache_ttl` selects the breakpoint TTL Hermes attaches for Claude via the native Anthropic API, OpenRouter, and Nous Portal. Only the two Anthropic-supported tiers (`"5m"`, `"1h"`) are honored — any other value is ignored. Providers with their own caps (e.g. Qwen Cloud, which maxes at 5 minutes) still clamp to what the upstream allows.
|
||||
|
||||
## Auxiliary Models
|
||||
|
||||
Hermes uses "auxiliary" models for side tasks like image analysis, web page summarization, browser screenshot analysis, session-title generation, and context compression. By default (`auxiliary.*.provider: "auto"`), Hermes routes every auxiliary task to your **main chat model** — the same provider/model you picked in `hermes model`. You don't need to configure anything to get started, but be aware that on expensive reasoning models (Opus, MiniMax M2.7, etc.) auxiliary tasks add meaningful cost. If you want cheap-and-fast side tasks regardless of your main model, set `auxiliary.<task>.provider` and `auxiliary.<task>.model` explicitly (for example, Gemini Flash on OpenRouter for vision and web extraction).
|
||||
|
|
@ -1317,6 +1337,28 @@ agent:
|
|||
tool_use_enforcement: ["gpt", "codex", "gemini", "grok", "my-custom-model"]
|
||||
```
|
||||
|
||||
## Tool-Loop Guardrails
|
||||
|
||||
Hermes detects when the agent is stuck in an unproductive tool-calling loop — the same tool call failing repeatedly, the same tool failing over and over, or an idempotent call returning the same result with no progress. By default it injects a **warning** into the tool result so the model self-corrects; it does not hard-stop, since a person watching the CLI/TUI can intervene.
|
||||
|
||||
For unattended gateway / server deployments, enable hard stops so a stuck agent is circuit-broken instead of burning the iteration budget:
|
||||
|
||||
```yaml
|
||||
tool_loop_guardrails:
|
||||
warnings_enabled: true # inject warnings into tool results (default: true)
|
||||
hard_stop_enabled: false # also BLOCK the call past the hard-stop threshold (default: false)
|
||||
warn_after:
|
||||
exact_failure: 2 # identical failing call repeated N times
|
||||
same_tool_failure: 3 # same tool failing N times (different args)
|
||||
idempotent_no_progress: 2 # same result, no progress, N times
|
||||
hard_stop_after:
|
||||
exact_failure: 5
|
||||
same_tool_failure: 8
|
||||
idempotent_no_progress: 5
|
||||
```
|
||||
|
||||
`hard_stop_enabled` defaults to `false` because interactive sessions have a human in the loop. In unattended deployments (gateway, cron, kanban workers) set it to `true` so repeated failures are blocked rather than only warned. See also [Docker / unattended deployments](docker.md).
|
||||
|
||||
## TTS Configuration
|
||||
|
||||
```yaml
|
||||
|
|
@ -1934,3 +1976,55 @@ terminal:
|
|||
```
|
||||
|
||||
`MESSAGING_CWD` and direct `TERMINAL_CWD` entries in `~/.hermes/.env` are legacy compatibility fallbacks. New configurations should use `terminal.cwd`.
|
||||
|
||||
## Network
|
||||
|
||||
Connectivity workarounds for outbound HTTP:
|
||||
|
||||
```yaml
|
||||
network:
|
||||
force_ipv4: false # Force IPv4 for outbound connections (default: false)
|
||||
```
|
||||
|
||||
`force_ipv4` — on servers with broken or unreachable IPv6, Python resolves AAAA records first and can hang for the full TCP timeout before falling back to IPv4. Set this to `true` to skip IPv6 entirely and connect over IPv4 directly.
|
||||
|
||||
## Onboarding
|
||||
|
||||
First-touch onboarding hints and the structured profile-build offer:
|
||||
|
||||
```yaml
|
||||
onboarding:
|
||||
profile_build: "ask" # "ask" (default) | "off"
|
||||
seen: {} # internal latch — leave empty
|
||||
```
|
||||
|
||||
- `profile_build` — controls the profile-build path offered on the very first gateway message ever. `"ask"` (default) offers to build a user profile; the offer is **opt-in and consent-gated** — the agent asks before any lookup and never reads connected accounts silently. `"off"` shows a plain intro only. The offer fires at most once.
|
||||
- `seen` — internal state. Hermes latches each shown hint here so it never fires again; the profile-build offer is also recorded here once shown. Don't hand-edit it — wipe the whole `onboarding` section if you want to re-see all hints.
|
||||
|
||||
## Dashboard
|
||||
|
||||
Configuration for the [web dashboard](/user-guide/features/web-dashboard) — visual theme, public URL, and authentication providers. The auth providers (OAuth, basic password, drain) are documented in detail on the web-dashboard page; this is the `config.yaml` shape.
|
||||
|
||||
```yaml
|
||||
dashboard:
|
||||
theme: "default" # "default" | "midnight" | "ember" | "mono" | "cyberpunk" | "rose"
|
||||
show_token_analytics: false # Re-enable the (local-estimate-only) token/cost analytics surfaces
|
||||
public_url: "" # Full public authority for OAuth redirect_uri (env: HERMES_DASHBOARD_PUBLIC_URL)
|
||||
oauth: # Portal OAuth gate (engaged with --host and not --insecure)
|
||||
client_id: "" # agent:{instance_id} — Portal provisions this
|
||||
portal_url: "" # blank → plugin default (production Portal)
|
||||
basic_auth: # Self-hosted username/password gate (dashboard_auth/basic plugin)
|
||||
username: "" # blank → plugin no-op
|
||||
password_hash: "" # scrypt$... (preferred — no plaintext at rest)
|
||||
password: "" # plaintext fallback (hashed in-memory at load)
|
||||
secret: "" # token-signing key; blank → random per-process
|
||||
session_ttl_seconds: 0 # 0 → plugin default (12h)
|
||||
drain_auth: # Drain-control service-credential gate (dashboard_auth/drain plugin)
|
||||
scope: "drain" # capability label on the verified principal
|
||||
min_secret_chars: 43 # entropy bar (url-safe-b64 chars; 43 ≈ 256 bits)
|
||||
```
|
||||
|
||||
- `theme` — dashboard visual theme.
|
||||
- `show_token_analytics` — off by default. The Analytics page and token/cost figures are a **local lower-bound estimate** (they exclude auxiliary calls, retries, fallbacks, and cache writes), so they can read far below the provider bill. Set `true` only if you understand they're not billing.
|
||||
- `public_url` — when set, this is the complete authority (scheme + host + optional path prefix) the OAuth `redirect_uri` is built from. Set it for deploys behind reverse proxies that don't reliably forward `X-Forwarded-*` headers. Leave empty to use proxy-header reconstruction.
|
||||
- `oauth` / `basic_auth` / `drain_auth` — auth provider config read by the bundled dashboard-auth plugins. The drain secret itself is **not** set here; it's provisioned via the `HERMES_DASHBOARD_DRAIN_SECRET` env var. See [Web Dashboard](/user-guide/features/web-dashboard) for full auth setup.
|
||||
|
|
|
|||
|
|
@ -256,7 +256,7 @@ When scheduling jobs, you specify where the output goes:
|
|||
| `"telegram,discord"` | Fan out to a specific set of channels | Comma-separated list |
|
||||
| `"origin,all"` | Deliver to the origin **plus** every other connected channel | Combine any tokens |
|
||||
|
||||
The agent's final response is automatically delivered. You do not need to call `send_message` in the cron prompt.
|
||||
The agent's final response is automatically delivered to the configured `deliver:` target — the agent does not send messages itself, so there is nothing to call in the cron prompt.
|
||||
|
||||
### Routing intent (`all`)
|
||||
|
||||
|
|
@ -464,7 +464,7 @@ This means cron jobs that run at high frequency or during peak hours are more re
|
|||
|
||||
## Schedule formats
|
||||
|
||||
The agent's final response is automatically delivered — you do **not** need to include `send_message` in the cron prompt for that same destination. If a cron run calls `send_message` to the exact target the scheduler will already deliver to, Hermes skips that duplicate send and tells the model to put the user-facing content in the final response instead. Use `send_message` only for additional or different targets.
|
||||
The agent's final response is automatically delivered to the job's `deliver:` target — the agent no longer fires messages itself, so the user-facing content simply goes in the final response. To deliver to **additional or different** targets, list multiple `deliver:` targets on the cron job (comma-separated, e.g. `deliver: "telegram,discord"`) rather than having the agent send them.
|
||||
|
||||
### Relative delays (one-shot)
|
||||
|
||||
|
|
|
|||
|
|
@ -159,7 +159,6 @@ Certain toolsets are blocked for subagents regardless of what you specify:
|
|||
- `clarify` — subagents cannot interact with the user
|
||||
- `memory` — no writes to shared persistent memory
|
||||
- `code_execution` — children should reason step-by-step
|
||||
- `send_message` — no cross-platform side effects (e.g., sending Telegram messages)
|
||||
|
||||
## Max Iterations
|
||||
|
||||
|
|
@ -243,7 +242,7 @@ For **durable long-running work** that must survive interrupts or outlive the cu
|
|||
|
||||
- Each subagent gets its **own terminal session** (separate from the parent)
|
||||
- **Nested delegation is opt-in** — only `role="orchestrator"` children can delegate further, and only when `max_spawn_depth` is raised from its default of 1 (flat). Disable globally with `orchestrator_enabled: false`.
|
||||
- Leaf subagents **cannot** call: `delegate_task`, `clarify`, `memory`, `send_message`, `execute_code`. Orchestrator subagents retain `delegate_task` but still cannot use the other four.
|
||||
- Leaf subagents **cannot** call: `delegate_task`, `clarify`, `memory`, `execute_code`. Orchestrator subagents retain `delegate_task` but still cannot use the other three.
|
||||
- **Interrupt propagation** — interrupting the parent interrupts all active children (including grandchildren under orchestrators)
|
||||
- Only the final summary enters the parent's context, keeping token usage efficient
|
||||
- Subagents inherit the parent's **API key, provider configuration, and credential pool** (enabling key rotation on rate limits)
|
||||
|
|
|
|||
|
|
@ -202,8 +202,8 @@ Create `~/.hermes/BOOT.md`. Write it as if you were giving instructions to a hum
|
|||
# Startup Checklist
|
||||
|
||||
1. Run `hermes cron list` and check if any scheduled jobs failed overnight.
|
||||
2. If any failed, send a summary to Discord #ops using the `send_message` tool.
|
||||
3. Check if `/opt/app/deploy.log` has any ERROR lines from the last 24 hours. If yes, summarize them and include in the same Discord message.
|
||||
2. If any failed, summarize them for Discord #ops (the hook delivers your final response to its configured target).
|
||||
3. Check if `/opt/app/deploy.log` has any ERROR lines from the last 24 hours. If yes, summarize them and include in the same report.
|
||||
4. If nothing went wrong, reply with only `[SILENT]` so no message is sent.
|
||||
```
|
||||
|
||||
|
|
@ -247,8 +247,9 @@ def _build_prompt(content: str) -> str:
|
|||
"---\n"
|
||||
f"{content}\n"
|
||||
"---\n\n"
|
||||
"Execute each instruction. Use the send_message tool to deliver any "
|
||||
"messages to platforms like Discord or Slack.\n"
|
||||
"Execute each instruction. Put any user-facing summary in your "
|
||||
"final response — the hook delivers it to the configured channel "
|
||||
"(e.g. Discord or Slack); you do not send messages yourself.\n"
|
||||
"If nothing needs attention and there is nothing to report, reply "
|
||||
"with ONLY: [SILENT]"
|
||||
)
|
||||
|
|
|
|||
|
|
@ -765,7 +765,7 @@ hermes mcp serve --verbose # Debug logging on stderr
|
|||
|
||||
### How it works
|
||||
|
||||
The MCP server reads conversation data directly from Hermes's session store (`~/.hermes/sessions/sessions.json` and the SQLite database). A background thread polls the database for new messages and maintains an in-memory event queue. For sending messages, it uses the same `send_message` infrastructure as the Hermes agent itself.
|
||||
The MCP server reads conversation data directly from Hermes's session store (`~/.hermes/sessions/sessions.json` and the SQLite database). A background thread polls the database for new messages and maintains an in-memory event queue. For sending messages, it uses the same internal send engine (`tools/send_message_tool.py`) that powers cron delivery and the `hermes send` CLI.
|
||||
|
||||
The gateway does NOT need to be running for read operations (listing conversations, reading history, polling events). It DOES need to be running for send operations, since the platform adapters need active connections.
|
||||
|
||||
|
|
|
|||
|
|
@ -103,6 +103,26 @@ Inside the CLI and TUI you can manage the pet without leaving the session:
|
|||
In the TUI, `/pet list` opens an interactive picker overlay; in the desktop app
|
||||
it opens the Cmd+K pet palette.
|
||||
|
||||
## Generating a pet (`/hatch`)
|
||||
|
||||
Beyond installing pre-made pets from the gallery, Hermes can **generate a brand-new pet** from a text description — its own AI sprite-generation pipeline.
|
||||
|
||||
- CLI/TUI: `/hatch <description>` (alias `/generate-pet`), or `hermes pets` → the generate flow.
|
||||
- Desktop app: the Pokédex-style **generate** UI — an animated egg, hatch FX, and a draft picker.
|
||||
|
||||
How generation works (a two-step, cost-bounded flow):
|
||||
|
||||
1. **Base drafts** — a handful of cheap, prompt-only "what should this pet look like" variants are generated. You pick one, or remix/retry for a fresh round.
|
||||
2. **Hatch** — the chosen base is used as a reference image to generate one grounded animation row per Hermes state (idle, thinking, tool use, etc.), which are deterministically sliced into frames and packed into a standard petdex/Codex atlas (8×9 grid of 192×208 cells). The result is a valid spritesheet you keep — and could `petdex submit`.
|
||||
|
||||
### Image backend
|
||||
|
||||
Generation uses the active [image-generation provider](/user-guide/features/image-generation), but it requires **reference-image grounding** so each animation row stays the same character as the base. Reference-capable backends: **Nous Portal**, **OpenRouter**, **OpenAI** (`gpt-image-2`), and **Krea**. OpenRouter/Nous run a quality-first model chain by default.
|
||||
|
||||
- Resolution order prefers Nous Portal → OpenAI → OpenRouter.
|
||||
- If no reference-capable backend is configured, generation surfaces an actionable error pointing you to `hermes tools` → Image Generation. (Installing/adopting existing gallery pets needs no image backend.)
|
||||
- Override the backend with the `HERMES_PET_IMAGE_PROVIDER` env var (e.g. `HERMES_PET_IMAGE_PROVIDER=openrouter`).
|
||||
|
||||
## Desktop app
|
||||
|
||||
In the desktop app you can manage the pet two ways:
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ specific tool's schema on demand.
|
|||
The tools that make up Hermes' core capability set (`terminal`,
|
||||
`read_file`, `write_file`, `patch`, `search_files`, `todo`, `memory`,
|
||||
`browser_*`, `web_search`, `web_extract`, `clarify`, `execute_code`,
|
||||
`delegate_task`, `session_search`, `send_message`, and the rest of
|
||||
`delegate_task`, `session_search`, and the rest of
|
||||
`_HERMES_CORE_TOOLS`) are *always* loaded directly. Only MCP tools and
|
||||
non-core plugin tools are eligible for deferral.
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ Tools are functions that extend the agent's capabilities. They're organized into
|
|||
|
||||
## Available Tools
|
||||
|
||||
Hermes ships with a broad built-in tool registry covering web search, browser automation, terminal execution, file editing, memory, delegation, RL training, messaging delivery, Home Assistant, and more.
|
||||
Hermes ships with a broad built-in tool registry covering web search, browser automation, terminal execution, file editing, memory, delegation, scheduled tasks, Home Assistant, and more.
|
||||
|
||||
:::note
|
||||
**Honcho cross-session memory** is available as a memory provider plugin (`plugins/memory/honcho/`), not as a built-in toolset. See [Plugins](./plugins.md) for installation.
|
||||
|
|
@ -27,7 +27,7 @@ High-level categories:
|
|||
| **Media** | `vision_analyze`, `image_generate`, `text_to_speech` | Multimodal analysis and generation. |
|
||||
| **Agent orchestration** | `todo`, `clarify`, `execute_code`, `delegate_task` | Planning, clarification, code execution, and subagent delegation. |
|
||||
| **Memory & recall** | `memory`, `session_search` | Persistent memory and session search. |
|
||||
| **Automation & delivery** | `cronjob`, `send_message` | Scheduled tasks with create/list/update/pause/resume/run/remove actions, plus outbound messaging delivery. |
|
||||
| **Automation** | `cronjob` | Scheduled tasks with create/list/update/pause/resume/run/remove actions. Outbound delivery is handled by cron's own delivery, the `hermes send` CLI, and the gateway notifier — not by an agent-callable tool. |
|
||||
| **Integrations** | `ha_*`, MCP server tools | Home Assistant, MCP, and other integrations. |
|
||||
|
||||
For the authoritative code-derived registry, see [Built-in Tools Reference](/reference/tools-reference) and [Toolsets Reference](/reference/toolsets-reference).
|
||||
|
|
|
|||
|
|
@ -965,6 +965,14 @@ def register(ctx):
|
|||
|
||||
The login page lists all registered providers; multiple providers can be stacked and the user picks one at `/login`.
|
||||
|
||||
### Non-interactive (bearer-token) auth
|
||||
|
||||
Alongside interactive human login (session cookies + refresh), the `DashboardAuthProvider` ABC supports a **non-interactive, service-to-service** capability via `supports_token = True` + `verify_token(token=...)`. When a provider opts in, an inbound `Authorization: Bearer <token>` is verified and, on success, a `TokenPrincipal` is attached to the request (`request.state.token_principal`) for the endpoints that provider marks token-authable — no cookie, no redirect, no refresh.
|
||||
|
||||
The bundled first consumer is the **drain** provider (`plugins/dashboard_auth/drain`): `nous-account-service` provisions a per-agent secret via `HERMES_DASHBOARD_DRAIN_SECRET`, and the provider verifies inbound bearer tokens against it with a constant-time compare, registering `/api/gateway/drain` as token-authable. It **fails closed** — a weak/short secret (< 256 bits) is rejected at registration and the endpoint stays disabled; it's a no-op when the env var is unset. Behavioural knobs (`scope`, `min_secret_chars`) live under `dashboard.drain_auth` in `config.yaml`.
|
||||
|
||||
Custom providers can implement `supports_token`/`verify_token` the same way to expose their own machine-authable endpoints.
|
||||
|
||||
### Verifying the gate is on
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -607,9 +607,9 @@ gateway:
|
|||
|
||||
Leaving this at `true` on the "primary" gateway keeps the normal behavior — global `/`-menu commands for built-ins and installed skills.
|
||||
|
||||
## Sending Media (`send_message` + `MEDIA:` tags)
|
||||
## Sending Media (inline `MEDIA:` tags)
|
||||
|
||||
The Discord adapter supports native file uploads for every common media type via the `send_message` tool and inline `MEDIA:/path/to/file` tags emitted by the agent:
|
||||
The Discord adapter supports native file uploads for every common media type via inline `MEDIA:/path/to/file` tags emitted in the agent's response — the adapter strips the tag and auto-uploads the file:
|
||||
|
||||
| Type | How it's delivered |
|
||||
|---|---|
|
||||
|
|
@ -723,7 +723,7 @@ Notes:
|
|||
|
||||
## Forum Channels
|
||||
|
||||
Discord forum channels (type 15) don't accept direct messages — every post in a forum must be a thread. Hermes auto-detects forum channels and creates a new thread post whenever it needs to send there, so `send_message`, TTS, images, voice messages, and file attachments all work without special handling from the agent.
|
||||
Discord forum channels (type 15) don't accept direct messages — every post in a forum must be a thread. Hermes auto-detects forum channels and creates a new thread post whenever it needs to send there, so text replies, TTS, images, voice messages, and file attachments all work without special handling from the agent.
|
||||
|
||||
- **Thread name** is derived from the first line of the message (markdown heading prefix stripped, capped at 100 chars). When the message is attachment-only, the filename is used as the fallback thread name.
|
||||
- **Attachments** ride along on the starter message of the new thread — no separate upload step, no partial sends.
|
||||
|
|
|
|||
|
|
@ -41,6 +41,7 @@ Bots need both a model provider and tool providers (TTS, web). A [Nous Portal](/
|
|||
| LINE | — | ✅ | ✅ | — | — | ✅ | — |
|
||||
| ntfy | — | — | — | — | — | — | — |
|
||||
| Raft | — | — | — | — | — | — | — |
|
||||
| IRC | — | — | — | — | — | — | — |
|
||||
|
||||
**Voice** = TTS audio replies and/or voice message transcription. **Images** = send/receive images. **Files** = send/receive file attachments. **Threads** = threaded conversations. **Reactions** = emoji reactions on messages. **Typing** = typing indicator while processing. **Streaming** = progressive message updates via editing.
|
||||
|
||||
|
|
@ -523,7 +524,7 @@ Each platform has its own toolset:
|
|||
| QQBot | `hermes-qqbot` | Full tools including terminal |
|
||||
| Yuanbao | `hermes-yuanbao` | Full tools including terminal |
|
||||
| Microsoft Teams | `hermes-teams` | Full tools including terminal |
|
||||
| API Server | `hermes-api-server` | Full tools (drops `clarify`, `send_message`, `text_to_speech` — programmatic access doesn't have an interactive user) |
|
||||
| API Server | `hermes-api-server` | Full tools (drops `clarify`, `text_to_speech` — programmatic access doesn't have an interactive user) |
|
||||
| Webhooks | `hermes-webhook` | Full tools including terminal |
|
||||
| Raft | `hermes-raft` | Wake-only channel; agent uses Raft CLI for message I/O |
|
||||
|
||||
|
|
@ -655,4 +656,5 @@ Defaults to `false`. Only platforms whose adapter implements `delete_message` ho
|
|||
- [Teams Meetings Pipeline](teams-meetings.md)
|
||||
- [Open WebUI + API Server](open-webui.md)
|
||||
- [Raft Setup](raft.md)
|
||||
- [IRC Setup](irc.md)
|
||||
- [Webhooks](webhooks.md)
|
||||
|
|
|
|||
78
website/docs/user-guide/messaging/irc.md
Normal file
78
website/docs/user-guide/messaging/irc.md
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
# IRC
|
||||
|
||||
The IRC adapter connects Hermes to any IRC server and relays messages between an IRC channel (or direct messages) and the agent. It speaks the IRC protocol over Python's stdlib `asyncio` — **no external dependencies, no SDK, no daemon**. It works with public networks like [Libera.Chat](https://libera.chat/) and any self-hosted ircd.
|
||||
|
||||
IRC is plain text: there is no voice, image, file, thread, reaction, typing, or streaming support — replies are sent as `PRIVMSG` lines, with long messages split to fit the IRC line limit.
|
||||
|
||||
> Run `hermes gateway setup` and pick **IRC** for a guided walk-through.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- An IRC server to connect to (e.g. `irc.libera.chat`)
|
||||
- A channel to join (e.g. `#hermes`) — comma-separate to join several
|
||||
- A nickname for the bot (default: `hermes-bot`)
|
||||
- Optional: a registered nick + NickServ password if your network requires identification
|
||||
|
||||
## Configure Hermes
|
||||
|
||||
You can configure IRC two ways — environment variables (for a quick env-only setup) or the `gateway` block in `~/.hermes/gateway-config.yaml`.
|
||||
|
||||
### Option A — gateway-config.yaml
|
||||
|
||||
```yaml
|
||||
gateway:
|
||||
platforms:
|
||||
irc:
|
||||
enabled: true
|
||||
extra:
|
||||
server: irc.libera.chat
|
||||
port: 6697
|
||||
nickname: hermes-bot
|
||||
channel: "#hermes"
|
||||
use_tls: true
|
||||
server_password: "" # optional server password
|
||||
nickserv_password: "" # optional NickServ identification
|
||||
allowed_users: [] # empty = allow all, or list of nicks
|
||||
max_message_length: 450 # IRC line limit (safe default)
|
||||
```
|
||||
|
||||
### Option B — environment variables
|
||||
|
||||
| Variable | Required | Description |
|
||||
|----------|:--------:|-------------|
|
||||
| `IRC_SERVER` | ✅ | IRC server hostname (e.g. `irc.libera.chat`) |
|
||||
| `IRC_CHANNEL` | ✅ | Channel(s) to join — comma-separate for multiple |
|
||||
| `IRC_NICKNAME` | ✅ | Bot nickname (default: `hermes-bot`) |
|
||||
| `IRC_PORT` | — | Server port (default: `6697` with TLS, `6667` without) |
|
||||
| `IRC_USE_TLS` | — | Use TLS (`true`/`false`; default `true` on port 6697) |
|
||||
| `IRC_SERVER_PASSWORD` | — | Server password for the `PASS` command |
|
||||
| `IRC_NICKSERV_PASSWORD` | — | NickServ password for automatic IDENTIFY on connect |
|
||||
| `IRC_ALLOWED_USERS` | — | Comma-separated nicks allowed to talk to the bot |
|
||||
| `IRC_ALLOW_ALL_USERS` | — | Allow anyone in the channel to talk to the bot (dev only) |
|
||||
| `IRC_HOME_CHANNEL` | — | Channel for cron / notification delivery (defaults to `IRC_CHANNEL`) |
|
||||
|
||||
## Access control
|
||||
|
||||
By default, only nicks listed in `allowed_users` (or `IRC_ALLOWED_USERS`) may talk to the bot. Leave the list empty **and** set `IRC_ALLOW_ALL_USERS=true` to let anyone in the channel chat with Hermes — useful for testing, but not recommended on public networks since IRC nicks are not authenticated unless the network enforces NickServ.
|
||||
|
||||
If your network registers nicks, set `IRC_NICKSERV_PASSWORD` (or `nickserv_password`) so the bot identifies to NickServ on connect and keeps its registered nick.
|
||||
|
||||
## Channels vs. DMs
|
||||
|
||||
- Messages in a joined channel are treated as a **group** conversation.
|
||||
- Private messages to the bot are treated as **direct messages**.
|
||||
|
||||
Cron jobs and notifications are delivered to the **home channel** — `IRC_HOME_CHANNEL` if set, otherwise the first `IRC_CHANNEL`.
|
||||
|
||||
## Run the gateway
|
||||
|
||||
```bash
|
||||
hermes gateway start
|
||||
```
|
||||
|
||||
Check status with `hermes gateway status` — IRC connection state is reported there, including for env-only setups.
|
||||
|
||||
## Notes
|
||||
|
||||
- Long agent replies are automatically split into multiple `PRIVMSG` lines to stay within the IRC line limit (`max_message_length`, default 450 bytes after protocol overhead).
|
||||
- The adapter acquires a scoped credential lock per server+nick, so two Hermes profiles won't fight over the same IRC identity.
|
||||
|
|
@ -85,10 +85,10 @@ cronjob(
|
|||
)
|
||||
```
|
||||
|
||||
Or target a specific topic explicitly:
|
||||
Or target a specific topic explicitly via the cron job's `deliver:` field, or from a shell script with the [`hermes send` CLI](/guides/pipe-script-output):
|
||||
|
||||
```python
|
||||
send_message(target="ntfy:alerts-channel", message="Done!")
|
||||
```bash
|
||||
hermes send ntfy:alerts-channel "Done!"
|
||||
```
|
||||
|
||||
This works even when the cron runs out-of-process from the gateway — the plugin registers a `standalone_sender_fn` that opens its own HTTP connection.
|
||||
|
|
|
|||
|
|
@ -62,7 +62,7 @@ SIMPLEX_HOME_CHANNEL=<contact-id>
|
|||
|
||||
## Find your contact ID or display name
|
||||
|
||||
After starting the daemon, open a conversation with your agent contact. The numeric `contactId` appears in session logs or via `hermes send_message action=list`. If you'd rather use the display name shown in the SimpleX UI, that works too — `SIMPLEX_ALLOWED_USERS` accepts either form.
|
||||
After starting the daemon, open a conversation with your agent contact. The numeric `contactId` appears in session logs. If you'd rather use the display name shown in the SimpleX UI, that works too — `SIMPLEX_ALLOWED_USERS` accepts either form.
|
||||
|
||||
## Authorization
|
||||
|
||||
|
|
@ -83,7 +83,7 @@ SIMPLEX_GROUP_ALLOWED=* # any group the bot is in
|
|||
```
|
||||
|
||||
Address groups by prefixing the chat ID with `group:`, e.g.
|
||||
`simplex:group:12` in `send_message` or as a cron `deliver=` target.
|
||||
`simplex:group:12` as a cron `deliver=` target or in a `hermes send` call.
|
||||
|
||||
## Attachments
|
||||
|
||||
|
|
@ -113,10 +113,10 @@ cronjob(
|
|||
)
|
||||
```
|
||||
|
||||
Or target a specific contact:
|
||||
Or target a specific contact via the cron job's `deliver:` field, or from a shell script with the [`hermes send` CLI](/guides/pipe-script-output):
|
||||
|
||||
```python
|
||||
send_message(target="simplex:<contact-id>", message="Done!")
|
||||
```bash
|
||||
hermes send simplex:<contact-id> "Done!"
|
||||
```
|
||||
|
||||
## Privacy notes
|
||||
|
|
|
|||
|
|
@ -653,6 +653,7 @@ const sidebars: SidebarsConfig = {
|
|||
'user-guide/messaging/line',
|
||||
'user-guide/messaging/simplex',
|
||||
'user-guide/messaging/ntfy',
|
||||
'user-guide/messaging/irc',
|
||||
'user-guide/messaging/open-webui',
|
||||
'user-guide/messaging/webhooks',
|
||||
],
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue