The architecture has been updated
This commit is contained in:
parent
805f7a017e
commit
a01257ead9
1119 changed files with 226 additions and 352 deletions
8
hermes_code/website/docs/reference/_category_.json
Normal file
8
hermes_code/website/docs/reference/_category_.json
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
{
|
||||
"label": "Reference",
|
||||
"position": 4,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "Complete reference for CLI commands, environment variables, and configuration."
|
||||
}
|
||||
}
|
||||
445
hermes_code/website/docs/reference/cli-commands.md
Normal file
445
hermes_code/website/docs/reference/cli-commands.md
Normal file
|
|
@ -0,0 +1,445 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
title: "CLI Commands Reference"
|
||||
description: "Authoritative reference for Hermes terminal commands and command families"
|
||||
---
|
||||
|
||||
# CLI Commands Reference
|
||||
|
||||
This page covers the **terminal commands** you run from your shell.
|
||||
|
||||
For in-chat slash commands, see [Slash Commands Reference](./slash-commands.md).
|
||||
|
||||
## Global entrypoint
|
||||
|
||||
```bash
|
||||
hermes [global-options] <command> [subcommand/options]
|
||||
```
|
||||
|
||||
### Global options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--version`, `-V` | Show version and exit. |
|
||||
| `--resume <session>`, `-r <session>` | Resume a previous session by ID or title. |
|
||||
| `--continue [name]`, `-c [name]` | Resume the most recent session, or the most recent session matching a title. |
|
||||
| `--worktree`, `-w` | Start in an isolated git worktree for parallel-agent workflows. |
|
||||
| `--yolo` | Bypass dangerous-command approval prompts. |
|
||||
| `--pass-session-id` | Include the session ID in the agent's system prompt. |
|
||||
|
||||
## Top-level commands
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `hermes chat` | Interactive or one-shot chat with the agent. |
|
||||
| `hermes model` | Interactively choose the default provider and model. |
|
||||
| `hermes gateway` | Run or manage the messaging gateway service. |
|
||||
| `hermes setup` | Interactive setup wizard for all or part of the configuration. |
|
||||
| `hermes whatsapp` | Configure and pair the WhatsApp bridge. |
|
||||
| `hermes login` / `logout` | Authenticate with OAuth-backed providers. |
|
||||
| `hermes status` | Show agent, auth, and platform status. |
|
||||
| `hermes cron` | Inspect and tick the cron scheduler. |
|
||||
| `hermes doctor` | Diagnose config and dependency issues. |
|
||||
| `hermes config` | Show, edit, migrate, and query configuration files. |
|
||||
| `hermes pairing` | Approve or revoke messaging pairing codes. |
|
||||
| `hermes skills` | Browse, install, publish, audit, and configure skills. |
|
||||
| `hermes honcho` | Manage Honcho cross-session memory integration. |
|
||||
| `hermes acp` | Run Hermes as an ACP server for editor integration. |
|
||||
| `hermes tools` | Configure enabled tools per platform. |
|
||||
| `hermes sessions` | Browse, export, prune, rename, and delete sessions. |
|
||||
| `hermes insights` | Show token/cost/activity analytics. |
|
||||
| `hermes claw` | OpenClaw migration helpers. |
|
||||
| `hermes version` | Show version information. |
|
||||
| `hermes update` | Pull latest code and reinstall dependencies. |
|
||||
| `hermes uninstall` | Remove Hermes from the system. |
|
||||
|
||||
## `hermes chat`
|
||||
|
||||
```bash
|
||||
hermes chat [options]
|
||||
```
|
||||
|
||||
Common options:
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `-q`, `--query "..."` | One-shot, non-interactive prompt. |
|
||||
| `-m`, `--model <model>` | Override the model for this run. |
|
||||
| `-t`, `--toolsets <csv>` | Enable a comma-separated set of toolsets. |
|
||||
| `--provider <provider>` | Force a provider: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`, `kilocode`. |
|
||||
| `-s`, `--skills <name>` | Preload one or more skills for the session (can be repeated or comma-separated). |
|
||||
| `-v`, `--verbose` | Verbose output. |
|
||||
| `-Q`, `--quiet` | Programmatic mode: suppress banner/spinner/tool previews. |
|
||||
| `--resume <session>` / `--continue [name]` | Resume a session directly from `chat`. |
|
||||
| `--worktree` | Create an isolated git worktree for this run. |
|
||||
| `--checkpoints` | Enable filesystem checkpoints before destructive file changes. |
|
||||
| `--yolo` | Skip approval prompts. |
|
||||
| `--pass-session-id` | Pass the session ID into the system prompt. |
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
hermes
|
||||
hermes chat -q "Summarize the latest PRs"
|
||||
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
|
||||
hermes chat --toolsets web,terminal,skills
|
||||
hermes chat --quiet -q "Return only JSON"
|
||||
hermes chat --worktree -q "Review this repo and open a PR"
|
||||
```
|
||||
|
||||
## `hermes model`
|
||||
|
||||
Interactive provider + model selector.
|
||||
|
||||
```bash
|
||||
hermes model
|
||||
```
|
||||
|
||||
Use this when you want to:
|
||||
- switch default providers
|
||||
- log into OAuth-backed providers during model selection
|
||||
- pick from provider-specific model lists
|
||||
- configure a custom/self-hosted endpoint
|
||||
- save the new default into config
|
||||
|
||||
### `/model` slash command (mid-session)
|
||||
|
||||
Switch models without leaving a session:
|
||||
|
||||
```
|
||||
/model # Show current model and available options
|
||||
/model claude-sonnet-4 # Switch model (auto-detects provider)
|
||||
/model zai:glm-5 # Switch provider and model
|
||||
/model custom:qwen-2.5 # Use model on your custom endpoint
|
||||
/model custom # Auto-detect model from custom endpoint
|
||||
/model custom:local:qwen-2.5 # Use a named custom provider
|
||||
/model openrouter:anthropic/claude-sonnet-4 # Switch back to cloud
|
||||
```
|
||||
|
||||
Provider and base URL changes are persisted to `config.yaml` automatically. When switching away from a custom endpoint, the stale base URL is cleared to prevent it leaking into other providers.
|
||||
|
||||
## `hermes gateway`
|
||||
|
||||
```bash
|
||||
hermes gateway <subcommand>
|
||||
```
|
||||
|
||||
Subcommands:
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `run` | Run the gateway in the foreground. |
|
||||
| `start` | Start the installed gateway service. |
|
||||
| `stop` | Stop the service. |
|
||||
| `restart` | Restart the service. |
|
||||
| `status` | Show service status. |
|
||||
| `install` | Install as a user service (`systemd` on Linux, `launchd` on macOS). |
|
||||
| `uninstall` | Remove the installed service. |
|
||||
| `setup` | Interactive messaging-platform setup. |
|
||||
|
||||
## `hermes setup`
|
||||
|
||||
```bash
|
||||
hermes setup [model|terminal|gateway|tools|agent] [--non-interactive] [--reset]
|
||||
```
|
||||
|
||||
Use the full wizard or jump into one section:
|
||||
|
||||
| Section | Description |
|
||||
|---------|-------------|
|
||||
| `model` | Provider and model setup. |
|
||||
| `terminal` | Terminal backend and sandbox setup. |
|
||||
| `gateway` | Messaging platform setup. |
|
||||
| `tools` | Enable/disable tools per platform. |
|
||||
| `agent` | Agent behavior settings. |
|
||||
|
||||
Options:
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--non-interactive` | Use defaults / environment values without prompts. |
|
||||
| `--reset` | Reset configuration to defaults before setup. |
|
||||
|
||||
## `hermes whatsapp`
|
||||
|
||||
```bash
|
||||
hermes whatsapp
|
||||
```
|
||||
|
||||
Runs the WhatsApp pairing/setup flow, including mode selection and QR-code pairing.
|
||||
|
||||
## `hermes login` / `hermes logout`
|
||||
|
||||
```bash
|
||||
hermes login [--provider nous|openai-codex] [--portal-url ...] [--inference-url ...]
|
||||
hermes logout [--provider nous|openai-codex]
|
||||
```
|
||||
|
||||
`login` supports:
|
||||
- Nous Portal OAuth/device flow
|
||||
- OpenAI Codex OAuth/device flow
|
||||
|
||||
Useful options for `login`:
|
||||
- `--no-browser`
|
||||
- `--timeout <seconds>`
|
||||
- `--ca-bundle <pem>`
|
||||
- `--insecure`
|
||||
|
||||
## `hermes status`
|
||||
|
||||
```bash
|
||||
hermes status [--all] [--deep]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--all` | Show all details in a shareable redacted format. |
|
||||
| `--deep` | Run deeper checks that may take longer. |
|
||||
|
||||
## `hermes cron`
|
||||
|
||||
```bash
|
||||
hermes cron <list|create|edit|pause|resume|run|remove|status|tick>
|
||||
```
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `list` | Show scheduled jobs. |
|
||||
| `create` / `add` | Create a scheduled job from a prompt, optionally attaching one or more skills via repeated `--skill`. |
|
||||
| `edit` | Update a job's schedule, prompt, name, delivery, repeat count, or attached skills. Supports `--clear-skills`, `--add-skill`, and `--remove-skill`. |
|
||||
| `pause` | Pause a job without deleting it. |
|
||||
| `resume` | Resume a paused job and compute its next future run. |
|
||||
| `run` | Trigger a job on the next scheduler tick. |
|
||||
| `remove` | Delete a scheduled job. |
|
||||
| `status` | Check whether the cron scheduler is running. |
|
||||
| `tick` | Run due jobs once and exit. |
|
||||
|
||||
## `hermes doctor`
|
||||
|
||||
```bash
|
||||
hermes doctor [--fix]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--fix` | Attempt automatic repairs where possible. |
|
||||
|
||||
## `hermes config`
|
||||
|
||||
```bash
|
||||
hermes config <subcommand>
|
||||
```
|
||||
|
||||
Subcommands:
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `show` | Show current config values. |
|
||||
| `edit` | Open `config.yaml` in your editor. |
|
||||
| `set <key> <value>` | Set a config value. |
|
||||
| `path` | Print the config file path. |
|
||||
| `env-path` | Print the `.env` file path. |
|
||||
| `check` | Check for missing or stale config. |
|
||||
| `migrate` | Add newly introduced options interactively. |
|
||||
|
||||
## `hermes pairing`
|
||||
|
||||
```bash
|
||||
hermes pairing <list|approve|revoke|clear-pending>
|
||||
```
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `list` | Show pending and approved users. |
|
||||
| `approve <platform> <code>` | Approve a pairing code. |
|
||||
| `revoke <platform> <user-id>` | Revoke a user's access. |
|
||||
| `clear-pending` | Clear pending pairing codes. |
|
||||
|
||||
## `hermes skills`
|
||||
|
||||
```bash
|
||||
hermes skills <subcommand>
|
||||
```
|
||||
|
||||
Subcommands:
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `browse` | Paginated browser for skill registries. |
|
||||
| `search` | Search skill registries. |
|
||||
| `install` | Install a skill. |
|
||||
| `inspect` | Preview a skill without installing it. |
|
||||
| `list` | List installed skills. |
|
||||
| `check` | Check installed hub skills for upstream updates. |
|
||||
| `update` | Reinstall hub skills with upstream changes when available. |
|
||||
| `audit` | Re-scan installed hub skills. |
|
||||
| `uninstall` | Remove a hub-installed skill. |
|
||||
| `publish` | Publish a skill to a registry. |
|
||||
| `snapshot` | Export/import skill configurations. |
|
||||
| `tap` | Manage custom skill sources. |
|
||||
| `config` | Interactive enable/disable configuration for skills by platform. |
|
||||
|
||||
Common examples:
|
||||
|
||||
```bash
|
||||
hermes skills browse
|
||||
hermes skills browse --source official
|
||||
hermes skills search react --source skills-sh
|
||||
hermes skills search https://mintlify.com/docs --source well-known
|
||||
hermes skills inspect official/security/1password
|
||||
hermes skills inspect skills-sh/vercel-labs/json-render/json-render-react
|
||||
hermes skills install official/migration/openclaw-migration
|
||||
hermes skills install skills-sh/anthropics/skills/pdf --force
|
||||
hermes skills check
|
||||
hermes skills update
|
||||
hermes skills config
|
||||
```
|
||||
|
||||
Notes:
|
||||
- `--force` can override non-dangerous policy blocks for third-party/community skills.
|
||||
- `--force` does not override a `dangerous` scan verdict.
|
||||
- `--source skills-sh` searches the public `skills.sh` directory.
|
||||
- `--source well-known` lets you point Hermes at a site exposing `/.well-known/skills/index.json`.
|
||||
|
||||
## `hermes honcho`
|
||||
|
||||
```bash
|
||||
hermes honcho <subcommand>
|
||||
```
|
||||
|
||||
Subcommands:
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `setup` | Interactive Honcho setup wizard. |
|
||||
| `status` | Show current Honcho config and connection status. |
|
||||
| `sessions` | List known Honcho session mappings. |
|
||||
| `map` | Map the current directory to a Honcho session name. |
|
||||
| `peer` | Show or update peer names and dialectic reasoning level. |
|
||||
| `mode` | Show or set memory mode: `hybrid`, `honcho`, or `local`. |
|
||||
| `tokens` | Show or set token budgets for context and dialectic. |
|
||||
| `identity` | Seed or show the AI peer identity representation. |
|
||||
| `migrate` | Migration guide from openclaw-honcho to Hermes Honcho. |
|
||||
|
||||
## `hermes acp`
|
||||
|
||||
```bash
|
||||
hermes acp
|
||||
```
|
||||
|
||||
Starts Hermes as an ACP (Agent Client Protocol) stdio server for editor integration.
|
||||
|
||||
Related entrypoints:
|
||||
|
||||
```bash
|
||||
hermes-acp
|
||||
python -m acp_adapter
|
||||
```
|
||||
|
||||
Install support first:
|
||||
|
||||
```bash
|
||||
pip install -e '.[acp]'
|
||||
```
|
||||
|
||||
See [ACP Editor Integration](../user-guide/features/acp.md) and [ACP Internals](../developer-guide/acp-internals.md).
|
||||
|
||||
## `hermes mcp`
|
||||
|
||||
```bash
|
||||
hermes mcp <subcommand>
|
||||
```
|
||||
|
||||
Manage MCP (Model Context Protocol) server configurations.
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `add <name> [--url URL] [--command CMD] [--args ...] [--auth oauth\|header]` | Add an MCP server with automatic tool discovery. |
|
||||
| `remove <name>` (alias: `rm`) | Remove an MCP server from config. |
|
||||
| `list` (alias: `ls`) | List configured MCP servers. |
|
||||
| `test <name>` | Test connection to an MCP server. |
|
||||
| `configure <name>` (alias: `config`) | Toggle tool selection for a server. |
|
||||
|
||||
See [MCP Config Reference](./mcp-config-reference.md) and [Use MCP with Hermes](../guides/use-mcp-with-hermes.md).
|
||||
|
||||
## `hermes plugins`
|
||||
|
||||
```bash
|
||||
hermes plugins <subcommand>
|
||||
```
|
||||
|
||||
Manage Hermes Agent plugins.
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `install <identifier> [--force]` | Install a plugin from a Git URL or `owner/repo`. |
|
||||
| `update <name>` | Pull latest changes for an installed plugin. |
|
||||
| `remove <name>` (aliases: `rm`, `uninstall`) | Remove an installed plugin. |
|
||||
| `list` (alias: `ls`) | List installed plugins. |
|
||||
|
||||
See [Plugins](../user-guide/features/plugins.md) and [Build a Hermes Plugin](../guides/build-a-hermes-plugin.md).
|
||||
|
||||
## `hermes tools`
|
||||
|
||||
```bash
|
||||
hermes tools [--summary]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--summary` | Print the current enabled-tools summary and exit. |
|
||||
|
||||
Without `--summary`, this launches the interactive per-platform tool configuration UI.
|
||||
|
||||
## `hermes sessions`
|
||||
|
||||
```bash
|
||||
hermes sessions <subcommand>
|
||||
```
|
||||
|
||||
Subcommands:
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `list` | List recent sessions. |
|
||||
| `browse` | Interactive session picker with search and resume. |
|
||||
| `export <output> [--session-id ID]` | Export sessions to JSONL. |
|
||||
| `delete <session-id>` | Delete one session. |
|
||||
| `prune` | Delete old sessions. |
|
||||
| `stats` | Show session-store statistics. |
|
||||
| `rename <session-id> <title>` | Set or change a session title. |
|
||||
|
||||
## `hermes insights`
|
||||
|
||||
```bash
|
||||
hermes insights [--days N] [--source platform]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--days <n>` | Analyze the last `n` days (default: 30). |
|
||||
| `--source <platform>` | Filter by source such as `cli`, `telegram`, or `discord`. |
|
||||
|
||||
## `hermes claw`
|
||||
|
||||
```bash
|
||||
hermes claw migrate
|
||||
```
|
||||
|
||||
Used to migrate settings, memories, skills, and keys from OpenClaw to Hermes.
|
||||
|
||||
## Maintenance commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `hermes version` | Print version information. |
|
||||
| `hermes update` | Pull latest changes and reinstall dependencies. |
|
||||
| `hermes uninstall [--full] [--yes]` | Remove Hermes, optionally deleting all config/data. |
|
||||
|
||||
## See also
|
||||
|
||||
- [Slash Commands Reference](./slash-commands.md)
|
||||
- [CLI Interface](../user-guide/cli.md)
|
||||
- [Sessions](../user-guide/sessions.md)
|
||||
- [Skills System](../user-guide/features/skills.md)
|
||||
- [Skins & Themes](../user-guide/features/skins.md)
|
||||
302
hermes_code/website/docs/reference/environment-variables.md
Normal file
302
hermes_code/website/docs/reference/environment-variables.md
Normal file
|
|
@ -0,0 +1,302 @@
|
|||
---
|
||||
sidebar_position: 2
|
||||
title: "Environment Variables"
|
||||
description: "Complete reference of all environment variables used by Hermes Agent"
|
||||
---
|
||||
|
||||
# Environment Variables Reference
|
||||
|
||||
All variables go in `~/.hermes/.env`. You can also set them with `hermes config set VAR value`.
|
||||
|
||||
## LLM Providers
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `OPENROUTER_API_KEY` | OpenRouter API key (recommended for flexibility) |
|
||||
| `OPENROUTER_BASE_URL` | Override the OpenRouter-compatible base URL |
|
||||
| `AI_GATEWAY_API_KEY` | Vercel AI Gateway API key ([ai-gateway.vercel.sh](https://ai-gateway.vercel.sh)) |
|
||||
| `AI_GATEWAY_BASE_URL` | Override AI Gateway base URL (default: `https://ai-gateway.vercel.sh/v1`) |
|
||||
| `OPENAI_API_KEY` | API key for custom OpenAI-compatible endpoints (used with `OPENAI_BASE_URL`) |
|
||||
| `OPENAI_BASE_URL` | Base URL for custom endpoint (VLLM, SGLang, etc.) |
|
||||
| `COPILOT_GITHUB_TOKEN` | GitHub token for Copilot API — first priority (OAuth `gho_*` or fine-grained PAT `github_pat_*`; classic PATs `ghp_*` are **not supported**) |
|
||||
| `GH_TOKEN` | GitHub token — second priority for Copilot (also used by `gh` CLI) |
|
||||
| `GITHUB_TOKEN` | GitHub token — third priority for Copilot |
|
||||
| `HERMES_COPILOT_ACP_COMMAND` | Override Copilot ACP CLI binary path (default: `copilot`) |
|
||||
| `COPILOT_CLI_PATH` | Alias for `HERMES_COPILOT_ACP_COMMAND` |
|
||||
| `HERMES_COPILOT_ACP_ARGS` | Override Copilot ACP arguments (default: `--acp --stdio`) |
|
||||
| `COPILOT_ACP_BASE_URL` | Override Copilot ACP base URL |
|
||||
| `GLM_API_KEY` | z.ai / ZhipuAI GLM API key ([z.ai](https://z.ai)) |
|
||||
| `ZAI_API_KEY` | Alias for `GLM_API_KEY` |
|
||||
| `Z_AI_API_KEY` | Alias for `GLM_API_KEY` |
|
||||
| `GLM_BASE_URL` | Override z.ai base URL (default: `https://api.z.ai/api/paas/v4`) |
|
||||
| `KIMI_API_KEY` | Kimi / Moonshot AI API key ([moonshot.ai](https://platform.moonshot.ai)) |
|
||||
| `KIMI_BASE_URL` | Override Kimi base URL (default: `https://api.moonshot.ai/v1`) |
|
||||
| `MINIMAX_API_KEY` | MiniMax API key — global endpoint ([minimax.io](https://www.minimax.io)) |
|
||||
| `MINIMAX_BASE_URL` | Override MiniMax base URL (default: `https://api.minimax.io/v1`) |
|
||||
| `MINIMAX_CN_API_KEY` | MiniMax API key — China endpoint ([minimaxi.com](https://www.minimaxi.com)) |
|
||||
| `MINIMAX_CN_BASE_URL` | Override MiniMax China base URL (default: `https://api.minimaxi.com/v1`) |
|
||||
| `KILOCODE_API_KEY` | Kilo Code API key ([kilo.ai](https://kilo.ai)) |
|
||||
| `KILOCODE_BASE_URL` | Override Kilo Code base URL (default: `https://api.kilo.ai/api/gateway`) |
|
||||
| `ANTHROPIC_API_KEY` | Anthropic Console API key ([console.anthropic.com](https://console.anthropic.com/)) |
|
||||
| `ANTHROPIC_TOKEN` | Manual or legacy Anthropic OAuth/setup-token override |
|
||||
| `DASHSCOPE_API_KEY` | Alibaba Cloud DashScope API key for Qwen models ([modelstudio.console.alibabacloud.com](https://modelstudio.console.alibabacloud.com/)) |
|
||||
| `DASHSCOPE_BASE_URL` | Custom DashScope base URL (default: international endpoint) |
|
||||
| `DEEPSEEK_API_KEY` | DeepSeek API key for direct DeepSeek access ([platform.deepseek.com](https://platform.deepseek.com/api_keys)) |
|
||||
| `DEEPSEEK_BASE_URL` | Custom DeepSeek API base URL |
|
||||
| `OPENCODE_ZEN_API_KEY` | OpenCode Zen API key — pay-as-you-go access to curated models ([opencode.ai](https://opencode.ai/auth)) |
|
||||
| `OPENCODE_ZEN_BASE_URL` | Override OpenCode Zen base URL |
|
||||
| `OPENCODE_GO_API_KEY` | OpenCode Go API key — $10/month subscription for open models ([opencode.ai](https://opencode.ai/auth)) |
|
||||
| `OPENCODE_GO_BASE_URL` | Override OpenCode Go base URL |
|
||||
| `CLAUDE_CODE_OAUTH_TOKEN` | Explicit Claude Code token override if you export one manually |
|
||||
| `HERMES_MODEL` | Preferred model name (checked before `LLM_MODEL`, used by gateway) |
|
||||
| `LLM_MODEL` | Default model name (fallback when not set in config.yaml) |
|
||||
| `VOICE_TOOLS_OPENAI_KEY` | Preferred OpenAI key for OpenAI speech-to-text and text-to-speech providers |
|
||||
| `HERMES_LOCAL_STT_COMMAND` | Optional local speech-to-text command template. Supports `{input_path}`, `{output_dir}`, `{language}`, and `{model}` placeholders |
|
||||
| `HERMES_LOCAL_STT_LANGUAGE` | Default language passed to `HERMES_LOCAL_STT_COMMAND` or auto-detected local `whisper` CLI fallback (default: `en`) |
|
||||
| `HERMES_HOME` | Override Hermes config directory (default: `~/.hermes`). Also scopes the gateway PID file and systemd service name, so multiple installations can run concurrently |
|
||||
|
||||
## Provider Auth (OAuth)
|
||||
|
||||
For native Anthropic auth, Hermes prefers Claude Code's own credential files when they exist because those credentials can refresh automatically. Environment variables such as `ANTHROPIC_TOKEN` remain useful as manual overrides, but they are no longer the preferred path for Claude Pro/Max login.
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `HERMES_INFERENCE_PROVIDER` | Override provider selection: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`, `kilocode` (default: `auto`) |
|
||||
| `HERMES_PORTAL_BASE_URL` | Override Nous Portal URL (for development/testing) |
|
||||
| `NOUS_INFERENCE_BASE_URL` | Override Nous inference API URL |
|
||||
| `HERMES_NOUS_MIN_KEY_TTL_SECONDS` | Min agent key TTL before re-mint (default: 1800 = 30min) |
|
||||
| `HERMES_NOUS_TIMEOUT_SECONDS` | HTTP timeout for Nous credential / token flows |
|
||||
| `HERMES_DUMP_REQUESTS` | Dump API request payloads to log files (`true`/`false`) |
|
||||
| `HERMES_PREFILL_MESSAGES_FILE` | Path to a JSON file of ephemeral prefill messages injected at API-call time |
|
||||
| `HERMES_TIMEZONE` | IANA timezone override (for example `America/New_York`) |
|
||||
|
||||
## Tool APIs
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `PARALLEL_API_KEY` | AI-native web search ([parallel.ai](https://parallel.ai/)) |
|
||||
| `FIRECRAWL_API_KEY` | Web scraping ([firecrawl.dev](https://firecrawl.dev/)) |
|
||||
| `FIRECRAWL_API_URL` | Custom Firecrawl API endpoint for self-hosted instances (optional) |
|
||||
| `TAVILY_API_KEY` | Tavily API key for AI-native web search, extract, and crawl ([app.tavily.com](https://app.tavily.com/home)) |
|
||||
| `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/)) |
|
||||
| `BROWSER_CDP_URL` | Chrome DevTools Protocol URL for local browser (set via `/browser connect`, e.g. `ws://localhost:9222`) |
|
||||
| `BROWSER_INACTIVITY_TIMEOUT` | Browser session inactivity timeout in seconds |
|
||||
| `FAL_KEY` | Image generation ([fal.ai](https://fal.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`) |
|
||||
| `GROQ_BASE_URL` | Override the Groq OpenAI-compatible STT endpoint |
|
||||
| `STT_OPENAI_MODEL` | Override the OpenAI STT model (default: `whisper-1`) |
|
||||
| `STT_OPENAI_BASE_URL` | Override the OpenAI-compatible STT endpoint |
|
||||
| `GITHUB_TOKEN` | GitHub token for Skills Hub (higher API rate limits, skill publish) |
|
||||
| `HONCHO_API_KEY` | Cross-session user modeling ([honcho.dev](https://honcho.dev/)) |
|
||||
| `HONCHO_BASE_URL` | Base URL for self-hosted Honcho instances (default: Honcho cloud). No API key required for local instances |
|
||||
| `TINKER_API_KEY` | RL training ([tinker-console.thinkingmachines.ai](https://tinker-console.thinkingmachines.ai/)) |
|
||||
| `WANDB_API_KEY` | RL training metrics ([wandb.ai](https://wandb.ai/)) |
|
||||
| `DAYTONA_API_KEY` | Daytona cloud sandboxes ([daytona.io](https://daytona.io/)) |
|
||||
|
||||
## Terminal Backend
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `TERMINAL_ENV` | Backend: `local`, `docker`, `ssh`, `singularity`, `modal`, `daytona` |
|
||||
| `TERMINAL_DOCKER_IMAGE` | Docker image (default: `python:3.11`) |
|
||||
| `TERMINAL_DOCKER_FORWARD_ENV` | JSON array of env var names to explicitly forward into Docker terminal sessions |
|
||||
| `TERMINAL_DOCKER_VOLUMES` | Additional Docker volume mounts (comma-separated `host:container` pairs) |
|
||||
| `TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE` | Advanced opt-in: mount the launch cwd into Docker `/workspace` (`true`/`false`, default: `false`) |
|
||||
| `TERMINAL_SINGULARITY_IMAGE` | Singularity image or `.sif` path |
|
||||
| `TERMINAL_MODAL_IMAGE` | Modal container image |
|
||||
| `TERMINAL_DAYTONA_IMAGE` | Daytona sandbox image |
|
||||
| `TERMINAL_TIMEOUT` | Command timeout in seconds |
|
||||
| `TERMINAL_LIFETIME_SECONDS` | Max lifetime for terminal sessions in seconds |
|
||||
| `TERMINAL_CWD` | Working directory for all terminal sessions |
|
||||
| `SUDO_PASSWORD` | Enable sudo without interactive prompt |
|
||||
|
||||
## SSH Backend
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `TERMINAL_SSH_HOST` | Remote server hostname |
|
||||
| `TERMINAL_SSH_USER` | SSH username |
|
||||
| `TERMINAL_SSH_PORT` | SSH port (default: 22) |
|
||||
| `TERMINAL_SSH_KEY` | Path to private key |
|
||||
| `TERMINAL_SSH_PERSISTENT` | Override persistent shell for SSH (default: follows `TERMINAL_PERSISTENT_SHELL`) |
|
||||
|
||||
## Container Resources (Docker, Singularity, Modal, Daytona)
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `TERMINAL_CONTAINER_CPU` | CPU cores (default: 1) |
|
||||
| `TERMINAL_CONTAINER_MEMORY` | Memory in MB (default: 5120) |
|
||||
| `TERMINAL_CONTAINER_DISK` | Disk in MB (default: 51200) |
|
||||
| `TERMINAL_CONTAINER_PERSISTENT` | Persist container filesystem across sessions (default: `true`) |
|
||||
| `TERMINAL_SANDBOX_DIR` | Host directory for workspaces and overlays (default: `~/.hermes/sandboxes/`) |
|
||||
|
||||
## Persistent Shell
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `TERMINAL_PERSISTENT_SHELL` | Enable persistent shell for non-local backends (default: `true`). Also settable via `terminal.persistent_shell` in config.yaml |
|
||||
| `TERMINAL_LOCAL_PERSISTENT` | Enable persistent shell for local backend (default: `false`) |
|
||||
| `TERMINAL_SSH_PERSISTENT` | Override persistent shell for SSH backend (default: follows `TERMINAL_PERSISTENT_SHELL`) |
|
||||
|
||||
## Messaging
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `TELEGRAM_BOT_TOKEN` | Telegram bot token (from @BotFather) |
|
||||
| `TELEGRAM_ALLOWED_USERS` | Comma-separated user IDs allowed to use the bot |
|
||||
| `TELEGRAM_HOME_CHANNEL` | Default Telegram chat/channel for cron delivery |
|
||||
| `TELEGRAM_HOME_CHANNEL_NAME` | Display name for the Telegram home channel |
|
||||
| `DISCORD_BOT_TOKEN` | Discord bot token |
|
||||
| `DISCORD_ALLOWED_USERS` | Comma-separated Discord user IDs allowed to use the bot |
|
||||
| `DISCORD_HOME_CHANNEL` | Default Discord channel for cron delivery |
|
||||
| `DISCORD_HOME_CHANNEL_NAME` | Display name for the Discord home channel |
|
||||
| `DISCORD_REQUIRE_MENTION` | Require an @mention before responding in server channels |
|
||||
| `DISCORD_FREE_RESPONSE_CHANNELS` | Comma-separated channel IDs where mention is not required |
|
||||
| `DISCORD_AUTO_THREAD` | Auto-thread long replies when supported |
|
||||
| `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_HOME_CHANNEL` | Default Slack channel for cron delivery |
|
||||
| `SLACK_HOME_CHANNEL_NAME` | Display name for the Slack home channel |
|
||||
| `WHATSAPP_ENABLED` | Enable the WhatsApp bridge (`true`/`false`) |
|
||||
| `WHATSAPP_MODE` | `bot` (separate number) or `self-chat` (message yourself) |
|
||||
| `WHATSAPP_ALLOWED_USERS` | Comma-separated phone numbers (with country code, no `+`) |
|
||||
| `SIGNAL_HTTP_URL` | signal-cli daemon HTTP endpoint (for example `http://127.0.0.1:8080`) |
|
||||
| `SIGNAL_ACCOUNT` | Bot phone number in E.164 format |
|
||||
| `SIGNAL_ALLOWED_USERS` | Comma-separated E.164 phone numbers or UUIDs |
|
||||
| `SIGNAL_GROUP_ALLOWED_USERS` | Comma-separated group IDs, or `*` for all groups |
|
||||
| `SIGNAL_HOME_CHANNEL_NAME` | Display name for the Signal home channel |
|
||||
| `SIGNAL_IGNORE_STORIES` | Ignore Signal stories/status updates |
|
||||
| `SIGNAL_ALLOW_ALL_USERS` | Allow all Signal users without an allowlist |
|
||||
| `TWILIO_ACCOUNT_SID` | Twilio Account SID (shared with telephony skill) |
|
||||
| `TWILIO_AUTH_TOKEN` | Twilio Auth Token (shared with telephony skill) |
|
||||
| `TWILIO_PHONE_NUMBER` | Twilio phone number in E.164 format (shared with telephony skill) |
|
||||
| `SMS_WEBHOOK_PORT` | Webhook listener port for inbound SMS (default: `8080`) |
|
||||
| `SMS_ALLOWED_USERS` | Comma-separated E.164 phone numbers allowed to chat |
|
||||
| `SMS_ALLOW_ALL_USERS` | Allow all SMS senders without an allowlist |
|
||||
| `SMS_HOME_CHANNEL` | Phone number for cron job / notification delivery |
|
||||
| `SMS_HOME_CHANNEL_NAME` | Display name for the SMS home channel |
|
||||
| `EMAIL_ADDRESS` | Email address for the Email gateway adapter |
|
||||
| `EMAIL_PASSWORD` | Password or app password for the email account |
|
||||
| `EMAIL_IMAP_HOST` | IMAP hostname for the email adapter |
|
||||
| `EMAIL_IMAP_PORT` | IMAP port |
|
||||
| `EMAIL_SMTP_HOST` | SMTP hostname for the email adapter |
|
||||
| `EMAIL_SMTP_PORT` | SMTP port |
|
||||
| `EMAIL_ALLOWED_USERS` | Comma-separated email addresses allowed to message the bot |
|
||||
| `EMAIL_HOME_ADDRESS` | Default recipient for proactive email delivery |
|
||||
| `EMAIL_HOME_ADDRESS_NAME` | Display name for the email home target |
|
||||
| `EMAIL_POLL_INTERVAL` | Email polling interval in seconds |
|
||||
| `EMAIL_ALLOW_ALL_USERS` | Allow all inbound email senders |
|
||||
| `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 |
|
||||
| `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_HOME_CHANNEL` | Channel ID for proactive message delivery (cron, notifications) |
|
||||
| `MATTERMOST_REPLY_MODE` | Reply style: `thread` (threaded replies) or `off` (flat messages, default) |
|
||||
| `MATRIX_HOMESERVER` | Matrix homeserver URL (e.g. `https://matrix.org`) |
|
||||
| `MATRIX_ACCESS_TOKEN` | Matrix access token for bot authentication |
|
||||
| `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_HOME_ROOM` | Room ID for proactive message delivery (e.g. `!abc123:matrix.org`) |
|
||||
| `MATRIX_ENCRYPTION` | Enable end-to-end encryption (`true`/`false`, default: `false`) |
|
||||
| `HASS_TOKEN` | Home Assistant Long-Lived Access Token (enables HA platform + tools) |
|
||||
| `HASS_URL` | Home Assistant URL (default: `http://homeassistant.local:8123`) |
|
||||
| `WEBHOOK_ENABLED` | Enable the webhook platform adapter (`true`/`false`) |
|
||||
| `WEBHOOK_PORT` | HTTP server port for receiving webhooks (default: `8644`) |
|
||||
| `WEBHOOK_SECRET` | Global HMAC secret for webhook signature validation (used as fallback when routes don't specify their own) |
|
||||
| `API_SERVER_ENABLED` | Enable the OpenAI-compatible API server (`true`/`false`). Runs alongside other platforms. |
|
||||
| `API_SERVER_KEY` | Bearer token for API server authentication. Strongly recommended; required for any network-accessible deployment. |
|
||||
| `API_SERVER_CORS_ORIGINS` | Comma-separated browser origins allowed to call the API server directly (for example `http://localhost:3000,http://127.0.0.1:3000`). Default: disabled. |
|
||||
| `API_SERVER_PORT` | Port for the API server (default: `8642`) |
|
||||
| `API_SERVER_HOST` | Host/bind address for the API server (default: `127.0.0.1`). Use `0.0.0.0` for network access only with `API_SERVER_KEY` and a narrow `API_SERVER_CORS_ORIGINS` allowlist. |
|
||||
| `MESSAGING_CWD` | Working directory for terminal commands in messaging mode (default: `~`) |
|
||||
| `GATEWAY_ALLOWED_USERS` | Comma-separated user IDs allowed across all platforms |
|
||||
| `GATEWAY_ALLOW_ALL_USERS` | Allow all users without allowlists (`true`/`false`, default: `false`) |
|
||||
|
||||
## Agent Behavior
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `HERMES_MAX_ITERATIONS` | Max tool-calling iterations per conversation (default: 90) |
|
||||
| `HERMES_TOOL_PROGRESS` | Deprecated compatibility variable for tool progress display. Prefer `display.tool_progress` in `config.yaml`. |
|
||||
| `HERMES_TOOL_PROGRESS_MODE` | Deprecated compatibility variable for tool progress mode. Prefer `display.tool_progress` in `config.yaml`. |
|
||||
| `HERMES_HUMAN_DELAY_MODE` | Response pacing: `off`/`natural`/`custom` |
|
||||
| `HERMES_HUMAN_DELAY_MIN_MS` | Custom delay range minimum (ms) |
|
||||
| `HERMES_HUMAN_DELAY_MAX_MS` | Custom delay range maximum (ms) |
|
||||
| `HERMES_QUIET` | Suppress non-essential output (`true`/`false`) |
|
||||
| `HERMES_API_TIMEOUT` | LLM API call timeout in seconds (default: `900`) |
|
||||
| `HERMES_EXEC_ASK` | Enable execution approval prompts in gateway mode (`true`/`false`) |
|
||||
| `HERMES_ENABLE_PROJECT_PLUGINS` | Enable auto-discovery of repo-local plugins from `./.hermes/plugins/` (`true`/`false`, default: `false`) |
|
||||
| `HERMES_BACKGROUND_NOTIFICATIONS` | Background process notification mode in gateway: `all` (default), `result`, `error`, `off` |
|
||||
| `HERMES_EPHEMERAL_SYSTEM_PROMPT` | Ephemeral system prompt injected at API-call time (never persisted to sessions) |
|
||||
|
||||
## Session Settings
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `SESSION_IDLE_MINUTES` | Reset sessions after N minutes of inactivity (default: 1440) |
|
||||
| `SESSION_RESET_HOUR` | Daily reset hour in 24h format (default: 4 = 4am) |
|
||||
|
||||
## Context Compression (config.yaml only)
|
||||
|
||||
Context compression is configured exclusively through the `compression` section in `config.yaml` — there are no environment variables for it.
|
||||
|
||||
```yaml
|
||||
compression:
|
||||
enabled: true
|
||||
threshold: 0.50
|
||||
summary_model: google/gemini-3-flash-preview
|
||||
summary_provider: auto
|
||||
summary_base_url: null # Custom OpenAI-compatible endpoint for summaries
|
||||
```
|
||||
|
||||
## Auxiliary Task Overrides
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `AUXILIARY_VISION_PROVIDER` | Override provider for vision tasks |
|
||||
| `AUXILIARY_VISION_MODEL` | Override model for vision tasks |
|
||||
| `AUXILIARY_VISION_BASE_URL` | Direct OpenAI-compatible endpoint for vision tasks |
|
||||
| `AUXILIARY_VISION_API_KEY` | API key paired with `AUXILIARY_VISION_BASE_URL` |
|
||||
| `AUXILIARY_WEB_EXTRACT_PROVIDER` | Override provider for web extraction/summarization |
|
||||
| `AUXILIARY_WEB_EXTRACT_MODEL` | Override model for web extraction/summarization |
|
||||
| `AUXILIARY_WEB_EXTRACT_BASE_URL` | Direct OpenAI-compatible endpoint for web extraction/summarization |
|
||||
| `AUXILIARY_WEB_EXTRACT_API_KEY` | API key paired with `AUXILIARY_WEB_EXTRACT_BASE_URL` |
|
||||
|
||||
For task-specific direct endpoints, Hermes uses the task's configured API key or `OPENAI_API_KEY`. It does not reuse `OPENROUTER_API_KEY` for those custom endpoints.
|
||||
|
||||
## Fallback Model (config.yaml only)
|
||||
|
||||
The primary model fallback is configured exclusively through `config.yaml` — there are no environment variables for it. Add a `fallback_model` section with `provider` and `model` keys to enable automatic failover when your main model encounters errors.
|
||||
|
||||
```yaml
|
||||
fallback_model:
|
||||
provider: openrouter
|
||||
model: anthropic/claude-sonnet-4
|
||||
```
|
||||
|
||||
See [Fallback Providers](/docs/user-guide/features/fallback-providers) for full details.
|
||||
|
||||
## Provider Routing (config.yaml only)
|
||||
|
||||
These go in `~/.hermes/config.yaml` under the `provider_routing` section:
|
||||
|
||||
| Key | Description |
|
||||
|-----|-------------|
|
||||
| `sort` | Sort providers: `"price"` (default), `"throughput"`, or `"latency"` |
|
||||
| `only` | List of provider slugs to allow (e.g., `["anthropic", "google"]`) |
|
||||
| `ignore` | List of provider slugs to skip |
|
||||
| `order` | List of provider slugs to try in order |
|
||||
| `require_parameters` | Only use providers supporting all request params (`true`/`false`) |
|
||||
| `data_collection` | `"allow"` (default) or `"deny"` to exclude data-storing providers |
|
||||
|
||||
:::tip
|
||||
Use `hermes config set` to set environment variables — it automatically saves them to the right file (`.env` for secrets, `config.yaml` for everything else).
|
||||
:::
|
||||
481
hermes_code/website/docs/reference/faq.md
Normal file
481
hermes_code/website/docs/reference/faq.md
Normal file
|
|
@ -0,0 +1,481 @@
|
|||
---
|
||||
sidebar_position: 3
|
||||
title: "FAQ & Troubleshooting"
|
||||
description: "Frequently asked questions and solutions to common issues with Hermes Agent"
|
||||
---
|
||||
|
||||
# FAQ & Troubleshooting
|
||||
|
||||
Quick answers and fixes for the most common questions and issues.
|
||||
|
||||
---
|
||||
|
||||
## Frequently Asked Questions
|
||||
|
||||
### What LLM providers work with Hermes?
|
||||
|
||||
Hermes Agent works with any OpenAI-compatible API. Supported providers include:
|
||||
|
||||
- **[OpenRouter](https://openrouter.ai/)** — access hundreds of models through one API key (recommended for flexibility)
|
||||
- **Nous Portal** — Nous Research's own inference endpoint
|
||||
- **OpenAI** — GPT-4o, o1, o3, etc.
|
||||
- **Anthropic** — Claude models (via OpenRouter or compatible proxy)
|
||||
- **Google** — Gemini models (via OpenRouter or compatible proxy)
|
||||
- **z.ai / ZhipuAI** — GLM models
|
||||
- **Kimi / Moonshot AI** — Kimi models
|
||||
- **MiniMax** — global and China endpoints
|
||||
- **Local models** — via [Ollama](https://ollama.com/), [vLLM](https://docs.vllm.ai/), [llama.cpp](https://github.com/ggerganov/llama.cpp), [SGLang](https://github.com/sgl-project/sglang), or any OpenAI-compatible server
|
||||
|
||||
Set your provider with `hermes model` or by editing `~/.hermes/.env`. See the [Environment Variables](./environment-variables.md) reference for all provider keys.
|
||||
|
||||
### Does it work on Windows?
|
||||
|
||||
**Not natively.** Hermes Agent requires a Unix-like environment. On Windows, install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and run Hermes from inside it. The standard install command works perfectly in WSL2:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
### Is my data sent anywhere?
|
||||
|
||||
API calls go **only to the LLM provider you configure** (e.g., OpenRouter, your local Ollama instance). Hermes Agent does not collect telemetry, usage data, or analytics. Your conversations, memory, and skills are stored locally in `~/.hermes/`.
|
||||
|
||||
### Can I use it offline / with local models?
|
||||
|
||||
Yes. Run `hermes model`, select **Custom endpoint**, and enter your server's URL:
|
||||
|
||||
```bash
|
||||
hermes model
|
||||
# Select: Custom endpoint (enter URL manually)
|
||||
# API base URL: http://localhost:11434/v1
|
||||
# API key: ollama
|
||||
# Model name: qwen3.5:27b
|
||||
# Context length: 32768 ← set this to match your server's actual context window
|
||||
```
|
||||
|
||||
Or configure it directly in `config.yaml`:
|
||||
|
||||
```yaml
|
||||
model:
|
||||
default: qwen3.5:27b
|
||||
provider: custom
|
||||
base_url: http://localhost:11434/v1
|
||||
```
|
||||
|
||||
Hermes persists the endpoint, provider, and base URL in `config.yaml` so it survives restarts. If your local server has exactly one model loaded, `/model custom` auto-detects it. You can also set `provider: custom` in config.yaml — it's a first-class provider, not an alias for anything else.
|
||||
|
||||
This works with Ollama, vLLM, llama.cpp server, SGLang, LocalAI, and others. See the [Configuration guide](../user-guide/configuration.md) for details.
|
||||
|
||||
:::tip Ollama users
|
||||
If you set a custom `num_ctx` in Ollama (e.g., `ollama run --num_ctx 16384`), make sure to set the matching context length in Hermes — Ollama's `/api/show` reports the model's *maximum* context, not the effective `num_ctx` you configured.
|
||||
:::
|
||||
|
||||
### How much does it cost?
|
||||
|
||||
Hermes Agent itself is **free and open-source** (MIT license). You pay only for the LLM API usage from your chosen provider. Local models are completely free to run.
|
||||
|
||||
### Can multiple people use one instance?
|
||||
|
||||
Yes. The [messaging gateway](../user-guide/messaging/index.md) lets multiple users interact with the same Hermes Agent instance via Telegram, Discord, Slack, WhatsApp, or Home Assistant. Access is controlled through allowlists (specific user IDs) and DM pairing (first user to message claims access).
|
||||
|
||||
### What's the difference between memory and skills?
|
||||
|
||||
- **Memory** stores **facts** — things the agent knows about you, your projects, and preferences. Memories are retrieved automatically based on relevance.
|
||||
- **Skills** store **procedures** — step-by-step instructions for how to do things. Skills are recalled when the agent encounters a similar task.
|
||||
|
||||
Both persist across sessions. See [Memory](../user-guide/features/memory.md) and [Skills](../user-guide/features/skills.md) for details.
|
||||
|
||||
### Can I use it in my own Python project?
|
||||
|
||||
Yes. Import the `AIAgent` class and use Hermes programmatically:
|
||||
|
||||
```python
|
||||
from hermes.agent import AIAgent
|
||||
|
||||
agent = AIAgent(model="openrouter/nous/hermes-3-llama-3.1-70b")
|
||||
response = agent.chat("Explain quantum computing briefly")
|
||||
```
|
||||
|
||||
See the [Python Library guide](../user-guide/features/code-execution.md) for full API usage.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Installation Issues
|
||||
|
||||
#### `hermes: command not found` after installation
|
||||
|
||||
**Cause:** Your shell hasn't reloaded the updated PATH.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Reload your shell profile
|
||||
source ~/.bashrc # bash
|
||||
source ~/.zshrc # zsh
|
||||
|
||||
# Or start a new terminal session
|
||||
```
|
||||
|
||||
If it still doesn't work, verify the install location:
|
||||
```bash
|
||||
which hermes
|
||||
ls ~/.local/bin/hermes
|
||||
```
|
||||
|
||||
:::tip
|
||||
The installer adds `~/.local/bin` to your PATH. If you use a non-standard shell config, add `export PATH="$HOME/.local/bin:$PATH"` manually.
|
||||
:::
|
||||
|
||||
#### Python version too old
|
||||
|
||||
**Cause:** Hermes requires Python 3.11 or newer.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
python3 --version # Check current version
|
||||
|
||||
# Install a newer Python
|
||||
sudo apt install python3.12 # Ubuntu/Debian
|
||||
brew install python@3.12 # macOS
|
||||
```
|
||||
|
||||
The installer handles this automatically — if you see this error during manual installation, upgrade Python first.
|
||||
|
||||
#### `uv: command not found`
|
||||
|
||||
**Cause:** The `uv` package manager isn't installed or not in PATH.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
#### Permission denied errors during install
|
||||
|
||||
**Cause:** Insufficient permissions to write to the install directory.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Don't use sudo with the installer — it installs to ~/.local/bin
|
||||
# If you previously installed with sudo, clean up:
|
||||
sudo rm /usr/local/bin/hermes
|
||||
# Then re-run the standard installer
|
||||
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Provider & Model Issues
|
||||
|
||||
#### API key not working
|
||||
|
||||
**Cause:** Key is missing, expired, incorrectly set, or for the wrong provider.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check your configuration
|
||||
hermes config show
|
||||
|
||||
# Re-configure your provider
|
||||
hermes model
|
||||
|
||||
# Or set directly
|
||||
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx
|
||||
```
|
||||
|
||||
:::warning
|
||||
Make sure the key matches the provider. An OpenAI key won't work with OpenRouter and vice versa. Check `~/.hermes/.env` for conflicting entries.
|
||||
:::
|
||||
|
||||
#### Model not available / model not found
|
||||
|
||||
**Cause:** The model identifier is incorrect or not available on your provider.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# List available models for your provider
|
||||
hermes model
|
||||
|
||||
# Set a valid model
|
||||
hermes config set HERMES_MODEL openrouter/nous/hermes-3-llama-3.1-70b
|
||||
|
||||
# Or specify per-session
|
||||
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct
|
||||
```
|
||||
|
||||
#### Rate limiting (429 errors)
|
||||
|
||||
**Cause:** You've exceeded your provider's rate limits.
|
||||
|
||||
**Solution:** Wait a moment and retry. For sustained usage, consider:
|
||||
- Upgrading your provider plan
|
||||
- Switching to a different model or provider
|
||||
- Using `hermes chat --provider <alternative>` to route to a different backend
|
||||
|
||||
#### Context length exceeded
|
||||
|
||||
**Cause:** The conversation has grown too long for the model's context window, or Hermes detected the wrong context length for your model.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Compress the current session
|
||||
/compress
|
||||
|
||||
# Or start a fresh session
|
||||
hermes chat
|
||||
|
||||
# Use a model with a larger context window
|
||||
hermes chat --model openrouter/google/gemini-2.0-flash-001
|
||||
```
|
||||
|
||||
If this happens on the first long conversation, Hermes may have the wrong context length for your model. Check what it detected:
|
||||
|
||||
Look at the CLI startup line — it shows the detected context length (e.g., `📊 Context limit: 128000 tokens`). You can also check with `/usage` during a session.
|
||||
|
||||
To fix context detection, set it explicitly:
|
||||
|
||||
```yaml
|
||||
# In ~/.hermes/config.yaml
|
||||
model:
|
||||
default: your-model-name
|
||||
context_length: 131072 # your model's actual context window
|
||||
```
|
||||
|
||||
Or for custom endpoints, add it per-model:
|
||||
|
||||
```yaml
|
||||
custom_providers:
|
||||
- name: "My Server"
|
||||
base_url: "http://localhost:11434/v1"
|
||||
models:
|
||||
qwen3.5:27b:
|
||||
context_length: 32768
|
||||
```
|
||||
|
||||
See [Context Length Detection](../user-guide/configuration.md#context-length-detection) for how auto-detection works and all override options.
|
||||
|
||||
---
|
||||
|
||||
### Terminal Issues
|
||||
|
||||
#### Command blocked as dangerous
|
||||
|
||||
**Cause:** Hermes detected a potentially destructive command (e.g., `rm -rf`, `DROP TABLE`). This is a safety feature.
|
||||
|
||||
**Solution:** When prompted, review the command and type `y` to approve it. You can also:
|
||||
- Ask the agent to use a safer alternative
|
||||
- See the full list of dangerous patterns in the [Security docs](../user-guide/security.md)
|
||||
|
||||
:::tip
|
||||
This is working as intended — Hermes never silently runs destructive commands. The approval prompt shows you exactly what will execute.
|
||||
:::
|
||||
|
||||
#### `sudo` not working via messaging gateway
|
||||
|
||||
**Cause:** The messaging gateway runs without an interactive terminal, so `sudo` cannot prompt for a password.
|
||||
|
||||
**Solution:**
|
||||
- Avoid `sudo` in messaging — ask the agent to find alternatives
|
||||
- If you must use `sudo`, configure passwordless sudo for specific commands in `/etc/sudoers`
|
||||
- Or switch to the terminal interface for administrative tasks: `hermes chat`
|
||||
|
||||
#### Docker backend not connecting
|
||||
|
||||
**Cause:** Docker daemon isn't running or the user lacks permissions.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check Docker is running
|
||||
docker info
|
||||
|
||||
# Add your user to the docker group
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
|
||||
# Verify
|
||||
docker run hello-world
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Messaging Issues
|
||||
|
||||
#### Bot not responding to messages
|
||||
|
||||
**Cause:** The bot isn't running, isn't authorized, or your user isn't in the allowlist.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check if the gateway is running
|
||||
hermes gateway status
|
||||
|
||||
# Start the gateway
|
||||
hermes gateway start
|
||||
|
||||
# Check logs for errors
|
||||
cat ~/.hermes/logs/gateway.log | tail -50
|
||||
```
|
||||
|
||||
#### Messages not delivering
|
||||
|
||||
**Cause:** Network issues, bot token expired, or platform webhook misconfiguration.
|
||||
|
||||
**Solution:**
|
||||
- Verify your bot token is valid with `hermes gateway setup`
|
||||
- Check gateway logs: `cat ~/.hermes/logs/gateway.log | tail -50`
|
||||
- For webhook-based platforms (Slack, WhatsApp), ensure your server is publicly accessible
|
||||
|
||||
#### Allowlist confusion — who can talk to the bot?
|
||||
|
||||
**Cause:** Authorization mode determines who gets access.
|
||||
|
||||
**Solution:**
|
||||
|
||||
| Mode | How it works |
|
||||
|------|-------------|
|
||||
| **Allowlist** | Only user IDs listed in config can interact |
|
||||
| **DM pairing** | First user to message in DM claims exclusive access |
|
||||
| **Open** | Anyone can interact (not recommended for production) |
|
||||
|
||||
Configure in `~/.hermes/config.yaml` under your gateway's settings. See the [Messaging docs](../user-guide/messaging/index.md).
|
||||
|
||||
#### Gateway won't start
|
||||
|
||||
**Cause:** Missing dependencies, port conflicts, or misconfigured tokens.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Install messaging dependencies
|
||||
pip install "hermes-agent[telegram]" # or [discord], [slack], [whatsapp]
|
||||
|
||||
# Check for port conflicts
|
||||
lsof -i :8080
|
||||
|
||||
# Verify configuration
|
||||
hermes config show
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Performance Issues
|
||||
|
||||
#### Slow responses
|
||||
|
||||
**Cause:** Large model, distant API server, or heavy system prompt with many tools.
|
||||
|
||||
**Solution:**
|
||||
- Try a faster/smaller model: `hermes chat --model openrouter/meta-llama/llama-3.1-8b-instruct`
|
||||
- Reduce active toolsets: `hermes chat -t "terminal"`
|
||||
- Check your network latency to the provider
|
||||
- For local models, ensure you have enough GPU VRAM
|
||||
|
||||
#### High token usage
|
||||
|
||||
**Cause:** Long conversations, verbose system prompts, or many tool calls accumulating context.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Compress the conversation to reduce tokens
|
||||
/compress
|
||||
|
||||
# Check session token usage
|
||||
/usage
|
||||
```
|
||||
|
||||
:::tip
|
||||
Use `/compress` regularly during long sessions. It summarizes the conversation history and reduces token usage significantly while preserving context.
|
||||
:::
|
||||
|
||||
#### Session getting too long
|
||||
|
||||
**Cause:** Extended conversations accumulate messages and tool outputs, approaching context limits.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Compress current session (preserves key context)
|
||||
/compress
|
||||
|
||||
# Start a new session with a reference to the old one
|
||||
hermes chat
|
||||
|
||||
# Resume a specific session later if needed
|
||||
hermes chat --continue
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### MCP Issues
|
||||
|
||||
#### MCP server not connecting
|
||||
|
||||
**Cause:** Server binary not found, wrong command path, or missing runtime.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Ensure MCP dependencies are installed (already included in standard install)
|
||||
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"
|
||||
|
||||
# For npm-based servers, ensure Node.js is available
|
||||
node --version
|
||||
npx --version
|
||||
|
||||
# Test the server manually
|
||||
npx -y @modelcontextprotocol/server-filesystem /tmp
|
||||
```
|
||||
|
||||
Verify your `~/.hermes/config.yaml` MCP configuration:
|
||||
```yaml
|
||||
mcp_servers:
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]
|
||||
```
|
||||
|
||||
#### Tools not showing up from MCP server
|
||||
|
||||
**Cause:** Server started but tool discovery failed, tools were filtered out by config, or the server does not support the MCP capability you expected.
|
||||
|
||||
**Solution:**
|
||||
- Check gateway/agent logs for MCP connection errors
|
||||
- Ensure the server responds to the `tools/list` RPC method
|
||||
- Review any `tools.include`, `tools.exclude`, `tools.resources`, `tools.prompts`, or `enabled` settings under that server
|
||||
- Remember that resource/prompt utility tools are only registered when the session actually supports those capabilities
|
||||
- Use `/reload-mcp` after changing config
|
||||
|
||||
```bash
|
||||
# Verify MCP servers are configured
|
||||
hermes config show | grep -A 12 mcp_servers
|
||||
|
||||
# Restart Hermes or reload MCP after config changes
|
||||
hermes chat
|
||||
```
|
||||
|
||||
See also:
|
||||
- [MCP (Model Context Protocol)](/docs/user-guide/features/mcp)
|
||||
- [Use MCP with Hermes](/docs/guides/use-mcp-with-hermes)
|
||||
- [MCP Config Reference](/docs/reference/mcp-config-reference)
|
||||
|
||||
#### MCP timeout errors
|
||||
|
||||
**Cause:** The MCP server is taking too long to respond, or it crashed during execution.
|
||||
|
||||
**Solution:**
|
||||
- Increase the timeout in your MCP server config if supported
|
||||
- Check if the MCP server process is still running
|
||||
- For remote HTTP MCP servers, check network connectivity
|
||||
|
||||
:::warning
|
||||
If an MCP server crashes mid-request, Hermes will report a timeout. Check the server's own logs (not just Hermes logs) to diagnose the root cause.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Still Stuck?
|
||||
|
||||
If your issue isn't covered here:
|
||||
|
||||
1. **Search existing issues:** [GitHub Issues](https://github.com/NousResearch/hermes-agent/issues)
|
||||
2. **Ask the community:** [Nous Research Discord](https://discord.gg/nousresearch)
|
||||
3. **File a bug report:** Include your OS, Python version (`python3 --version`), Hermes version (`hermes --version`), and the full error message
|
||||
215
hermes_code/website/docs/reference/mcp-config-reference.md
Normal file
215
hermes_code/website/docs/reference/mcp-config-reference.md
Normal file
|
|
@ -0,0 +1,215 @@
|
|||
---
|
||||
sidebar_position: 8
|
||||
title: "MCP Config Reference"
|
||||
description: "Reference for Hermes Agent MCP configuration keys, filtering semantics, and utility-tool policy"
|
||||
---
|
||||
|
||||
# MCP Config Reference
|
||||
|
||||
This page is the compact reference companion to the main MCP docs.
|
||||
|
||||
For conceptual guidance, see:
|
||||
- [MCP (Model Context Protocol)](/docs/user-guide/features/mcp)
|
||||
- [Use MCP with Hermes](/docs/guides/use-mcp-with-hermes)
|
||||
|
||||
## Root config shape
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
<server_name>:
|
||||
command: "..." # stdio servers
|
||||
args: []
|
||||
env: {}
|
||||
|
||||
# OR
|
||||
url: "..." # HTTP servers
|
||||
headers: {}
|
||||
|
||||
enabled: true
|
||||
timeout: 120
|
||||
connect_timeout: 60
|
||||
tools:
|
||||
include: []
|
||||
exclude: []
|
||||
resources: true
|
||||
prompts: true
|
||||
```
|
||||
|
||||
## Server keys
|
||||
|
||||
| Key | Type | Applies to | Meaning |
|
||||
|---|---|---|---|
|
||||
| `command` | string | stdio | Executable to launch |
|
||||
| `args` | list | stdio | Arguments for the subprocess |
|
||||
| `env` | mapping | stdio | Environment passed to the subprocess |
|
||||
| `url` | string | HTTP | Remote MCP endpoint |
|
||||
| `headers` | mapping | HTTP | Headers for remote server requests |
|
||||
| `enabled` | bool | both | Skip the server entirely when false |
|
||||
| `timeout` | number | both | Tool call timeout |
|
||||
| `connect_timeout` | number | both | Initial connection timeout |
|
||||
| `tools` | mapping | both | Filtering and utility-tool policy |
|
||||
|
||||
## `tools` policy keys
|
||||
|
||||
| Key | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `include` | string or list | Whitelist server-native MCP tools |
|
||||
| `exclude` | string or list | Blacklist server-native MCP tools |
|
||||
| `resources` | bool-like | Enable/disable `list_resources` + `read_resource` |
|
||||
| `prompts` | bool-like | Enable/disable `list_prompts` + `get_prompt` |
|
||||
|
||||
## Filtering semantics
|
||||
|
||||
### `include`
|
||||
|
||||
If `include` is set, only those server-native MCP tools are registered.
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
include: [create_issue, list_issues]
|
||||
```
|
||||
|
||||
### `exclude`
|
||||
|
||||
If `exclude` is set and `include` is not, every server-native MCP tool except those names is registered.
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
exclude: [delete_customer]
|
||||
```
|
||||
|
||||
### Precedence
|
||||
|
||||
If both are set, `include` wins.
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
include: [create_issue]
|
||||
exclude: [create_issue, delete_issue]
|
||||
```
|
||||
|
||||
Result:
|
||||
- `create_issue` is still allowed
|
||||
- `delete_issue` is ignored because `include` takes precedence
|
||||
|
||||
## Utility-tool policy
|
||||
|
||||
Hermes may register these utility wrappers per MCP server:
|
||||
|
||||
Resources:
|
||||
- `list_resources`
|
||||
- `read_resource`
|
||||
|
||||
Prompts:
|
||||
- `list_prompts`
|
||||
- `get_prompt`
|
||||
|
||||
### Disable resources
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
resources: false
|
||||
```
|
||||
|
||||
### Disable prompts
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
prompts: false
|
||||
```
|
||||
|
||||
### Capability-aware registration
|
||||
|
||||
Even when `resources: true` or `prompts: true`, Hermes only registers those utility tools if the MCP session actually exposes the corresponding capability.
|
||||
|
||||
So this is normal:
|
||||
- you enable prompts
|
||||
- but no prompt utilities appear
|
||||
- because the server does not support prompts
|
||||
|
||||
## `enabled: false`
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
legacy:
|
||||
url: "https://mcp.legacy.internal"
|
||||
enabled: false
|
||||
```
|
||||
|
||||
Behavior:
|
||||
- no connection attempt
|
||||
- no discovery
|
||||
- no tool registration
|
||||
- config remains in place for later reuse
|
||||
|
||||
## Empty result behavior
|
||||
|
||||
If filtering removes all server-native tools and no utility tools are registered, Hermes does not create an empty MCP runtime toolset for that server.
|
||||
|
||||
## Example configs
|
||||
|
||||
### Safe GitHub allowlist
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
|
||||
tools:
|
||||
include: [list_issues, create_issue, update_issue, search_code]
|
||||
resources: false
|
||||
prompts: false
|
||||
```
|
||||
|
||||
### Stripe blacklist
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
stripe:
|
||||
url: "https://mcp.stripe.com"
|
||||
headers:
|
||||
Authorization: "Bearer ***"
|
||||
tools:
|
||||
exclude: [delete_customer, refund_payment]
|
||||
```
|
||||
|
||||
### Resource-only docs server
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
docs:
|
||||
url: "https://mcp.docs.example.com"
|
||||
tools:
|
||||
include: []
|
||||
resources: true
|
||||
prompts: false
|
||||
```
|
||||
|
||||
## Reloading config
|
||||
|
||||
After changing MCP config, reload servers with:
|
||||
|
||||
```text
|
||||
/reload-mcp
|
||||
```
|
||||
|
||||
## Tool naming
|
||||
|
||||
Server-native MCP tools become:
|
||||
|
||||
```text
|
||||
mcp_<server>_<tool>
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `mcp_github_create_issue`
|
||||
- `mcp_filesystem_read_file`
|
||||
- `mcp_my_api_query_data`
|
||||
|
||||
Utility tools follow the same prefixing pattern:
|
||||
- `mcp_<server>_list_resources`
|
||||
- `mcp_<server>_read_resource`
|
||||
- `mcp_<server>_list_prompts`
|
||||
- `mcp_<server>_get_prompt`
|
||||
|
|
@ -0,0 +1,74 @@
|
|||
---
|
||||
sidebar_position: 6
|
||||
title: "Official Optional Skills Catalog"
|
||||
description: "Catalog of official optional skills available from the repository"
|
||||
---
|
||||
|
||||
# Official Optional Skills Catalog
|
||||
|
||||
Official optional skills live in the repository under `optional-skills/`. Install them with `hermes skills install official/<category>/<skill>` or browse them with `hermes skills browse --source official`.
|
||||
|
||||
## autonomous-ai-agents
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `blackbox` | Delegate coding tasks to Blackbox AI CLI agent. Multi-model agent with built-in judge that runs tasks through multiple LLMs and picks the best result. Requires the blackbox CLI and a Blackbox AI API key. | `autonomous-ai-agents/blackbox` |
|
||||
|
||||
## blockchain
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `base` | Query Base (Ethereum L2) blockchain data with USD pricing — wallet balances, token info, transaction details, gas analysis, contract inspection. | `blockchain/base` |
|
||||
| `solana` | Query Solana blockchain data with USD pricing — wallet balances, token portfolios with values, transaction details, NFTs, whale detection, and live network stats. Uses Solana RPC + CoinGecko. No API key required. | `blockchain/solana` |
|
||||
|
||||
## creative
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `blender-mcp` | Control Blender directly from Hermes via socket connection to the blender-mcp addon. Create 3D objects, materials, animations, and run arbitrary Blender Python. | `creative/blender-mcp` |
|
||||
| `meme-generation` | Generate real meme images by picking a template and overlaying text with Pillow. Produces actual .png meme files. | `creative/meme-generation` |
|
||||
|
||||
## email
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `agentmail` | Give the agent its own dedicated email inbox via AgentMail. Send, receive, and manage email autonomously using agent-owned email addresses (e.g. hermes-agent@agentmail.to). | `email/agentmail` |
|
||||
|
||||
## health
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `neuroskill-bci` | Connect to a running NeuroSkill instance and incorporate the user's real-time cognitive and emotional state (focus, relaxation, mood, cognitive load, drowsiness, heart rate, HRV, sleep staging, and 40+ derived EXG scores) into responses. Requires a BCI wearable (Muse 2/S or Open… | `health/neuroskill-bci` |
|
||||
|
||||
## mcp
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `fastmcp` | Build, test, inspect, install, and deploy MCP servers with FastMCP in Python. | `mcp/fastmcp` |
|
||||
|
||||
## migration
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `openclaw-migration` | Migrate a user's OpenClaw customization footprint into Hermes Agent. Imports Hermes-compatible memories, SOUL.md, command allowlists, user skills, and selected workspace assets from ~/.openclaw, then reports exactly what could not be migrated and why. | `migration/openclaw-migration` |
|
||||
|
||||
## productivity
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `telephony` | Give Hermes phone capabilities — provision a Twilio number, send/receive SMS/MMS, make direct calls, and place AI-driven outbound calls through Bland.ai or Vapi. | `productivity/telephony` |
|
||||
|
||||
## research
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `bioinformatics` | Gateway to 400+ bioinformatics skills from bioSkills and ClawBio. Covers genomics, transcriptomics, single-cell, variant calling, pharmacogenomics, metagenomics, structural biology. | `research/bioinformatics` |
|
||||
| `qmd` | Search personal knowledge bases, notes, docs, and meeting transcripts locally using qmd — a hybrid retrieval engine with BM25, vector search, and LLM reranking. Supports CLI and MCP integration. | `research/qmd` |
|
||||
|
||||
## security
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `1password` | Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in, and reading/injecting secrets for commands. | `security/1password` |
|
||||
| `oss-forensics` | Supply chain investigation, evidence recovery, and forensic analysis for GitHub repositories. Covers deleted commit recovery, force-push detection, IOC extraction. | `security/oss-forensics` |
|
||||
| `sherlock` | OSINT username search across 400+ social networks. Hunt down social media accounts by username. | `security/sherlock` |
|
||||
279
hermes_code/website/docs/reference/skills-catalog.md
Normal file
279
hermes_code/website/docs/reference/skills-catalog.md
Normal file
|
|
@ -0,0 +1,279 @@
|
|||
---
|
||||
sidebar_position: 5
|
||||
title: "Bundled Skills Catalog"
|
||||
description: "Catalog of bundled skills that ship with Hermes Agent"
|
||||
---
|
||||
|
||||
# Bundled Skills Catalog
|
||||
|
||||
Hermes ships with a large built-in skill library copied into `~/.hermes/skills/` on install. This page catalogs the bundled skills that live in the repository under `skills/`.
|
||||
|
||||
## apple
|
||||
|
||||
Apple/macOS-specific skills — iMessage, Reminders, Notes, FindMy, and macOS automation. These skills only load on macOS systems.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `apple-notes` | Manage Apple Notes via the memo CLI on macOS (create, view, search, edit). | `apple/apple-notes` |
|
||||
| `apple-reminders` | Manage Apple Reminders via remindctl CLI (list, add, complete, delete). | `apple/apple-reminders` |
|
||||
| `findmy` | Track Apple devices and AirTags via FindMy.app on macOS using AppleScript and screen capture. | `apple/findmy` |
|
||||
| `imessage` | Send and receive iMessages/SMS via the imsg CLI on macOS. | `apple/imessage` |
|
||||
|
||||
## autonomous-ai-agents
|
||||
|
||||
Skills for spawning and orchestrating autonomous AI coding agents and multi-agent workflows — running independent agent processes, delegating tasks, and coordinating parallel workstreams.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `claude-code` | Delegate coding tasks to Claude Code (Anthropic's CLI agent). Use for building features, refactoring, PR reviews, and iterative coding. Requires the claude CLI installed. | `autonomous-ai-agents/claude-code` |
|
||||
| `codex` | Delegate coding tasks to OpenAI Codex CLI agent. Use for building features, refactoring, PR reviews, and batch issue fixing. Requires the codex CLI and a git repository. | `autonomous-ai-agents/codex` |
|
||||
| `hermes-agent-spawning` | Spawn additional Hermes Agent instances as autonomous subprocesses for independent long-running tasks. Supports non-interactive one-shot mode (-q) and interactive PTY mode for multi-turn collaboration. Different from delegate_task — this runs a full separate hermes process. | `autonomous-ai-agents/hermes-agent` |
|
||||
| `opencode` | Delegate coding tasks to OpenCode CLI agent for feature implementation, refactoring, PR review, and long-running autonomous sessions. Requires the opencode CLI installed and authenticated. | `autonomous-ai-agents/opencode` |
|
||||
|
||||
## data-science
|
||||
|
||||
Skills for data science workflows — interactive exploration, Jupyter notebooks, data analysis, and visualization.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `jupyter-live-kernel` | Use a live Jupyter kernel for stateful, iterative Python execution via hamelnb. Load this skill when the task involves exploration, iteration, or inspecting intermediate results. | `data-science/jupyter-live-kernel` |
|
||||
|
||||
## creative
|
||||
|
||||
Creative content generation — ASCII art, hand-drawn style diagrams, and visual design tools.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `ascii-art` | Generate ASCII art using pyfiglet (571 fonts), cowsay, boxes, toilet, image-to-ascii, remote APIs (asciified, ascii.co.uk), and LLM fallback. No API keys required. | `creative/ascii-art` |
|
||||
| `ascii-video` | "Production pipeline for ASCII art video — any format. Converts video/audio/images/generative input into colored ASCII character video output (MP4, GIF, image sequence). Covers: video-to-ASCII conversion, audio-reactive music visualizers, generative ASCII art animations, hybrid… | `creative/ascii-video` |
|
||||
| `excalidraw` | Create hand-drawn style diagrams using Excalidraw JSON format. Generate .excalidraw files for architecture diagrams, flowcharts, sequence diagrams, concept maps, and more. Files can be opened at excalidraw.com or uploaded for shareable links. | `creative/excalidraw` |
|
||||
|
||||
## dogfood
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `dogfood` | Systematic exploratory QA testing of web applications — find bugs, capture evidence, and generate structured reports. | `dogfood/dogfood` |
|
||||
| `hermes-agent-setup` | Help users configure Hermes Agent — CLI usage, setup wizard, model/provider selection, tools, skills, voice/STT/TTS, gateway, and troubleshooting. | `dogfood/hermes-agent-setup` |
|
||||
|
||||
## email
|
||||
|
||||
Skills for sending, receiving, searching, and managing email from the terminal.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `himalaya` | CLI to manage emails via IMAP/SMTP. Use himalaya to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language). | `email/himalaya` |
|
||||
|
||||
## gaming
|
||||
|
||||
Skills for setting up, configuring, and managing game servers, modpacks, and gaming-related infrastructure.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `minecraft-modpack-server` | Set up a modded Minecraft server from a CurseForge/Modrinth server pack zip. Covers NeoForge/Forge install, Java version, JVM tuning, firewall, LAN config, backups, and launch scripts. | `gaming/minecraft-modpack-server` |
|
||||
| `pokemon-player` | Play Pokemon games autonomously via headless emulation. Starts a game server, reads structured game state from RAM, makes strategic decisions, and sends button inputs — all from the terminal. | `gaming/pokemon-player` |
|
||||
|
||||
## github
|
||||
|
||||
GitHub workflow skills for managing repositories, pull requests, code reviews, issues, and CI/CD pipelines using the gh CLI and git via terminal.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `codebase-inspection` | Inspect and analyze codebases using pygount for LOC counting, language breakdown, and code-vs-comment ratios. Use when asked to check lines of code, repo size, language composition, or codebase stats. | `github/codebase-inspection` |
|
||||
| `github-auth` | Set up GitHub authentication for the agent using git (universally available) or the gh CLI. Covers HTTPS tokens, SSH keys, credential helpers, and gh auth — with a detection flow to pick the right method automatically. | `github/github-auth` |
|
||||
| `github-code-review` | Review code changes by analyzing git diffs, leaving inline comments on PRs, and performing thorough pre-push review. Works with gh CLI or falls back to git + GitHub REST API via curl. | `github/github-code-review` |
|
||||
| `github-issues` | Create, manage, triage, and close GitHub issues. Search existing issues, add labels, assign people, and link to PRs. Works with gh CLI or falls back to git + GitHub REST API via curl. | `github/github-issues` |
|
||||
| `github-pr-workflow` | Full pull request lifecycle — create branches, commit changes, open PRs, monitor CI status, auto-fix failures, and merge. Works with gh CLI or falls back to git + GitHub REST API via curl. | `github/github-pr-workflow` |
|
||||
| `github-repo-management` | Clone, create, fork, configure, and manage GitHub repositories. Manage remotes, secrets, releases, and workflows. Works with gh CLI or falls back to git + GitHub REST API via curl. | `github/github-repo-management` |
|
||||
|
||||
## inference-sh
|
||||
|
||||
Skills for AI app execution via inference.sh cloud platform.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `inference-sh-cli` | Run 150+ AI apps via inference.sh CLI (infsh) — image generation, video creation, LLMs, search, 3D, social automation. | `inference-sh/cli` |
|
||||
|
||||
## leisure
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `find-nearby` | Find nearby places (restaurants, cafes, bars, pharmacies, etc.) using OpenStreetMap. Works with coordinates, addresses, cities, zip codes, or Telegram location pins. No API keys needed. | `leisure/find-nearby` |
|
||||
|
||||
## mcp
|
||||
|
||||
Skills for working with MCP (Model Context Protocol) servers, tools, and integrations. Includes the built-in native MCP client (configure servers in config.yaml for automatic tool discovery) and the mcporter CLI bridge for ad-hoc server interaction.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `mcporter` | Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation. | `mcp/mcporter` |
|
||||
| `native-mcp` | Built-in MCP (Model Context Protocol) client that connects to external MCP servers, discovers their tools, and registers them as native Hermes Agent tools. Supports stdio and HTTP transports with automatic reconnection, security filtering, and zero-config tool injection. | `mcp/native-mcp` |
|
||||
|
||||
## media
|
||||
|
||||
Skills for working with media content — YouTube transcripts, GIF search, music generation, and audio visualization.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `gif-search` | Search and download GIFs from Tenor using curl. No dependencies beyond curl and jq. Useful for finding reaction GIFs, creating visual content, and sending GIFs in chat. | `media/gif-search` |
|
||||
| `heartmula` | Set up and run HeartMuLa, the open-source music generation model family (Suno-like). Generates full songs from lyrics + tags with multilingual support. | `media/heartmula` |
|
||||
| `songsee` | Generate spectrograms and audio feature visualizations (mel, chroma, MFCC, tempogram, etc.) from audio files via CLI. Useful for audio analysis, music production debugging, and visual documentation. | `media/songsee` |
|
||||
| `youtube-content` | Fetch YouTube video transcripts and transform them into structured content (chapters, summaries, threads, blog posts). | `media/youtube-content` |
|
||||
|
||||
## mlops
|
||||
|
||||
General-purpose ML operations tools — model hub management, dataset operations, and workflow orchestration.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `huggingface-hub` | Hugging Face Hub CLI (hf) — search, download, and upload models and datasets, manage repos, deploy inference endpoints. | `mlops/huggingface-hub` |
|
||||
|
||||
## mlops/cloud
|
||||
|
||||
GPU cloud providers and serverless compute platforms for ML workloads.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `lambda-labs-gpu-cloud` | Reserved and on-demand GPU cloud instances for ML training and inference. Use when you need dedicated GPU instances with simple SSH access, persistent filesystems, or high-performance multi-node clusters for large-scale training. | `mlops/cloud/lambda-labs` |
|
||||
| `modal-serverless-gpu` | Serverless GPU cloud platform for running ML workloads. Use when you need on-demand GPU access without infrastructure management, deploying ML models as APIs, or running batch jobs with automatic scaling. | `mlops/cloud/modal` |
|
||||
|
||||
## mlops/evaluation
|
||||
|
||||
Model evaluation benchmarks, experiment tracking, data curation, tokenizers, and interpretability tools.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `evaluating-llms-harness` | Evaluates LLMs across 60+ academic benchmarks (MMLU, HumanEval, GSM8K, TruthfulQA, HellaSwag). Use when benchmarking model quality, comparing models, reporting academic results, or tracking training progress. Industry standard used by EleutherAI, HuggingFace, and major labs. Sup… | `mlops/evaluation/lm-evaluation-harness` |
|
||||
| `huggingface-tokenizers` | Fast tokenizers optimized for research and production. Rust-based implementation tokenizes 1GB in <20 seconds. Supports BPE, WordPiece, and Unigram algorithms. Train custom vocabularies, track alignments, handle padding/truncation. Integrates seamlessly with transformers. Use… | `mlops/evaluation/huggingface-tokenizers` |
|
||||
| `nemo-curator` | GPU-accelerated data curation for LLM training. Supports text/image/video/audio. Features fuzzy deduplication (16× faster), quality filtering (30+ heuristics), semantic deduplication, PII redaction, NSFW detection. Scales across GPUs with RAPIDS. Use for preparing high-quality t… | `mlops/evaluation/nemo-curator` |
|
||||
| `sparse-autoencoder-training` | Provides guidance for training and analyzing Sparse Autoencoders (SAEs) using SAELens to decompose neural network activations into interpretable features. Use when discovering interpretable features, analyzing superposition, or studying monosemantic representations in language m… | `mlops/evaluation/saelens` |
|
||||
| `weights-and-biases` | Track ML experiments with automatic logging, visualize training in real-time, optimize hyperparameters with sweeps, and manage model registry with W&B - collaborative MLOps platform | `mlops/evaluation/weights-and-biases` |
|
||||
|
||||
## mlops/inference
|
||||
|
||||
Model serving, quantization (GGUF/GPTQ), structured output, inference optimization, and model surgery tools for deploying and running LLMs.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `gguf-quantization` | GGUF format and llama.cpp quantization for efficient CPU/GPU inference. Use when deploying models on consumer hardware, Apple Silicon, or when needing flexible quantization from 2-8 bit without GPU requirements. | `mlops/inference/gguf` |
|
||||
| `guidance` | Control LLM output with regex and grammars, guarantee valid JSON/XML/code generation, enforce structured formats, and build multi-step workflows with Guidance - Microsoft Research's constrained generation framework | `mlops/inference/guidance` |
|
||||
| `instructor` | Extract structured data from LLM responses with Pydantic validation, retry failed extractions automatically, parse complex JSON with type safety, and stream partial results with Instructor - battle-tested structured output library | `mlops/inference/instructor` |
|
||||
| `llama-cpp` | Runs LLM inference on CPU, Apple Silicon, and consumer GPUs without NVIDIA hardware. Use for edge deployment, M1/M2/M3 Macs, AMD/Intel GPUs, or when CUDA is unavailable. Supports GGUF quantization (1.5-8 bit) for reduced memory and 4-10× speedup vs PyTorch on CPU. | `mlops/inference/llama-cpp` |
|
||||
| `obliteratus` | Remove refusal behaviors from open-weight LLMs using OBLITERATUS — mechanistic interpretability techniques (diff-in-means, SVD, whitened SVD, LEACE, SAE decomposition, etc.) to excise guardrails while preserving reasoning. 9 CLI methods, 28 analysis modules, 116 model presets ac… | `mlops/inference/obliteratus` |
|
||||
| `outlines` | Guarantee valid JSON/XML/code structure during generation, use Pydantic models for type-safe outputs, support local models (Transformers, vLLM), and maximize inference speed with Outlines - dottxt.ai's structured generation library | `mlops/inference/outlines` |
|
||||
| `serving-llms-vllm` | Serves LLMs with high throughput using vLLM's PagedAttention and continuous batching. Use when deploying production LLM APIs, optimizing inference latency/throughput, or serving models with limited GPU memory. Supports OpenAI-compatible endpoints, quantization (GPTQ/AWQ/FP8), an… | `mlops/inference/vllm` |
|
||||
| `tensorrt-llm` | Optimizes LLM inference with NVIDIA TensorRT for maximum throughput and lowest latency. Use for production deployment on NVIDIA GPUs (A100/H100), when you need 10-100x faster inference than PyTorch, or for serving models with quantization (FP8/INT4), in-flight batching, and mult… | `mlops/inference/tensorrt-llm` |
|
||||
|
||||
## mlops/models
|
||||
|
||||
Specific model architectures and tools — computer vision (CLIP, SAM, Stable Diffusion), speech (Whisper), audio generation (AudioCraft), and multimodal models (LLaVA).
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `audiocraft-audio-generation` | PyTorch library for audio generation including text-to-music (MusicGen) and text-to-sound (AudioGen). Use when you need to generate music from text descriptions, create sound effects, or perform melody-conditioned music generation. | `mlops/models/audiocraft` |
|
||||
| `clip` | OpenAI's model connecting vision and language. Enables zero-shot image classification, image-text matching, and cross-modal retrieval. Trained on 400M image-text pairs. Use for image search, content moderation, or vision-language tasks without fine-tuning. Best for general-purpo… | `mlops/models/clip` |
|
||||
| `llava` | Large Language and Vision Assistant. Enables visual instruction tuning and image-based conversations. Combines CLIP vision encoder with Vicuna/LLaMA language models. Supports multi-turn image chat, visual question answering, and instruction following. Use for vision-language cha… | `mlops/models/llava` |
|
||||
| `segment-anything-model` | Foundation model for image segmentation with zero-shot transfer. Use when you need to segment any object in images using points, boxes, or masks as prompts, or automatically generate all object masks in an image. | `mlops/models/segment-anything` |
|
||||
| `stable-diffusion-image-generation` | State-of-the-art text-to-image generation with Stable Diffusion models via HuggingFace Diffusers. Use when generating images from text prompts, performing image-to-image translation, inpainting, or building custom diffusion pipelines. | `mlops/models/stable-diffusion` |
|
||||
| `whisper` | OpenAI's general-purpose speech recognition model. Supports 99 languages, transcription, translation to English, and language identification. Six model sizes from tiny (39M params) to large (1550M params). Use for speech-to-text, podcast transcription, or multilingual audio proc… | `mlops/models/whisper` |
|
||||
|
||||
## mlops/research
|
||||
|
||||
ML research frameworks for building and optimizing AI systems with declarative programming.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `dspy` | Build complex AI systems with declarative programming, optimize prompts automatically, create modular RAG systems and agents with DSPy - Stanford NLP's framework for systematic LM programming | `mlops/research/dspy` |
|
||||
|
||||
## mlops/training
|
||||
|
||||
Fine-tuning, RLHF/DPO/GRPO training, distributed training frameworks, and optimization tools for training LLMs and other models.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `axolotl` | Expert guidance for fine-tuning LLMs with Axolotl - YAML configs, 100+ models, LoRA/QLoRA, DPO/KTO/ORPO/GRPO, multimodal support | `mlops/training/axolotl` |
|
||||
| `distributed-llm-pretraining-torchtitan` | Provides PyTorch-native distributed LLM pretraining using torchtitan with 4D parallelism (FSDP2, TP, PP, CP). Use when pretraining Llama 3.1, DeepSeek V3, or custom models at scale from 8 to 512+ GPUs with Float8, torch.compile, and distributed checkpointing. | `mlops/training/torchtitan` |
|
||||
| `fine-tuning-with-trl` | Fine-tune LLMs using reinforcement learning with TRL - SFT for instruction tuning, DPO for preference alignment, PPO/GRPO for reward optimization, and reward model training. Use when need RLHF, align model with preferences, or train from human feedback. Works with HuggingFace Tr… | `mlops/training/trl-fine-tuning` |
|
||||
| `grpo-rl-training` | Expert guidance for GRPO/RL fine-tuning with TRL for reasoning and task-specific model training | `mlops/training/grpo-rl-training` |
|
||||
| `hermes-atropos-environments` | Build, test, and debug Hermes Agent RL environments for Atropos training. Covers the HermesAgentBaseEnv interface, reward functions, agent loop integration, evaluation with tools, wandb logging, and the three CLI modes (serve/process/evaluate). Use when creating, reviewing, or f… | `mlops/training/hermes-atropos-environments` |
|
||||
| `huggingface-accelerate` | Simplest distributed training API. 4 lines to add distributed support to any PyTorch script. Unified API for DeepSpeed/FSDP/Megatron/DDP. Automatic device placement, mixed precision (FP16/BF16/FP8). Interactive config, single launch command. HuggingFace ecosystem standard. | `mlops/training/accelerate` |
|
||||
| `optimizing-attention-flash` | Optimizes transformer attention with Flash Attention for 2-4x speedup and 10-20x memory reduction. Use when training/running transformers with long sequences (>512 tokens), encountering GPU memory issues with attention, or need faster inference. Supports PyTorch native SDPA,… | `mlops/training/flash-attention` |
|
||||
| `peft-fine-tuning` | Parameter-efficient fine-tuning for LLMs using LoRA, QLoRA, and 25+ methods. Use when fine-tuning large models (7B-70B) with limited GPU memory, when you need to train <1% of parameters with minimal accuracy loss, or for multi-adapter serving. HuggingFace's official library i… | `mlops/training/peft` |
|
||||
| `pytorch-fsdp` | Expert guidance for Fully Sharded Data Parallel training with PyTorch FSDP - parameter sharding, mixed precision, CPU offloading, FSDP2 | `mlops/training/pytorch-fsdp` |
|
||||
| `pytorch-lightning` | High-level PyTorch framework with Trainer class, automatic distributed training (DDP/FSDP/DeepSpeed), callbacks system, and minimal boilerplate. Scales from laptop to supercomputer with same code. Use when you want clean training loops with built-in best practices. | `mlops/training/pytorch-lightning` |
|
||||
| `simpo-training` | Simple Preference Optimization for LLM alignment. Reference-free alternative to DPO with better performance (+6.4 points on AlpacaEval 2.0). No reference model needed, more efficient than DPO. Use for preference alignment when want simpler, faster training than DPO/PPO. | `mlops/training/simpo` |
|
||||
| `slime-rl-training` | Provides guidance for LLM post-training with RL using slime, a Megatron+SGLang framework. Use when training GLM models, implementing custom data generation workflows, or needing tight Megatron-LM integration for RL scaling. | `mlops/training/slime` |
|
||||
| `unsloth` | Expert guidance for fast fine-tuning with Unsloth - 2-5x faster training, 50-80% less memory, LoRA/QLoRA optimization | `mlops/training/unsloth` |
|
||||
|
||||
## mlops/vector-databases
|
||||
|
||||
Vector similarity search and embedding databases for RAG, semantic search, and AI application backends.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `chroma` | Open-source embedding database for AI applications. Store embeddings and metadata, perform vector and full-text search, filter by metadata. Simple 4-function API. Scales from notebooks to production clusters. Use for semantic search, RAG applications, or document retrieval. Best… | `mlops/vector-databases/chroma` |
|
||||
| `faiss` | Facebook's library for efficient similarity search and clustering of dense vectors. Supports billions of vectors, GPU acceleration, and various index types (Flat, IVF, HNSW). Use for fast k-NN search, large-scale vector retrieval, or when you need pure similarity search without… | `mlops/vector-databases/faiss` |
|
||||
| `pinecone` | Managed vector database for production AI applications. Fully managed, auto-scaling, with hybrid search (dense + sparse), metadata filtering, and namespaces. Low latency (<100ms p95). Use for production RAG, recommendation systems, or semantic search at scale. Best for server… | `mlops/vector-databases/pinecone` |
|
||||
| `qdrant-vector-search` | High-performance vector similarity search engine for RAG and semantic search. Use when building production RAG systems requiring fast nearest neighbor search, hybrid search with filtering, or scalable vector storage with Rust-powered performance. | `mlops/vector-databases/qdrant` |
|
||||
|
||||
## note-taking
|
||||
|
||||
Note taking skills, to save information, assist with research, and collab on multi-session planning and information sharing.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `obsidian` | Read, search, and create notes in the Obsidian vault. | `note-taking/obsidian` |
|
||||
|
||||
## productivity
|
||||
|
||||
Skills for document creation, presentations, spreadsheets, and other productivity workflows.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `google-workspace` | Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration via Python. Uses OAuth2 with automatic token refresh. No external binaries needed — runs entirely with Google's Python client libraries in the Hermes venv. | `productivity/google-workspace` |
|
||||
| `linear` | Manage Linear issues, projects, and teams via the GraphQL API. Create, update, search, and organize issues. | `productivity/linear` |
|
||||
| `nano-pdf` | Edit PDFs with natural-language instructions using the nano-pdf CLI. Modify text, fix typos, update titles, and make content changes to specific pages without manual editing. | `productivity/nano-pdf` |
|
||||
| `notion` | Notion API for creating and managing pages, databases, and blocks via curl. Search, create, update, and query Notion workspaces directly from the terminal. | `productivity/notion` |
|
||||
| `ocr-and-documents` | Extract text from PDFs and scanned documents. Use web_extract for remote URLs, pymupdf for local text-based PDFs, marker-pdf for OCR/scanned docs. For DOCX use python-docx, for PPTX see the powerpoint skill. | `productivity/ocr-and-documents` |
|
||||
| `powerpoint` | "Use this skill any time a .pptx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx file (even if the extracted content will be used elsewhere, like in a… | `productivity/powerpoint` |
|
||||
|
||||
## research
|
||||
|
||||
Skills for academic research, paper discovery, literature review, domain reconnaissance, market data, content monitoring, and scientific knowledge retrieval.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `arxiv` | Search and retrieve academic papers from arXiv using their free REST API. No API key needed. Search by keyword, author, category, or ID. Combine with web_extract or the ocr-and-documents skill to read full paper content. | `research/arxiv` |
|
||||
| `blogwatcher` | Monitor blogs and RSS/Atom feeds for updates using the blogwatcher CLI. Add blogs, scan for new articles, and track what you've read. | `research/blogwatcher` |
|
||||
| `domain-intel` | Passive domain reconnaissance using Python stdlib. Subdomain discovery, SSL certificate inspection, WHOIS lookups, DNS records, domain availability checks, and bulk multi-domain analysis. No API keys required. | `research/domain-intel` |
|
||||
| `duckduckgo-search` | Free web search via DuckDuckGo — text, news, images, videos. No API key needed. Use the Python DDGS library or CLI to search, then web_extract for full content. | `research/duckduckgo-search` |
|
||||
| `parallel-cli` | Optional vendor skill for Parallel CLI — agent-native web search, extraction, deep research, enrichment, FindAll, and monitoring. | `research/parallel-cli` |
|
||||
| `ml-paper-writing` | Write publication-ready ML/AI papers for NeurIPS, ICML, ICLR, ACL, AAAI, COLM. Use when drafting papers from research repos, structuring arguments, verifying citations, or preparing camera-ready submissions. Includes LaTeX templates, reviewer guidelines, and citation verificatio… | `research/ml-paper-writing` |
|
||||
| `polymarket` | Query Polymarket prediction market data — search markets, get prices, orderbooks, and price history. Read-only via public REST APIs, no API key needed. | `research/polymarket` |
|
||||
|
||||
## smart-home
|
||||
|
||||
Skills for controlling smart home devices — lights, switches, sensors, and home automation systems.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `openhue` | Control Philips Hue lights, rooms, and scenes via the OpenHue CLI. Turn lights on/off, adjust brightness, color, color temperature, and activate scenes. | `smart-home/openhue` |
|
||||
|
||||
## social-media
|
||||
|
||||
Skills for interacting with social platforms — posting, reading, monitoring, and account operations.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `xitter` | Interact with X/Twitter via the x-cli terminal client using official X API credentials. | `social-media/xitter` |
|
||||
|
||||
## software-development
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `code-review` | Guidelines for performing thorough code reviews with security and quality focus | `software-development/code-review` |
|
||||
| `plan` | Plan mode for Hermes — inspect context, write a markdown plan into `.hermes/plans/` in the active workspace/backend working directory, and do not execute the work. | `software-development/plan` |
|
||||
| `requesting-code-review` | Use when completing tasks, implementing major features, or before merging. Validates work meets requirements through systematic review process. | `software-development/requesting-code-review` |
|
||||
| `subagent-driven-development` | Use when executing implementation plans with independent tasks. Dispatches fresh delegate_task per task with two-stage review (spec compliance then code quality). | `software-development/subagent-driven-development` |
|
||||
| `systematic-debugging` | Use when encountering any bug, test failure, or unexpected behavior. 4-phase root cause investigation — NO fixes without understanding the problem first. | `software-development/systematic-debugging` |
|
||||
| `test-driven-development` | Use when implementing any feature or bugfix, before writing implementation code. Enforces RED-GREEN-REFACTOR cycle with test-first approach. | `software-development/test-driven-development` |
|
||||
| `writing-plans` | Use when you have a spec or requirements for a multi-step task. Creates comprehensive implementation plans with bite-sized tasks, exact file paths, and complete code examples. | `software-development/writing-plans` |
|
||||
131
hermes_code/website/docs/reference/slash-commands.md
Normal file
131
hermes_code/website/docs/reference/slash-commands.md
Normal file
|
|
@ -0,0 +1,131 @@
|
|||
---
|
||||
sidebar_position: 2
|
||||
title: "Slash Commands Reference"
|
||||
description: "Complete reference for interactive CLI and messaging slash commands"
|
||||
---
|
||||
|
||||
# Slash Commands Reference
|
||||
|
||||
Hermes has two slash-command surfaces, both driven by a central `COMMAND_REGISTRY` in `hermes_cli/commands.py`:
|
||||
|
||||
- **Interactive CLI slash commands** — dispatched by `cli.py`, with autocomplete from the registry
|
||||
- **Messaging slash commands** — dispatched by `gateway/run.py`, with help text and platform menus generated from the registry
|
||||
|
||||
Installed skills are also exposed as dynamic slash commands on both surfaces. That includes bundled skills like `/plan`, which opens plan mode and saves markdown plans under `.hermes/plans/` relative to the active workspace/backend working directory.
|
||||
|
||||
## Interactive CLI slash commands
|
||||
|
||||
Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-insensitive.
|
||||
|
||||
### Session
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/new` (alias: `/reset`) | Start a new session (fresh session ID + history) |
|
||||
| `/clear` | Clear screen and start a new session |
|
||||
| `/history` | Show conversation history |
|
||||
| `/save` | Save the current conversation |
|
||||
| `/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) |
|
||||
| `/compress` | Manually compress conversation context (flush memories + summarize) |
|
||||
| `/rollback` | List or restore filesystem checkpoints (usage: /rollback [number]) |
|
||||
| `/stop` | Kill all running background processes |
|
||||
| `/queue <prompt>` (alias: `/q`) | Queue a prompt for the next turn (doesn't interrupt the current agent response) |
|
||||
| `/resume [name]` | Resume a previously-named session |
|
||||
| `/statusbar` (alias: `/sb`) | Toggle the context/model status bar on or off |
|
||||
| `/background <prompt>` | Run a prompt in a separate background session. The agent processes your prompt independently — your current session stays free for other work. Results appear as a panel when the task finishes. See [CLI Background Sessions](/docs/user-guide/cli#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. |
|
||||
|
||||
### Configuration
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/config` | Show current configuration |
|
||||
| `/model [model-name]` | Show or change the current model. Supports: `/model claude-sonnet-4`, `/model provider:model` (switch providers), `/model custom:model` (custom endpoint), `/model custom:name:model` (named custom provider), `/model custom` (auto-detect from endpoint) |
|
||||
| `/provider` | Show available providers and current provider |
|
||||
| `/prompt` | View/set custom system prompt |
|
||||
| `/personality` | Set a predefined personality |
|
||||
| `/verbose` | Cycle tool progress display: off → new → all → verbose |
|
||||
| `/reasoning` | Manage reasoning effort and display (usage: /reasoning [level\|show\|hide]) |
|
||||
| `/skin` | Show or change the display skin/theme |
|
||||
| `/voice [on\|off\|tts\|status]` | Toggle CLI voice mode and spoken playback. Recording uses `voice.record_key` (default: `Ctrl+B`). |
|
||||
|
||||
### Tools & Skills
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/tools [list\|disable\|enable] [name...]` | Manage tools: list available tools, or disable/enable specific tools for the current session. Disabling a tool removes it from the agent's toolset and triggers a session reset. |
|
||||
| `/toolsets` | List available toolsets |
|
||||
| `/browser [connect\|disconnect\|status]` | Manage local Chrome CDP connection. `connect` attaches browser tools to a running Chrome instance (default: `ws://localhost:9222`). `disconnect` detaches. `status` shows current connection. Auto-launches Chrome if no debugger is detected. |
|
||||
| `/skills` | Search, install, inspect, or manage skills from online registries |
|
||||
| `/cron` | Manage scheduled tasks (list, add/create, edit, pause, resume, run, remove) |
|
||||
| `/reload-mcp` | Reload MCP servers from config.yaml |
|
||||
| `/plugins` | List installed plugins and their status |
|
||||
|
||||
### Info
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/help` | Show this help message |
|
||||
| `/usage` | Show token usage, cost breakdown, and session duration |
|
||||
| `/insights` | Show usage insights and analytics (last 30 days) |
|
||||
| `/platforms` | Show gateway/messaging platform status |
|
||||
| `/paste` | Check clipboard for an image and attach it |
|
||||
|
||||
### Exit
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/quit` | Exit the CLI (also: /exit, /q) |
|
||||
|
||||
### Dynamic CLI slash commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/<skill-name>` | Load any installed skill as an on-demand command. Example: `/gif-search`, `/github-pr-workflow`, `/excalidraw`. |
|
||||
| `/skills ...` | Search, browse, inspect, install, audit, publish, and configure skills from registries and the official optional-skills catalog. |
|
||||
|
||||
### Quick commands
|
||||
|
||||
User-defined quick commands from `quick_commands` in `~/.hermes/config.yaml` are also available as slash commands. These are resolved at dispatch time, not shown in the built-in autocomplete/help tables.
|
||||
|
||||
## Messaging slash commands
|
||||
|
||||
The messaging gateway supports the following built-in commands inside Telegram, Discord, Slack, WhatsApp, Signal, Email, and Home Assistant chats:
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/new` | Start a new conversation. |
|
||||
| `/reset` | Reset conversation history. |
|
||||
| `/status` | Show session info. |
|
||||
| `/stop` | Kill all running background processes and interrupt the running agent. |
|
||||
| `/model [provider:model]` | Show or change the model. Supports provider switches (`/model zai:glm-5`), custom endpoints (`/model custom:model`), named custom providers (`/model custom:local:qwen`), and auto-detect (`/model custom`). |
|
||||
| `/provider` | Show provider availability and auth status. |
|
||||
| `/personality [name]` | Set a personality overlay for the session. |
|
||||
| `/retry` | Retry the last message. |
|
||||
| `/undo` | Remove the last exchange. |
|
||||
| `/sethome` | Mark the current chat as the platform home channel for deliveries. |
|
||||
| `/compress` | Manually compress conversation context. |
|
||||
| `/title [name]` | Set or show the session title. |
|
||||
| `/resume [name]` | Resume a previously named session. |
|
||||
| `/usage` | Show token usage, estimated cost breakdown (input/output), context window state, and session duration. |
|
||||
| `/insights [days]` | Show usage analytics. |
|
||||
| `/reasoning [level\|show\|hide]` | Change reasoning effort or toggle reasoning display. |
|
||||
| `/voice [on\|off\|tts\|join\|channel\|leave\|status]` | Control spoken replies in chat. `join`/`channel`/`leave` manage Discord voice-channel mode. |
|
||||
| `/rollback [number]` | List or restore filesystem checkpoints. |
|
||||
| `/background <prompt>` | 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` | Reload MCP servers from config. |
|
||||
| `/approve [session\|always]` | Approve and execute a pending dangerous command. `session` approves for this session only; `always` adds to permanent allowlist. |
|
||||
| `/deny` | Reject a pending dangerous command. |
|
||||
| `/update` | Update Hermes Agent to the latest version. |
|
||||
| `/help` | Show messaging help. |
|
||||
| `/<skill-name>` | Invoke any installed skill by name. |
|
||||
|
||||
## Notes
|
||||
|
||||
- `/skin`, `/tools`, `/toolsets`, `/browser`, `/config`, `/prompt`, `/cron`, `/skills`, `/platforms`, `/paste`, `/verbose`, `/statusbar`, and `/plugins` are **CLI-only** commands.
|
||||
- `/status`, `/sethome`, `/update`, `/approve`, and `/deny` are **messaging-only** commands.
|
||||
- `/background`, `/voice`, `/reload-mcp`, and `/rollback` work in **both** the CLI and the messaging gateway.
|
||||
- `/voice join`, `/voice channel`, and `/voice leave` are only meaningful on Discord.
|
||||
163
hermes_code/website/docs/reference/tools-reference.md
Normal file
163
hermes_code/website/docs/reference/tools-reference.md
Normal file
|
|
@ -0,0 +1,163 @@
|
|||
---
|
||||
sidebar_position: 3
|
||||
title: "Built-in Tools Reference"
|
||||
description: "Authoritative reference for Hermes built-in tools, grouped by toolset"
|
||||
---
|
||||
|
||||
# Built-in Tools Reference
|
||||
|
||||
This page documents the built-in Hermes tool registry as it exists in code. Availability can still vary by platform, credentials, and enabled toolsets.
|
||||
|
||||
## `browser` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `browser_back` | Navigate back to the previous page in browser history. Requires browser_navigate to be called first. | — |
|
||||
| `browser_click` | Click on an element identified by its ref ID from the snapshot (e.g., '@e5'). The ref IDs are shown in square brackets in the snapshot output. Requires browser_navigate and browser_snapshot to be called first. | — |
|
||||
| `browser_close` | Close the browser session and release resources. Call this when done with browser tasks to free up Browserbase session quota. | — |
|
||||
| `browser_console` | Get browser console output and JavaScript errors from the current page. Returns console.log/warn/error/info messages and uncaught JS exceptions. Use this to detect silent JavaScript errors, failed API calls, and application warnings. Requi… | — |
|
||||
| `browser_get_images` | Get a list of all images on the current page with their URLs and alt text. Useful for finding images to analyze with the vision tool. Requires browser_navigate to be called first. | — |
|
||||
| `browser_navigate` | Navigate to a URL in the browser. Initializes the session and loads the page. Must be called before other browser tools. For simple information retrieval, prefer web_search or web_extract (faster, cheaper). Use browser tools when you need… | — |
|
||||
| `browser_press` | Press a keyboard key. Useful for submitting forms (Enter), navigating (Tab), or keyboard shortcuts. Requires browser_navigate to be called first. | — |
|
||||
| `browser_scroll` | Scroll the page in a direction. Use this to reveal more content that may be below or above the current viewport. Requires browser_navigate to be called first. | — |
|
||||
| `browser_snapshot` | Get a text-based snapshot of the current page's accessibility tree. Returns interactive elements with ref IDs (like @e1, @e2) for browser_click and browser_type. full=false (default): compact view with interactive elements. full=true: comp… | — |
|
||||
| `browser_type` | Type text into an input field identified by its ref ID. Clears the field first, then types the new text. Requires browser_navigate and browser_snapshot to be called first. | — |
|
||||
| `browser_vision` | Take a screenshot of the current page and analyze it with vision AI. Use this when you need to visually understand what's on the page - especially useful for CAPTCHAs, visual verification challenges, complex layouts, or when the text snaps… | — |
|
||||
|
||||
## `clarify` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `clarify` | Ask the user a question when you need clarification, feedback, or a decision before proceeding. Supports two modes: 1. **Multiple choice** — provide up to 4 choices. The user picks one or types their own answer via a 5th 'Other' option. 2.… | — |
|
||||
|
||||
## `code_execution` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `execute_code` | Run a Python script that can call Hermes tools programmatically. Use this when you need 3+ tool calls with processing logic between them, need to filter/reduce large tool outputs before they enter your context, need conditional branching (… | — |
|
||||
|
||||
## `cronjob` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `cronjob` | Unified scheduled-task manager. Use `action="create"`, `"list"`, `"update"`, `"pause"`, `"resume"`, `"run"`, or `"remove"` to manage jobs. Supports skill-backed jobs with one or more attached skills, and `skills=[]` on update clears attached skills. Cron runs happen in fresh sessions with no current-chat context. | — |
|
||||
|
||||
## `delegation` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `delegate_task` | Spawn one or more subagents to work on tasks in isolated contexts. Each subagent gets its own conversation, terminal session, and toolset. Only the final summary is returned -- intermediate tool results never enter your context window. TWO… | — |
|
||||
|
||||
## `file` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `patch` | Targeted find-and-replace edits in files. Use this instead of sed/awk in terminal. Uses fuzzy matching (9 strategies) so minor whitespace/indentation differences won't break it. Returns a unified diff. Auto-runs syntax checks after editing… | — |
|
||||
| `read_file` | Read a text file with line numbers and pagination. Use this instead of cat/head/tail in terminal. Output format: 'LINE_NUM\|CONTENT'. Suggests similar filenames if not found. Use offset and limit for large files. NOTE: Cannot read images o… | — |
|
||||
| `search_files` | Search file contents or find files by name. Use this instead of grep/rg/find/ls in terminal. Ripgrep-backed, faster than shell equivalents. Content search (target='content'): Regex search inside files. Output modes: full matches with line… | — |
|
||||
| `write_file` | Write content to a file, completely replacing existing content. Use this instead of echo/cat heredoc in terminal. Creates parent directories automatically. OVERWRITES the entire file — use 'patch' for targeted edits. | — |
|
||||
|
||||
## `homeassistant` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `ha_call_service` | Call a Home Assistant service to control a device. Use ha_list_services to discover available services and their parameters for each domain. | — |
|
||||
| `ha_get_state` | Get the detailed state of a single Home Assistant entity, including all attributes (brightness, color, temperature setpoint, sensor readings, etc.). | — |
|
||||
| `ha_list_entities` | List Home Assistant entities. Optionally filter by domain (light, switch, climate, sensor, binary_sensor, cover, fan, etc.) or by area name (living room, kitchen, bedroom, etc.). | — |
|
||||
| `ha_list_services` | List available Home Assistant services (actions) for device control. Shows what actions can be performed on each device type and what parameters they accept. Use this to discover how to control devices found via ha_list_entities. | — |
|
||||
|
||||
## `honcho` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `honcho_conclude` | Write a conclusion about the user back to Honcho's memory. Conclusions are persistent facts that build the user's profile — preferences, corrections, clarifications, project context, or anything the user tells you that should be remembered… | — |
|
||||
| `honcho_context` | Ask Honcho a natural language question and get a synthesized answer. Uses Honcho's LLM (dialectic reasoning) — higher cost than honcho_profile or honcho_search. Can query about any peer: the user (default), the AI assistant, or any named p… | — |
|
||||
| `honcho_profile` | Retrieve the user's peer card from Honcho — a curated list of key facts about them (name, role, preferences, communication style, patterns). Fast, no LLM reasoning, minimal cost. Use this at conversation start or when you need a quick fact… | — |
|
||||
| `honcho_search` | Semantic search over Honcho's stored context about the user. Returns raw excerpts ranked by relevance to your query — no LLM synthesis. Cheaper and faster than honcho_context. Good when you want to find specific past facts and reason over… | — |
|
||||
|
||||
## `image_gen` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `image_generate` | Generate high-quality images from text prompts using FLUX 2 Pro model with automatic 2x upscaling. Creates detailed, artistic images that are automatically upscaled for hi-rez results. Returns a single upscaled image URL. Display it using… | FAL_KEY |
|
||||
|
||||
## `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… | — |
|
||||
|
||||
## `moa` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `mixture_of_agents` | Route a hard problem through multiple frontier LLMs collaboratively. Makes 5 API calls (4 reference models + 1 aggregator) with maximum reasoning effort — use sparingly for genuinely difficult problems. Best for: complex math, advanced alg… | OPENROUTER_API_KEY |
|
||||
|
||||
## `rl` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `rl_check_status` | Get status and metrics for a training run. RATE LIMITED: enforces 30-minute minimum between checks for the same run. Returns WandB metrics: step, state, reward_mean, loss, percent_correct. | TINKER_API_KEY, WANDB_API_KEY |
|
||||
| `rl_edit_config` | Update a configuration field. Use rl_get_current_config() first to see all available fields for the selected environment. Each environment has different configurable options. Infrastructure settings (tokenizer, URLs, lora_rank, learning_ra… | TINKER_API_KEY, WANDB_API_KEY |
|
||||
| `rl_get_current_config` | Get the current environment configuration. Returns only fields that can be modified: group_size, max_token_length, total_steps, steps_per_eval, use_wandb, wandb_name, max_num_workers. | TINKER_API_KEY, WANDB_API_KEY |
|
||||
| `rl_get_results` | Get final results and metrics for a completed training run. Returns final metrics and path to trained weights. | TINKER_API_KEY, WANDB_API_KEY |
|
||||
| `rl_list_environments` | List all available RL environments. Returns environment names, paths, and descriptions. TIP: Read the file_path with file tools to understand how each environment works (verifiers, data loading, rewards). | TINKER_API_KEY, WANDB_API_KEY |
|
||||
| `rl_list_runs` | List all training runs (active and completed) with their status. | TINKER_API_KEY, WANDB_API_KEY |
|
||||
| `rl_select_environment` | Select an RL environment for training. Loads the environment's default configuration. After selecting, use rl_get_current_config() to see settings and rl_edit_config() to modify them. | TINKER_API_KEY, WANDB_API_KEY |
|
||||
| `rl_start_training` | Start a new RL training run with the current environment and config. Most training parameters (lora_rank, learning_rate, etc.) are fixed. Use rl_edit_config() to set group_size, batch_size, wandb_project before starting. WARNING: Training… | TINKER_API_KEY, WANDB_API_KEY |
|
||||
| `rl_stop_training` | Stop a running training job. Use if metrics look bad, training is stagnant, or you want to try different settings. | TINKER_API_KEY, WANDB_API_KEY |
|
||||
| `rl_test_inference` | Quick inference test for any environment. Runs a few steps of inference + scoring using OpenRouter. Default: 3 steps x 16 completions = 48 rollouts per model, testing 3 models = 144 total. Tests environment loading, prompt construction, in… | TINKER_API_KEY, WANDB_API_KEY |
|
||||
|
||||
## `session_search` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `session_search` | Search your long-term memory of past conversations. This is your recall -- every past session is searchable, and this tool summarizes what happened. USE THIS PROACTIVELY when: - The user says 'we did this before', 'remember when', 'last ti… | — |
|
||||
|
||||
## `skills` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `skill_manage` | Manage skills (create, update, delete). Skills are your procedural memory — reusable approaches for recurring task types. New skills go to ~/.hermes/skills/; existing skills can be modified wherever they live. Actions: create (full SKILL.m… | — |
|
||||
| `skill_view` | Skills allow for loading information about specific tasks and workflows, as well as scripts and templates. Load a skill's full content or access its linked files (references, templates, scripts). First call returns SKILL.md content plus a… | — |
|
||||
| `skills_list` | List available skills (name + description). Use skill_view(name) to load full content. | — |
|
||||
|
||||
## `terminal` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `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. Do NOT use cat/head/tail to read files — use read_file instead. Do NOT use grep/rg/find to search — use search_files instead. Do NOT use ls to list directori… | — |
|
||||
|
||||
## `todo` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `todo` | Manage your task list for the current session. Use for complex tasks with 3+ steps or when the user provides multiple tasks. Call with no parameters to read the current list. Writing: - Provide 'todos' array to create/update items - merge=… | — |
|
||||
|
||||
## `vision` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `vision_analyze` | Analyze images using AI vision. Provides a comprehensive description and answers a specific question about the image content. | — |
|
||||
|
||||
## `web` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `web_search` | Search the web for information on any topic. Returns up to 5 relevant results with titles, URLs, and descriptions. | PARALLEL_API_KEY or FIRECRAWL_API_KEY or TAVILY_API_KEY |
|
||||
| `web_extract` | Extract content from web page URLs. Returns page content in markdown format. Also works with PDF URLs — pass the PDF link directly and it converts to markdown text. Pages under 5000 chars return full markdown; larger pages are LLM-summarized. | PARALLEL_API_KEY or FIRECRAWL_API_KEY or TAVILY_API_KEY |
|
||||
|
||||
## `tts` toolset
|
||||
|
||||
| Tool | Description | Requires environment |
|
||||
|------|-------------|----------------------|
|
||||
| `text_to_speech` | Convert text to speech audio. Returns a MEDIA: path that the platform delivers as a voice message. On Telegram it plays as a voice bubble, on Discord/WhatsApp as an audio attachment. In CLI mode, saves to ~/voice-memos/. Voice and provider… | — |
|
||||
|
||||
|
||||
52
hermes_code/website/docs/reference/toolsets-reference.md
Normal file
52
hermes_code/website/docs/reference/toolsets-reference.md
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
sidebar_position: 4
|
||||
title: "Toolsets Reference"
|
||||
description: "Reference for Hermes core, composite, platform, and dynamic toolsets"
|
||||
---
|
||||
|
||||
# Toolsets Reference
|
||||
|
||||
Toolsets are named bundles of tools that you can enable with `hermes chat --toolsets ...`, configure per platform, or resolve inside the agent runtime.
|
||||
|
||||
| Toolset | Kind | Resolves to |
|
||||
|---------|------|-------------|
|
||||
| `browser` | core | `browser_back`, `browser_click`, `browser_close`, `browser_console`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `web_search` |
|
||||
| `clarify` | core | `clarify` |
|
||||
| `code_execution` | core | `execute_code` |
|
||||
| `cronjob` | core | `cronjob` |
|
||||
| `debugging` | composite | `patch`, `process`, `read_file`, `search_files`, `terminal`, `web_extract`, `web_search`, `write_file` |
|
||||
| `delegation` | core | `delegate_task` |
|
||||
| `file` | core | `patch`, `read_file`, `search_files`, `write_file` |
|
||||
| `hermes-acp` | platform | `browser_back`, `browser_click`, `browser_close`, `browser_console`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `delegate_task`, `execute_code`, `memory`, `patch`, `process`, `read_file`, `search_files`, `session_search`, `skill_manage`, `skill_view`, `skills_list`, `terminal`, `todo`, `vision_analyze`, `web_extract`, `web_search`, `write_file` |
|
||||
| `hermes-cli` | platform | `browser_back`, `browser_click`, `browser_close`, `browser_console`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `clarify`, `cronjob`, `delegate_task`, `execute_code`, `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services`, `honcho_conclude`, `honcho_context`, `honcho_profile`, `honcho_search`, `image_generate`, `memory`, `mixture_of_agents`, `patch`, `process`, `read_file`, `search_files`, `send_message`, `session_search`, `skill_manage`, `skill_view`, `skills_list`, `terminal`, `text_to_speech`, `todo`, `vision_analyze`, `web_extract`, `web_search`, `write_file` |
|
||||
| `hermes-discord` | platform | _(same as hermes-cli)_ |
|
||||
| `hermes-email` | platform | _(same as hermes-cli)_ |
|
||||
| `hermes-gateway` | composite | Union of all messaging platform toolsets |
|
||||
| `hermes-homeassistant` | platform | _(same as hermes-cli)_ |
|
||||
| `hermes-signal` | platform | _(same as hermes-cli)_ |
|
||||
| `hermes-slack` | platform | _(same as hermes-cli)_ |
|
||||
| `hermes-sms` | platform | _(same as hermes-cli)_ |
|
||||
| `hermes-telegram` | platform | _(same as hermes-cli)_ |
|
||||
| `hermes-whatsapp` | platform | _(same as hermes-cli)_ |
|
||||
| `homeassistant` | core | `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services` |
|
||||
| `honcho` | core | `honcho_conclude`, `honcho_context`, `honcho_profile`, `honcho_search` |
|
||||
| `image_gen` | core | `image_generate` |
|
||||
| `memory` | core | `memory` |
|
||||
| `messaging` | core | `send_message` |
|
||||
| `moa` | core | `mixture_of_agents` |
|
||||
| `rl` | core | `rl_check_status`, `rl_edit_config`, `rl_get_current_config`, `rl_get_results`, `rl_list_environments`, `rl_list_runs`, `rl_select_environment`, `rl_start_training`, `rl_stop_training`, `rl_test_inference` |
|
||||
| `safe` | composite | `image_generate`, `mixture_of_agents`, `vision_analyze`, `web_extract`, `web_search` |
|
||||
| `search` | core | `web_search` |
|
||||
| `session_search` | core | `session_search` |
|
||||
| `skills` | core | `skill_manage`, `skill_view`, `skills_list` |
|
||||
| `terminal` | core | `process`, `terminal` |
|
||||
| `todo` | core | `todo` |
|
||||
| `tts` | core | `text_to_speech` |
|
||||
| `vision` | core | `vision_analyze` |
|
||||
| `web` | core | `web_extract`, `web_search` |
|
||||
|
||||
## Dynamic toolsets
|
||||
|
||||
- `mcp-<server>` — generated at runtime for each configured MCP server.
|
||||
- Custom toolsets can be created in configuration and resolved at startup.
|
||||
- Wildcards: `all` and `*` expand to every registered toolset.
|
||||
Loading…
Add table
Add a link
Reference in a new issue