Merge origin/main into bb/gui
Adopt main's web/ dashboard layout (apps/dashboard removed; web/ restored), keep bb/gui's desktop CLI/update workspace handling, and preserve main's mTLS/URL validation MCP changes. Dashboard backend is aligned to main with only the intended STT provider quarantine/ElevenLabs override reapplied.
This commit is contained in:
Brooklyn Nicholson
@@ -8,6 +8,10 @@ description: "Master the Hermes Agent terminal interface — commands, keybindin
|
||||
|
||||
Hermes Agent's CLI is a full terminal user interface (TUI) — not a web UI. It features multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output. Built for people who live in the terminal.
|
||||
|
||||
:::tip First-time setup
|
||||
One command — `hermes setup --portal` — and you're ready to `hermes chat`. See [Nous Portal](/integrations/nous-portal).
|
||||
:::
|
||||
|
||||
:::tip
|
||||
Hermes also ships a modern TUI with modal overlays, mouse selection, and non-blocking input. Launch it with `hermes --tui` — see the [TUI](tui.md) guide.
|
||||
:::
|
||||
@@ -49,7 +53,7 @@ hermes -w -q "Fix issue #123" # Single query in worktree
|
||||
|
||||
## Interface Layout
|
||||
|
||||
<img className="docs-terminal-figure" src="/img/docs/cli-layout.svg" alt="Stylized preview of the Hermes CLI layout showing the banner, conversation area, and fixed input prompt." />
|
||||
<img className="docs-terminal-figure" src="/docs/img/docs/cli-layout.svg" alt="Stylized preview of the Hermes CLI layout showing the banner, conversation area, and fixed input prompt." />
|
||||
<p className="docs-figure-caption">The Hermes CLI banner, conversation stream, and fixed input prompt rendered as a stable docs figure instead of fragile text art.</p>
|
||||
|
||||
The welcome banner shows your model, terminal backend, working directory, available tools, and installed skills at a glance.
|
||||
|
||||
@@ -8,6 +8,10 @@ description: "Configure Hermes Agent — config.yaml, providers, models, API key
|
||||
|
||||
All settings are stored in the `~/.hermes/` directory for easy access.
|
||||
|
||||
:::tip Easiest path to a working `config.yaml`
|
||||
Run `hermes setup --portal` — one OAuth gets you a model provider and all four Tool Gateway tools without hand-editing YAML. Portal subscribers also get 10% off token-billed providers. See [Nous Portal](/integrations/nous-portal).
|
||||
:::
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```text
|
||||
@@ -126,7 +130,7 @@ The agent has the same filesystem access as your user account. Use `hermes tools
|
||||
|
||||
Runs commands inside a Docker container with security hardening (all capabilities dropped, no privilege escalation, PID limits).
|
||||
|
||||
**Single persistent container, not per-command.** Hermes starts ONE long-lived container on first use and routes every terminal, file, and `execute_code` call through `docker exec` into that same container — across sessions, `/new`, `/reset`, and `delegate_task` subagents — for the lifetime of the Hermes process. Working-directory changes, installed packages, and files in `/workspace` carry over from one tool call to the next, just like a local shell. The container is stopped and removed on shutdown. See **Container lifecycle** below for details.
|
||||
**Single persistent container, shared across Hermes processes.** Hermes starts ONE long-lived container on first use and routes every terminal, file, and `execute_code` call through `docker exec` into that same container — across sessions, `/new`, `/reset`, and `delegate_task` subagents. Working-directory changes, installed packages, files in `/workspace`, and **background processes** all carry over from one tool call to the next, and from one Hermes process to the next. When you close a TUI session, run `/quit`, or start a new `hermes` invocation, the container keeps running and the next Hermes process reuses it via a labeled lookup. See **Container lifecycle** below for the exact teardown rules.
|
||||
|
||||
```yaml
|
||||
terminal:
|
||||
@@ -134,8 +138,11 @@ terminal:
|
||||
docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
|
||||
docker_mount_cwd_to_workspace: false # Mount launch dir into /workspace
|
||||
docker_run_as_host_user: false # See "Running container as host user" below
|
||||
docker_forward_env: # Env vars to forward into container
|
||||
docker_forward_env: # Host env vars to forward into container
|
||||
- "GITHUB_TOKEN"
|
||||
docker_env: # Literal env vars to inject (KEY=value)
|
||||
DEBUG: "1"
|
||||
PYTHONUNBUFFERED: "1"
|
||||
docker_volumes: # Host directory mounts
|
||||
- "/home/user/projects:/workspace/projects"
|
||||
- "/home/user/data:/data:ro" # :ro for read-only
|
||||
@@ -147,14 +154,49 @@ terminal:
|
||||
container_cpu: 1 # CPU cores (0 = unlimited)
|
||||
container_memory: 5120 # MB (0 = unlimited)
|
||||
container_disk: 51200 # MB (requires overlay2 on XFS+pquota)
|
||||
container_persistent: true # Persist /workspace and /root across sessions
|
||||
container_persistent: true # Persist /workspace and /root bind-mount dirs
|
||||
|
||||
# Cross-process container reuse (defaults match the "one long-lived
|
||||
# container shared across sessions" contract — see Container lifecycle).
|
||||
docker_persist_across_processes: true # Reuse container across Hermes restarts
|
||||
docker_orphan_reaper: true # Sweep abandoned Exited containers at startup
|
||||
|
||||
# Cross-backend lifecycle settings (apply to docker as well)
|
||||
timeout: 180 # Per-command timeout in seconds
|
||||
lifetime_seconds: 300 # Idle-reaper window; also feeds 2× orphan-reaper threshold
|
||||
```
|
||||
|
||||
**`docker_env`** vs **`docker_forward_env`**: the former injects literal `KEY=value` pairs you specify in the config (the values live in your `config.yaml` or are passed as a JSON dict via `TERMINAL_DOCKER_ENV='{"DEBUG":"1"}'`). The latter forwards values from your shell or `~/.hermes/.env`, so the actual secret never appears in the config file. Use `docker_forward_env` for tokens and `docker_env` for static knobs the container needs.
|
||||
|
||||
**`terminal.docker_extra_args`** (also overridable via `TERMINAL_DOCKER_EXTRA_ARGS='["--gpus=all"]'`) lets you pass arbitrary `docker run` flags that Hermes doesn't surface as first-class keys — `--gpus`, `--network`, `--add-host`, alternative `--security-opt` overrides, etc. Each entry must be a string; the list is appended last to the assembled `docker run` invocation so it can override Hermes' defaults if needed. Use sparingly — flags that conflict with the sandbox hardening (capability drops, `--user`, the workspace bind mount) will silently weaken isolation.
|
||||
|
||||
**Requirements:** Docker Desktop or Docker Engine installed and running. Hermes probes `$PATH` plus common macOS install locations (`/usr/local/bin/docker`, `/opt/homebrew/bin/docker`, Docker Desktop app bundle). Podman is supported out of the box: set `HERMES_DOCKER_BINARY=podman` (or the full path) to force it when both are installed.
|
||||
|
||||
**Container lifecycle:** Hermes reuses a single long-lived container (`docker run -d ... sleep 2h`) for every terminal and file-tool call, across sessions, `/new`, `/reset`, and `delegate_task` subagents, for the lifetime of the Hermes process. Commands run via `docker exec` with a login shell, so working-directory changes, installed packages, and files in `/workspace` all persist from one tool call to the next. The container is stopped and removed on Hermes shutdown (or when the idle-sweep reclaims it).
|
||||
#### Container lifecycle
|
||||
|
||||
Every Hermes-managed container is tagged with three labels so subsequent processes (and the orphan reaper) can identify it:
|
||||
|
||||
- `hermes-agent=1` — marks it as Hermes-managed
|
||||
- `hermes-task-id=<sanitized task_id>` — keys the per-task reuse probe
|
||||
- `hermes-profile=<sanitized profile name>` — scopes reuse and reaping to the active Hermes profile
|
||||
|
||||
On startup, Hermes runs `docker ps --filter label=hermes-task-id=<id> --filter label=hermes-profile=<profile>` and **attaches to the existing container** when it finds one. If the container is `exited` (e.g. after a Docker daemon restart), it's `docker start`'d and reused — filesystem state and any installed packages survive, but in-container background processes do not.
|
||||
|
||||
When a Hermes process exits — `/quit`, closing a TUI session, gateway shutdown, even SIGKILL — the cleanup path is a **no-op for the container in default mode**. The container keeps running. The next Hermes process attaches to it in milliseconds via the label probe. This is the behavior the "one long-lived container shared across sessions" contract requires: it's the only way background processes (npm watchers, dev servers, long-running pytest) survive across sessions.
|
||||
|
||||
**The container is only torn down (stopped and `docker rm -f`'d) in these cases:**
|
||||
|
||||
| Trigger | When it fires |
|
||||
|---|---|
|
||||
| `docker_persist_across_processes: false` | Explicit per-process isolation. Every `cleanup()` does `stop` + `rm -f`. Matches pre-issue-#20561 behavior. |
|
||||
| Idle reaper (`lifetime_seconds`, default 300s) | Only when the env is `persist_across_processes=false`. Persist-mode envs are no-op'd; container survives the idle sweep. |
|
||||
| Orphan reaper at next startup | Sweeps **Exited** hermes-labeled containers older than `2 × lifetime_seconds` (default 600s = 10 min), scoped to the current profile. **Running containers are never touched** — sibling-process safety. Set `docker_orphan_reaper: false` to disable. |
|
||||
| Direct user action | `docker rm -f`, `docker system prune`, Docker Desktop restart. We don't set `--restart=always`, so a host reboot leaves the container `Exited` (its CoW layer survives and gets reused on next startup, but bg processes are gone). |
|
||||
|
||||
Edge cases worth knowing:
|
||||
|
||||
- **OOM kill of in-container PID 1** transitions the container to `Exited`. Next reuse will `docker start` it; filesystem state survives, bg processes do not.
|
||||
- **Switching profiles** isolates containers from each other — a container labeled `hermes-profile=work` is invisible to a Hermes process running under `hermes-profile=research`. The orphan reaper is profile-scoped too, so cross-profile containers don't get reaped accidentally, but they also won't get cleaned up automatically until you start Hermes again under their original profile.
|
||||
|
||||
Parallel subagents spawned via `delegate_task(tasks=[...])` share this one container — concurrent `cd`, env mutations, and writes to the same path will collide. If a subagent needs an isolated sandbox, it must register a per-task image override via `register_task_env_overrides()`, which RL and benchmark environments (TerminalBench2, HermesSweEnv, etc.) do automatically for their per-task Docker images.
|
||||
|
||||
@@ -166,6 +208,29 @@ Parallel subagents spawned via `delegate_task(tasks=[...])` share this one conta
|
||||
|
||||
**Credential forwarding:** Env vars listed in `docker_forward_env` are resolved from your shell environment first, then `~/.hermes/.env`. Skills can also declare `required_environment_variables` which are merged automatically.
|
||||
|
||||
#### Environment variable overrides
|
||||
|
||||
Every key under `terminal:` has an env-var override of the form `TERMINAL_<KEY_UPPERCASE>`. The most useful ones for the Docker backend:
|
||||
|
||||
| Env var | Maps to | Notes |
|
||||
|---|---|---|
|
||||
| `TERMINAL_DOCKER_IMAGE` | `docker_image` | Base image |
|
||||
| `TERMINAL_DOCKER_FORWARD_ENV` | `docker_forward_env` | JSON array: `'["GITHUB_TOKEN","OPENAI_API_KEY"]'` |
|
||||
| `TERMINAL_DOCKER_ENV` | `docker_env` | JSON dict: `'{"DEBUG":"1"}'` |
|
||||
| `TERMINAL_DOCKER_VOLUMES` | `docker_volumes` | JSON array of `"host:container[:ro]"` strings |
|
||||
| `TERMINAL_DOCKER_EXTRA_ARGS` | `docker_extra_args` | JSON array |
|
||||
| `TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE` | `docker_mount_cwd_to_workspace` | `true` / `false` |
|
||||
| `TERMINAL_DOCKER_RUN_AS_HOST_USER` | `docker_run_as_host_user` | `true` / `false` |
|
||||
| `TERMINAL_DOCKER_PERSIST_ACROSS_PROCESSES` | `docker_persist_across_processes` | `true` / `false` — default `true` |
|
||||
| `TERMINAL_DOCKER_ORPHAN_REAPER` | `docker_orphan_reaper` | `true` / `false` — default `true` |
|
||||
| `TERMINAL_CONTAINER_CPU` | `container_cpu` | CPU cores |
|
||||
| `TERMINAL_CONTAINER_MEMORY` | `container_memory` | MB |
|
||||
| `TERMINAL_CONTAINER_DISK` | `container_disk` | MB |
|
||||
| `TERMINAL_CONTAINER_PERSISTENT` | `container_persistent` | `true` / `false` — controls the bind-mount workspace dirs, distinct from `docker_persist_across_processes` |
|
||||
| `TERMINAL_LIFETIME_SECONDS` | `lifetime_seconds` | Idle reaper window |
|
||||
| `TERMINAL_TIMEOUT` | `timeout` | Per-command timeout |
|
||||
| `HERMES_DOCKER_BINARY` | _none_ | Force a specific docker/podman binary path |
|
||||
|
||||
### SSH Backend
|
||||
|
||||
Runs commands on a remote server over SSH. Uses ControlMaster for connection reuse (5-minute idle keepalive). Persistent shell is enabled by default — state (cwd, env vars) survives across commands.
|
||||
@@ -566,6 +631,7 @@ compression:
|
||||
threshold: 0.50 # Compress at this % of context limit
|
||||
target_ratio: 0.20 # Fraction of threshold to preserve as recent tail
|
||||
protect_last_n: 20 # Min recent messages to keep uncompressed
|
||||
protect_first_n: 3 # Non-system head messages pinned across compactions (0 = pin nothing)
|
||||
hygiene_hard_message_limit: 400 # Gateway safety valve — see below
|
||||
|
||||
# The summarization model/provider is configured under auxiliary:
|
||||
@@ -582,6 +648,8 @@ Older configs with `compression.summary_model`, `compression.summary_provider`,
|
||||
|
||||
`hygiene_hard_message_limit` is a gateway-only **pre-compression safety valve**. Runaway sessions with thousands of messages can hit model context limits before the normal percent-of-context threshold fires; when message count crosses this ceiling, Hermes forces compression regardless of token usage. Default `400` — raise it for platforms where very long sessions are normal, lower it to force more aggressive compression. Editing this value on a running gateway takes effect on the next message (see below).
|
||||
|
||||
`protect_first_n` controls how many **non-system** head messages are pinned across every compaction. Default `3` — the opening user/assistant exchange survives every summarizer pass so the original goal stays visible. On long-running rolling-compaction sessions where the opening turn is no longer relevant, set `protect_first_n: 0` to pin nothing but the system prompt + summary + tail. The system prompt itself is always preserved regardless of this setting.
|
||||
|
||||
:::tip Gateway hot-reload of compression and context length
|
||||
As of recent releases, editing `model.context_length` or any `compression.*` key in `config.yaml` on a running gateway takes effect on the next message — no gateway restart, no `/reset`, no session rotation required. The cached-agent signature includes these keys, so the gateway transparently rebuilds the agent when it sees a change. API keys and tool/skill config still require the usual reload paths.
|
||||
:::
|
||||
@@ -796,7 +864,7 @@ Available providers for auxiliary tasks: `auto`, `main`, plus any provider in th
|
||||
:::
|
||||
|
||||
:::warning `"main"` is for auxiliary tasks only
|
||||
The `"main"` provider option means "use whatever provider my main agent uses" — it's only valid inside `auxiliary:`, `compression:`, and `fallback_model:` configs. It is **not** a valid value for your top-level `model.provider` setting. If you use a custom OpenAI-compatible endpoint, set `provider: custom` in your `model:` section. See [AI Providers](/integrations/providers) for all main model provider options.
|
||||
The `"main"` provider option means "use whatever provider my main agent uses" — it's only valid inside `auxiliary:`, `compression:`, and primary fallback entries (`fallback_providers:` or legacy `fallback_model:`). It is **not** a valid value for your top-level `model.provider` setting. If you use a custom OpenAI-compatible endpoint, set `provider: custom` in your `model:` section. See [AI Providers](/integrations/providers) for all main model provider options.
|
||||
:::
|
||||
|
||||
### Full auxiliary config reference
|
||||
@@ -866,7 +934,7 @@ Each auxiliary task has a configurable `timeout` (in seconds). Defaults: vision
|
||||
:::
|
||||
|
||||
:::info
|
||||
Context compression has its own `compression:` block for thresholds and an `auxiliary.compression:` block for model/provider settings — see [Context Compression](#context-compression) above. The fallback model uses a `fallback_model:` block — see [Fallback Model](/integrations/providers#fallback-model). All three follow the same provider/model/base_url pattern.
|
||||
Context compression has its own `compression:` block for thresholds and an `auxiliary.compression:` block for model/provider settings — see [Context Compression](#context-compression) above. The primary fallback chain uses a top-level `fallback_providers:` list — see [Fallback Providers](/integrations/providers#fallback-providers). All three follow the same provider/model/base_url pattern.
|
||||
:::
|
||||
|
||||
### OpenRouter routing & Pareto Code for auxiliary tasks
|
||||
@@ -909,7 +977,7 @@ AUXILIARY_VISION_MODEL=openai/gpt-4o
|
||||
|
||||
### Provider Options
|
||||
|
||||
These options apply to **auxiliary task configs** (`auxiliary:`, `compression:`, `fallback_model:`), not to your main `model.provider` setting.
|
||||
These options apply to **auxiliary task configs** (`auxiliary:`, `compression:`) and primary fallback entries (`fallback_providers:` or legacy `fallback_model:`), not to your main `model.provider` setting.
|
||||
|
||||
| Provider | Description | Requirements |
|
||||
|----------|-------------|-------------|
|
||||
@@ -1422,7 +1490,7 @@ Environment scrubbing (strips `*_API_KEY`, `*_TOKEN`, `*_SECRET`, `*_PASSWORD`,
|
||||
|
||||
## Web Search Backends
|
||||
|
||||
The `web_search`, `web_extract`, and `web_crawl` tools support five backend providers. Configure the backend in `config.yaml` or via `hermes tools`:
|
||||
The `web_search` and `web_extract` tools support five backend providers. Configure the backend in `config.yaml` or via `hermes tools`:
|
||||
|
||||
```yaml
|
||||
web:
|
||||
@@ -1433,17 +1501,17 @@ web:
|
||||
extract_backend: "firecrawl"
|
||||
```
|
||||
|
||||
| Backend | Env Var | Search | Extract | Crawl |
|
||||
|---------|---------|--------|---------|-------|
|
||||
| **Firecrawl** (default) | `FIRECRAWL_API_KEY` | ✔ | ✔ | ✔ |
|
||||
| **SearXNG** | `SEARXNG_URL` | ✔ | — | — |
|
||||
| **Parallel** | `PARALLEL_API_KEY` | ✔ | ✔ | — |
|
||||
| **Tavily** | `TAVILY_API_KEY` | ✔ | ✔ | ✔ |
|
||||
| **Exa** | `EXA_API_KEY` | ✔ | ✔ | — |
|
||||
| Backend | Env Var | Search | Extract |
|
||||
|---------|---------|--------|---------|
|
||||
| **Firecrawl** (default) | `FIRECRAWL_API_KEY` | ✔ | ✔ |
|
||||
| **SearXNG** | `SEARXNG_URL` | ✔ | — |
|
||||
| **Parallel** | `PARALLEL_API_KEY` | ✔ | ✔ |
|
||||
| **Tavily** | `TAVILY_API_KEY` | ✔ | ✔ |
|
||||
| **Exa** | `EXA_API_KEY` | ✔ | ✔ |
|
||||
|
||||
**Backend selection:** If `web.backend` is not set, the backend is auto-detected from available API keys. If only `SEARXNG_URL` is set, SearXNG is used. If only `EXA_API_KEY` is set, Exa is used. If only `TAVILY_API_KEY` is set, Tavily is used. If only `PARALLEL_API_KEY` is set, Parallel is used. Otherwise Firecrawl is the default.
|
||||
|
||||
**SearXNG** is a free, self-hosted, privacy-respecting metasearch engine that queries 70+ search engines. No API key needed — just set `SEARXNG_URL` to your instance (e.g., `http://localhost:8080`). SearXNG is search-only; `web_extract` and `web_crawl` require a separate extract provider (set `web.extract_backend`). See the [Web Search setup guide](/user-guide/features/web-search) for Docker setup instructions.
|
||||
**SearXNG** is a free, self-hosted, privacy-respecting metasearch engine that queries 70+ search engines. No API key needed — just set `SEARXNG_URL` to your instance (e.g., `http://localhost:8080`). SearXNG is search-only; `web_extract` requires a separate extract provider (set `web.extract_backend`). See the [Web Search setup guide](/user-guide/features/web-search) for Docker setup instructions.
|
||||
|
||||
**Self-hosted Firecrawl:** Set `FIRECRAWL_API_URL` to point at your own instance. When a custom URL is set, the API key becomes optional (set `USE_DB_AUTHENTICATION=*** on the server to disable auth).
|
||||
|
||||
@@ -1516,7 +1584,7 @@ Pre-execution security scanning and secret redaction:
|
||||
|
||||
```yaml
|
||||
security:
|
||||
redact_secrets: false # Redact API key patterns in tool output and logs (off by default)
|
||||
redact_secrets: true # Redact API key patterns in tool output and logs (on by default)
|
||||
tirith_enabled: true # Enable Tirith security scanning for terminal commands
|
||||
tirith_path: "tirith" # Path to tirith binary (default: "tirith" in $PATH)
|
||||
tirith_timeout: 5 # Seconds to wait for tirith scan before timing out
|
||||
@@ -1527,7 +1595,7 @@ security:
|
||||
shared_files: []
|
||||
```
|
||||
|
||||
- `redact_secrets` — when `true`, automatically detects and redacts patterns that look like API keys, tokens, and passwords in tool output before it enters the conversation context and logs. **Off by default** — enable if you commonly work with real credentials in tool output and want a safety net. Set to `true` explicitly to turn on.
|
||||
- `redact_secrets` — when `true`, automatically detects and redacts patterns that look like API keys, tokens, and passwords in tool output before it enters the conversation context and logs. **On by default**. Set to `false` explicitly only when you need raw credential-like strings for debugging or redactor development.
|
||||
- `tirith_enabled` — when `true`, terminal commands are scanned by [Tirith](https://github.com/sheeki03/tirith) before execution to detect potentially dangerous operations.
|
||||
- `tirith_path` — path to the tirith binary. Set this if tirith is installed in a non-standard location.
|
||||
- `tirith_timeout` — maximum seconds to wait for a tirith scan. Commands proceed if the scan times out.
|
||||
@@ -1658,12 +1726,14 @@ See also:
|
||||
| Context | Default |
|
||||
|---------|---------|
|
||||
| **CLI (`hermes`)** | Current directory where you run the command |
|
||||
| **Messaging gateway** | Home directory `~` (override with `MESSAGING_CWD`) |
|
||||
| **Messaging gateway** | `terminal.cwd` from `~/.hermes/config.yaml`; if unset, home directory `~` |
|
||||
| **Docker / Singularity / Modal / SSH** | User's home directory inside the container or remote machine |
|
||||
|
||||
Override the working directory:
|
||||
```bash
|
||||
# In ~/.hermes/.env or ~/.hermes/config.yaml:
|
||||
MESSAGING_CWD=/home/myuser/projects # Gateway sessions
|
||||
TERMINAL_CWD=/workspace # All terminal sessions
|
||||
```yaml
|
||||
# In ~/.hermes/config.yaml:
|
||||
terminal:
|
||||
cwd: /home/myuser/projects
|
||||
```
|
||||
|
||||
`MESSAGING_CWD` and direct `TERMINAL_CWD` entries in `~/.hermes/.env` are legacy compatibility fallbacks. New configurations should use `terminal.cwd`.
|
||||
|
||||
@@ -13,6 +13,12 @@ This page covers configuring both from the dashboard. If you prefer config files
|
||||
|
||||
:::tip Fastest path: Nous Portal
|
||||
[Nous Portal](/user-guide/features/tool-gateway) provides 300+ models under one subscription. On a fresh install, run `hermes setup --portal` to log in and set Nous as your provider in one command. Inspect what's wired up with `hermes portal status`.
|
||||
|
||||
- Portal subscribers also get **10% off token-billed providers**.
|
||||
:::
|
||||
|
||||
:::note `model:` schema — empty string vs. mapping
|
||||
On a brand-new install the bundled default config has `model: ""` (an empty string sentinel meaning "not configured yet"). The first time you run `hermes setup` or `hermes model`, that key is upgraded in-place to a mapping with `provider`, `default`, `base_url`, and `api_mode` sub-keys — the shape shown throughout this page and in [`profiles.md`](./profiles.md) / [`configuration.md`](./configuration.md). If you ever see an empty string in `config.yaml`, run `hermes model` (or click **Change** in the dashboard) and Hermes will write the dict form for you.
|
||||
:::
|
||||
|
||||
## The Models page
|
||||
@@ -54,7 +60,7 @@ Every auxiliary task defaults to `auto` — meaning Hermes uses your main model
|
||||
| Task | When to override |
|
||||
|---|---|
|
||||
| **Title Gen** | Almost always. A $0.10/M flash model writes session titles as well as Opus. Default config sets this to `google/gemini-3-flash-preview` on OpenRouter. |
|
||||
| **Vision** | When your main model is a coding model without vision (e.g. Kimi, DeepSeek). Point it at `google/gemini-2.5-flash` or `gpt-4o-mini`. |
|
||||
| **Vision** | When your main model lacks vision support. Point it at `google/gemini-2.5-flash` or `gpt-4o-mini`. |
|
||||
| **Compression** | When you're burning reasoning tokens on Opus/M2.7 just to summarize context. A fast chat model does the job at 1/50th the cost. |
|
||||
| **Approval** | For `approval_mode: smart` — a fast/cheap model (haiku, flash, gpt-5-mini) decides whether to auto-approve low-risk commands. Expensive models here are waste. |
|
||||
| **Web Extract** | When you use `web_extract` heavily. Same logic as compression — summarization doesn't need reasoning. |
|
||||
@@ -166,7 +172,9 @@ Inside any `hermes chat` session:
|
||||
|
||||
### Custom aliases
|
||||
|
||||
Define your own short names for models you reach for often, then use `/model <alias>` in the CLI or any messaging platform:
|
||||
Define your own short names for models you reach for often, then use `/model <alias>` in the CLI or any messaging platform. There are two equivalent formats — pick whichever fits your workflow.
|
||||
|
||||
**Canonical (top-level `model_aliases:`)** — full control over provider + base_url:
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
@@ -179,13 +187,15 @@ model_aliases:
|
||||
provider: x-ai
|
||||
```
|
||||
|
||||
Or from the shell (short form, `provider/model`):
|
||||
**Short string form (`model.aliases.<name>: provider/model`)** — convenient from the shell because `hermes config set` only writes scalar values, but it can't carry a custom `base_url`:
|
||||
|
||||
```bash
|
||||
hermes config set model.aliases.fav anthropic/claude-opus-4.6
|
||||
hermes config set model.aliases.grok x-ai/grok-4
|
||||
```
|
||||
|
||||
Both paths feed the same loader (`hermes_cli/model_switch.py`). Entries declared in `model_aliases:` take precedence over `model.aliases:` entries with the same name.
|
||||
|
||||
Then `/model fav` or `/model grok` in chat. User aliases shadow built-in short names (`sonnet`, `kimi`, `opus`, etc.). See [Custom model aliases](/reference/slash-commands#custom-model-aliases) for the full reference.
|
||||
|
||||
### `hermes model` subcommand
|
||||
@@ -196,7 +206,7 @@ hermes model # Interactive provider + model picker (the canonical way
|
||||
|
||||
`hermes model` walks you through picking a provider, authenticating (OAuth flows open a browser; API-key providers prompt for the key), and then choosing a specific model from that provider's curated catalog. The choice is written to `model.provider` and `model.model` in `~/.hermes/config.yaml`.
|
||||
|
||||
To list providers/models without launching the picker, use the dashboard or the REST endpoints below. To inspect what the CLI will actually use right now: `hermes config get model` and `hermes status`.
|
||||
To list providers/models without launching the picker, use the dashboard or the REST endpoints below. To inspect what the CLI will actually use right now: `hermes config show | grep '^model\.'` and `hermes status`.
|
||||
|
||||
### Direct config edit
|
||||
|
||||
|
||||
@@ -26,6 +26,10 @@ docker run -it --rm \
|
||||
|
||||
This drops you into the setup wizard, which will prompt you for your API keys and write them to `~/.hermes/.env`. You only need to do this once. It is highly recommended to set up a chat system for the gateway to work with at this point.
|
||||
|
||||
:::tip
|
||||
Inside the container, run `hermes setup --portal` once — the refresh token persists in the mounted `~/.hermes` volume. See [Nous Portal](/integrations/nous-portal).
|
||||
:::
|
||||
|
||||
## Running in gateway mode
|
||||
|
||||
Once configured, run the container in the background as a persistent gateway (Telegram, Discord, Slack, WhatsApp, etc.):
|
||||
@@ -49,6 +53,10 @@ You'll see a one-line breadcrumb in `docker logs` confirming the upgrade. To opt
|
||||
This behavior applies to the s6-based image only. Earlier (tini-based) images still run `gateway run` as the foreground main process.
|
||||
:::
|
||||
|
||||
:::note Where gateway logs go
|
||||
See the [Where the logs go](#where-the-logs-go) section below for the full routing map (per-profile gateways, dashboard, boot reconciler, container-wide `docker logs`).
|
||||
:::
|
||||
|
||||
Note: the API server is gated on `API_SERVER_ENABLED=true`. To expose it beyond `127.0.0.1` inside the container, also set `API_SERVER_HOST=0.0.0.0` and an `API_SERVER_KEY` (minimum 8 characters — generate one with `openssl rand -hex 32`). Example:
|
||||
|
||||
```sh
|
||||
@@ -68,7 +76,7 @@ Opening any port on an internet facing machine is a security risk. You should no
|
||||
|
||||
## Running the dashboard
|
||||
|
||||
The built-in web dashboard runs as an optional side-process inside the same container as the gateway. Set `HERMES_DASHBOARD=1` to run the dashboard on container loopback (`127.0.0.1`) by default:
|
||||
The built-in web dashboard runs as a supervised s6-rc service alongside the gateway in the same container. Set `HERMES_DASHBOARD=1` to bring it up:
|
||||
|
||||
```sh
|
||||
docker run -d \
|
||||
@@ -76,33 +84,38 @@ docker run -d \
|
||||
--restart unless-stopped \
|
||||
-v ~/.hermes:/opt/data \
|
||||
-p 8642:8642 \
|
||||
-p 9119:9119 \
|
||||
-e HERMES_DASHBOARD=1 \
|
||||
nousresearch/hermes-agent gateway run
|
||||
```
|
||||
|
||||
The entrypoint starts `hermes dashboard` in the background (running as the non-root `hermes` user) before `exec`-ing the main command. Dashboard output is prefixed with `[dashboard]` in `docker logs` so it's easy to separate from gateway logs.
|
||||
The dashboard is supervised by s6 — if it crashes, `s6-supervise` restarts it automatically after a short backoff. Dashboard stdout/stderr is forwarded to `docker logs <container>` (no prefix; the gateway's own output now lives in a per-profile s6-log file — see [Where the logs go](#where-the-logs-go) below — so the two streams don't clash).
|
||||
|
||||
| Environment variable | Description | Default |
|
||||
|---------------------|-------------|---------|
|
||||
| `HERMES_DASHBOARD` | Set to `1` (or `true` / `yes`) to launch the dashboard alongside the main command | *(unset — dashboard not started)* |
|
||||
| `HERMES_DASHBOARD_HOST` | Bind address for the dashboard HTTP server | `127.0.0.1` |
|
||||
| `HERMES_DASHBOARD` | Set to `1` (or `true` / `yes`) to enable the supervised dashboard service | *(unset — service is registered but stays down)* |
|
||||
| `HERMES_DASHBOARD_HOST` | Bind address for the dashboard HTTP server | `0.0.0.0` |
|
||||
| `HERMES_DASHBOARD_PORT` | Port for the dashboard HTTP server | `9119` |
|
||||
| `HERMES_DASHBOARD_TUI` | Set to `1` to expose the in-browser Chat tab (embedded `hermes --tui` via PTY/WebSocket) | *(unset)* |
|
||||
| `HERMES_DASHBOARD_INSECURE` | Set to `1` (or `true` / `yes`) to bind without the OAuth auth gate. Only use on trusted networks behind a reverse proxy without the OAuth contract — the dashboard exposes API keys and session data | *(unset — gate enforced when a `DashboardAuthProvider` is registered)* |
|
||||
|
||||
By default, the dashboard stays on loopback to avoid exposing the unauthenticated web surface over the network. To publish it intentionally, set `HERMES_DASHBOARD_HOST=0.0.0.0` and configure your own trusted network boundary/reverse proxy. In that case you must explicitly add `--insecure` behavior by passing host/flags in your command path (the entrypoint no longer auto-enables insecure mode).
|
||||
The dashboard inside the container defaults to binding `0.0.0.0` — without it, the published `-p 9119:9119` port would not be reachable from the host. To restrict the bind to container loopback (for sidecar / reverse-proxy setups), set `HERMES_DASHBOARD_HOST=127.0.0.1`.
|
||||
|
||||
:::note
|
||||
The dashboard runs as a supervised s6 service inside the container. If
|
||||
the dashboard process crashes, s6-overlay restarts it automatically
|
||||
after a short backoff — you'll see a new PID without needing to
|
||||
restart the container. Logs and crash output are visible via
|
||||
`docker logs <container>` (s6 forwards service stdout/stderr there).
|
||||
The dashboard's OAuth auth gate engages automatically when both of the following are true:
|
||||
|
||||
Running the dashboard as a separate container is not supported: its
|
||||
gateway-liveness detection requires a shared PID namespace with the
|
||||
gateway process.
|
||||
1. The bind host is non-loopback (e.g. the default `0.0.0.0` inside the container), **and**
|
||||
2. A `DashboardAuthProvider` plugin is registered.
|
||||
|
||||
The bundled `dashboard_auth/nous` provider activates whenever `HERMES_DASHBOARD_OAUTH_CLIENT_ID` is set (see [Web Dashboard → Authentication](features/web-dashboard.md)). With the gate engaged, browser callers are redirected to the configured portal's OAuth flow before they can reach any protected route.
|
||||
|
||||
If no provider is registered and the bind is non-loopback, the dashboard **fails closed at startup** with a specific error pointing at the missing env var. To opt out of the gate explicitly — for a trusted-LAN deployment behind your own reverse proxy without the OAuth contract — set `HERMES_DASHBOARD_INSECURE=1`. This is the **only** path that disables the gate; the bind host alone never implies `--insecure` (it used to, but that predated the OAuth gate and silently disabled it on every container-deployed dashboard).
|
||||
|
||||
:::warning `HERMES_DASHBOARD_INSECURE=1` exposes API keys
|
||||
Opting out of the OAuth gate serves the dashboard's API surface (including model keys and session data) to anyone who can reach the published port. Only enable it when you have your own auth layer in front, or on a trusted LAN you fully control.
|
||||
:::
|
||||
|
||||
Running the dashboard as a separate container is not supported: its gateway-liveness detection requires a shared PID namespace with the gateway process.
|
||||
|
||||
## Running interactively (CLI chat)
|
||||
|
||||
To open an interactive chat session against a running data directory:
|
||||
@@ -145,37 +158,60 @@ Never run two Hermes **gateway** containers against the same data directory simu
|
||||
|
||||
## Multi-profile support
|
||||
|
||||
Hermes supports [multiple profiles](../reference/profile-commands.md) — separate `~/.hermes/` directories that let you run independent agents (different SOUL, skills, memory, sessions, credentials) from a single installation. **When running under Docker, using Hermes' built-in multi-profile feature is not recommended.**
|
||||
Hermes supports [multiple profiles](../reference/profile-commands.md) — separate `~/.hermes/` subdirectories that let you run independent agents (different SOUL, skills, memory, sessions, credentials) from a single installation. **Inside the official Docker image, the s6 supervision tree treats each profile as a first-class supervised service**, so the recommended deployment is **one container hosting all profiles**.
|
||||
|
||||
Instead, the recommended pattern is **one container per profile**, with each container bind-mounting its own host directory as `/opt/data`:
|
||||
Each profile created with `hermes profile create <name>` gets:
|
||||
|
||||
- A dedicated s6 service slot at `/run/service/gateway-<name>/`, registered dynamically by the runtime — no container rebuild required.
|
||||
- Auto-restart on crash, backoff-managed by `s6-supervise`.
|
||||
- Per-profile rotated logs at `${HERMES_HOME}/logs/gateways/<name>/current` (10 archives × 1 MB each).
|
||||
- State persistence across container restarts: the boot-time reconciler reads `gateway_state.json` from each profile directory and brings the slot back up only for profiles whose last recorded state was `running`. Stopped profiles stay stopped.
|
||||
|
||||
The lifecycle commands you'd run on the host work the same way from inside the container:
|
||||
|
||||
```sh
|
||||
# Work profile
|
||||
docker run -d \
|
||||
--name hermes-work \
|
||||
--restart unless-stopped \
|
||||
-v ~/.hermes-work:/opt/data \
|
||||
-p 8642:8642 \
|
||||
nousresearch/hermes-agent gateway run
|
||||
# Create a profile — registers the gateway-<name> s6 slot.
|
||||
docker exec hermes hermes profile create coder
|
||||
|
||||
# Personal profile
|
||||
docker run -d \
|
||||
--name hermes-personal \
|
||||
--restart unless-stopped \
|
||||
-v ~/.hermes-personal:/opt/data \
|
||||
-p 8643:8642 \
|
||||
nousresearch/hermes-agent gateway run
|
||||
# Start / stop / restart — dispatches s6-svc; the gateway lifecycle survives docker restart.
|
||||
docker exec hermes hermes -p coder gateway start
|
||||
docker exec hermes hermes -p coder gateway stop
|
||||
docker exec hermes hermes -p coder gateway restart
|
||||
|
||||
# Status — reports `Manager: s6 (container supervisor)` inside the container.
|
||||
docker exec hermes hermes -p coder gateway status
|
||||
|
||||
# Remove a profile — tears down the s6 slot too.
|
||||
docker exec hermes hermes profile delete coder
|
||||
```
|
||||
|
||||
Why separate containers over profiles in Docker:
|
||||
Under the hood, `hermes gateway start/stop/restart` inside the container is intercepted and routed to `s6-svc` against the right service directory; you don't need to learn the s6 commands directly. For raw supervisor state, use `/command/s6-svstat /run/service/gateway-<name>` (note `/command/` is on PATH only for processes spawned by the supervision tree — when calling from `docker exec`, pass the absolute path).
|
||||
|
||||
- **Isolation** — each container has its own filesystem, process table, and resource limits. A crash, dependency change, or runaway session in one profile can't affect another.
|
||||
- **Independent lifecycle** — upgrade, restart, pause, or roll back each agent separately (`docker restart hermes-work` leaves `hermes-personal` untouched).
|
||||
- **Clean port and network separation** — each gateway binds its own host port; there's no risk of cross-talk between chat platforms or API servers.
|
||||
- **Simpler mental model** — the container *is* the profile. Backups, migrations, and permissions all follow the bind-mounted directory, with no extra `--profile` flags to remember.
|
||||
- **Avoids concurrent-write risk** — the warning above about never running two gateways against the same data directory still applies to profiles within a single container.
|
||||
### Why one container with many profiles, not many containers
|
||||
|
||||
In Docker Compose, this just means declaring one service per profile with distinct `container_name`, `volumes`, and `ports`:
|
||||
Before the s6 migration, "one container per profile" was the recommended pattern because there was no in-container supervisor to manage multiple gateways. With s6 as PID 1, that's no longer necessary, and the single-container layout is simpler in almost every dimension:
|
||||
|
||||
| | One container, many profiles | One container per profile |
|
||||
|---|---|---|
|
||||
| Disk overhead | One image, one bundled venv, one Playwright cache | N images / N caches |
|
||||
| Memory overhead | Shared Python interpreter cache, shared node_modules | Duplicated per container |
|
||||
| Profile creation | `docker exec ... hermes profile create <name>` (seconds) | New `docker run` invocation + port allocation + bind-mount config |
|
||||
| Per-profile crash recovery | `s6-supervise` auto-restart | Docker's `--restart unless-stopped` (slower, kills sibling work) |
|
||||
| Logs | Per-profile rotated file via `s6-log`, plus container-boot audit log | `docker logs <name>` per container — no built-in rotation |
|
||||
| Backup | One `~/.hermes` directory | N directories to coordinate |
|
||||
|
||||
The default profile (`default`) is always registered on first boot, so a fresh container ships with one supervised gateway out of the box. Additional profiles are pure runtime adds.
|
||||
|
||||
### When you DO want a separate container
|
||||
|
||||
Profile-in-container is the default. Run a separate container per profile only when you have a specific reason:
|
||||
|
||||
- **Resource isolation per workload** — e.g. a runaway browser-tool session in profile A shouldn't be able to OOM profile B. Containers give you `--memory` / `--cpus` per profile.
|
||||
- **Independent image pinning** — different upstream image tags per workload.
|
||||
- **Network segmentation** — distinct Docker networks per profile (e.g. one customer-facing, one internal).
|
||||
- **Compliance / blast radius** — distinct credentials never share an OS-level process tree.
|
||||
|
||||
In those cases, declare one service per profile with distinct `container_name`, `volumes`, and `ports`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
@@ -200,6 +236,24 @@ services:
|
||||
- ~/.hermes-personal:/opt/data
|
||||
```
|
||||
|
||||
The warning from [Persistent volumes](#persistent-volumes) still applies: never point two containers at the same `~/.hermes` directory simultaneously. The s6 supervisor inside each container manages its own profile set; cross-container sharing of a data volume corrupts session files and memory stores.
|
||||
|
||||
## Where the logs go
|
||||
|
||||
The s6 container has four distinct log surfaces, and "why isn't my gateway showing anything in `docker logs`" is a common surprise. Cheatsheet:
|
||||
|
||||
| Source | Where it lands | How to read it |
|
||||
|---|---|---|
|
||||
| **Per-profile gateway** (`hermes gateway run` and per-profile gateways under s6) | Tee'd to two places: `docker logs <container>` (real time, no extra prefix) **and** `${HERMES_HOME}/logs/gateways/<profile>/current` (rotated, ISO-8601 timestamped, 10 archives × 1 MB each) | `docker logs -f hermes` or `tail -F ~/.hermes/logs/gateways/default/current` on the host |
|
||||
| **Dashboard** (when `HERMES_DASHBOARD=1`) | `docker logs <container>` (no prefix) | `docker logs -f hermes` — interleaved with gateway lines |
|
||||
| **Boot reconciler** (records which profile gateways were restored on each container start) | `${HERMES_HOME}/logs/container-boot.log` (append-only audit log) | `tail -F ~/.hermes/logs/container-boot.log` |
|
||||
| **Generic Hermes logs** (`agent.log`, `errors.log`) | `${HERMES_HOME}/logs/` (profile-aware) | `docker exec hermes hermes logs --follow [--level WARNING] [--session <id>]` |
|
||||
|
||||
Two practical consequences worth knowing:
|
||||
|
||||
- The file copy at `logs/gateways/<profile>/current` is what survives container restarts. `docker logs` only retains output from the current container's lifetime (and is wiped on `docker rm`); the rotated files persist on the bind-mounted volume.
|
||||
- The boot reconciler's audit line shape is `<iso-timestamp> profile=<name> prior_state=<state> action=<registered|started>`, so a quick `grep profile=coder ~/.hermes/logs/container-boot.log` reveals when a given profile was last restored and whether s6 auto-started it.
|
||||
|
||||
## Environment variable forwarding
|
||||
|
||||
API keys are read from `/opt/data/.env` inside the container. You can also pass environment variables directly:
|
||||
@@ -215,7 +269,7 @@ docker run -it --rm \
|
||||
Direct `-e` flags override values from `.env`. This is useful for CI/CD or secrets-manager integrations where you don't want keys on disk.
|
||||
|
||||
:::note Looking for Docker as the **terminal backend**?
|
||||
This page covers running Hermes itself inside Docker. If you want Hermes to execute the agent's `terminal` / `execute_code` calls inside a Docker sandbox container (one persistent container per Hermes process), that's a separate config block — `terminal.backend: docker` plus `terminal.docker_image`, `terminal.docker_volumes`, `terminal.docker_forward_env`, `terminal.docker_run_as_host_user`, and `terminal.docker_extra_args`. See [Configuration → Docker Backend](configuration.md#docker-backend) for the full set.
|
||||
This page covers running Hermes itself inside Docker. If you want Hermes to execute the agent's `terminal` / `execute_code` calls inside a Docker sandbox container (one long-lived container shared across Hermes processes — see issue #20561), that's a separate config block — `terminal.backend: docker` plus `terminal.docker_image`, `terminal.docker_volumes`, `terminal.docker_forward_env`, `terminal.docker_env`, `terminal.docker_run_as_host_user`, `terminal.docker_extra_args`, `terminal.docker_persist_across_processes`, and `terminal.docker_orphan_reaper`. See [Configuration → Docker Backend](configuration.md#docker-backend) for the full set including container-lifecycle rules.
|
||||
:::
|
||||
|
||||
## Docker Compose example
|
||||
@@ -247,7 +301,7 @@ services:
|
||||
cpus: "2.0"
|
||||
```
|
||||
|
||||
Start with `docker compose up -d` and view logs with `docker compose logs -f`. Dashboard output is prefixed with `[dashboard]` so it's easy to filter from gateway logs.
|
||||
Start with `docker compose up -d` and view logs with `docker compose logs -f`. The supervised gateway's stdout is also tee'd to `${HERMES_HOME}/logs/gateways/<profile>/current` on the volume — see [Where the logs go](#where-the-logs-go) for the full routing map.
|
||||
|
||||
## Optional: Linux desktop audio bridge
|
||||
|
||||
@@ -381,24 +435,28 @@ The container ENTRYPOINT is now `/init` (s6-overlay), not `/usr/bin/tini`. All f
|
||||
Do not override the image entrypoint unless you keep `/init` (or, equivalently, the legacy `docker/entrypoint.sh` shim that forwards to the stage2 hook) in the command chain. s6-overlay's `/init` runs as root so it can chown the volume on first boot, then drops to the `hermes` user via `s6-setuidgid` for every supervised service AND for the main program. Starting `hermes gateway run` as root inside the official image is refused by default because it can leave root-owned files in `/opt/data` and break later dashboard or gateway starts. Set `HERMES_ALLOW_ROOT_GATEWAY=1` only when you intentionally accept that risk.
|
||||
:::
|
||||
|
||||
### Per-profile gateway supervision
|
||||
### `docker exec` automatically drops to the `hermes` user
|
||||
|
||||
Inside the container, each profile created with `hermes profile create <name>` automatically gets an s6-supervised gateway service registered at `/run/service/gateway-<name>/`. The lifecycle commands you'd run on the host work the same way:
|
||||
`docker exec hermes <cmd>` defaults to running as root inside the container, but the image ships a thin shim at `/opt/hermes/bin/hermes` (earliest on PATH) that detects root callers and transparently re-execs through `s6-setuidgid hermes`. So `docker exec hermes login`, `docker exec hermes profile create …`, `docker exec hermes setup`, etc. all write files owned by UID 10000 — i.e. readable by the supervised gateway — with no extra `--user` flag needed. Non-root callers (the supervised processes themselves, `docker exec --user hermes`, kanban subagents inside the container) hit a short-circuit that exec's the venv binary directly, so there's no overhead on the hot paths.
|
||||
|
||||
If you specifically need a `docker exec` that retains root semantics (diagnostic sessions, inspecting root-only state, files outside `/opt/data` that root happens to own), opt out per invocation:
|
||||
|
||||
```sh
|
||||
hermes profile create coder # registers gateway-coder s6 slot
|
||||
hermes -p coder gateway start # s6-svc -u → supervised gateway
|
||||
hermes -p coder gateway stop # s6-svc -d → service down
|
||||
hermes -p coder gateway restart # s6-svc -t → SIGTERM the supervisor
|
||||
hermes profile delete coder # tears down the s6 slot
|
||||
docker exec -e HERMES_DOCKER_EXEC_AS_ROOT=1 hermes <cmd>
|
||||
```
|
||||
|
||||
The shim accepts `1` / `true` / `yes` (case-insensitive). Anything else — including typos like `=0` — falls through to the drop, so silent opt-outs aren't possible. If `s6-setuidgid` isn't available (custom builds that stripped s6-overlay), the shim refuses to run as root and exits 126 instead, surfacing the broken privilege model loudly rather than regressing to the historical footgun where `docker exec hermes login` would write `auth.json` as `root:root` and break the supervised gateway's auth on every chat platform message.
|
||||
|
||||
### Per-profile gateway supervision
|
||||
|
||||
Each profile created with `hermes profile create <name>` automatically gets an s6-supervised gateway service registered at `/run/service/gateway-<name>/`, with state-persistent auto-restart across container restarts. See [Multi-profile support](#multi-profile-support) above for the user-facing workflow and the lifecycle commands.
|
||||
|
||||
**Supervision benefits over the pre-s6 image:**
|
||||
|
||||
- Gateway crashes are auto-restarted by `s6-supervise` after a ~1s backoff.
|
||||
- Dashboard crashes are auto-restarted (set `HERMES_DASHBOARD=1` to start it).
|
||||
- Dashboard, when enabled with `HERMES_DASHBOARD=1`, is supervised on the same supervision tree and gets the same auto-restart treatment.
|
||||
- `docker restart` preserves running gateways: the cont-init reconciler reads `$HERMES_HOME/profiles/<name>/gateway_state.json` and brings the slot back up if the last recorded state was `running`. Stopped gateways stay stopped.
|
||||
- Per-profile gateway logs persist under `$HERMES_HOME/logs/gateways/<profile>/current` (rotated by `s6-log`), and the reconciler's actions are appended to `$HERMES_HOME/logs/container-boot.log` per boot.
|
||||
- Per-profile gateway logs persist under `$HERMES_HOME/logs/gateways/<profile>/current` (rotated by `s6-log`), and the reconciler's actions are appended to `$HERMES_HOME/logs/container-boot.log` per boot. See [Where the logs go](#where-the-logs-go) for the full routing map.
|
||||
|
||||
`hermes status` inside the container reports `Manager: s6 (container supervisor)`. Use `/command/s6-svstat /run/service/gateway-<name>` for the raw supervisor view (note `/command/` is on PATH for supervision-tree processes only; pass the absolute path when calling from `docker exec`).
|
||||
|
||||
@@ -652,12 +710,24 @@ Check logs: `docker logs hermes`. Common causes:
|
||||
|
||||
### "Permission denied" errors
|
||||
|
||||
The container's stage2 hook drops privileges to the non-root `hermes` user (UID 10000) via `s6-setuidgid` inside each supervised service. If your host `~/.hermes/` is owned by a different UID, set `HERMES_UID`/`HERMES_GID` to match your host user, or ensure the data directory is writable:
|
||||
The container's stage2 hook drops privileges to the non-root `hermes` user (UID 10000) via `s6-setuidgid` inside each supervised service. If your host `~/.hermes/` is owned by a different UID, set `HERMES_UID`/`HERMES_GID` — or their `PUID`/`PGID` aliases, for parity with LinuxServer.io and NAS images — to match your host user, or ensure the data directory is writable:
|
||||
|
||||
```sh
|
||||
chmod -R 755 ~/.hermes
|
||||
```
|
||||
|
||||
On a NAS (UGOS, Synology, unRAID) the data directory is typically a **bind mount** owned by a host UID the container cannot `chown`. Set `PUID`/`PGID` (or `HERMES_UID`/`HERMES_GID`) to that host user so the runtime runs as the owner of the mount rather than UID 10000:
|
||||
|
||||
```sh
|
||||
docker run -d \
|
||||
--name hermes \
|
||||
-e PUID=1000 -e PGID=10 \
|
||||
-v /volume1/docker/hermes:/opt/data \
|
||||
nousresearch/hermes-agent gateway run
|
||||
```
|
||||
|
||||
`docker exec hermes <cmd>` automatically drops to UID 10000 too — see [`docker exec` automatically drops to the `hermes` user](#docker-exec-automatically-drops-to-the-hermes-user) for details and the per-invocation opt-out.
|
||||
|
||||
### Browser tools not working
|
||||
|
||||
Playwright needs shared memory. Add `--shm-size=1g` to your Docker run command:
|
||||
|
||||
@@ -308,6 +308,66 @@ Resume a previously paused job.
|
||||
|
||||
Trigger the job to run immediately, out of schedule.
|
||||
|
||||
## Sessions API (session control over REST)
|
||||
|
||||
External UIs can manage Hermes sessions over REST without standing up the dashboard. All endpoints are gated by `API_SERVER_KEY` and live under `/api/sessions/*`.
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| `GET` | `/api/sessions` | List sessions (paginated — `limit`, `offset`, `source`, `include_children`) |
|
||||
| `POST` | `/api/sessions` | Create an empty session |
|
||||
| `GET` | `/api/sessions/{id}` | Read session metadata |
|
||||
| `PATCH` | `/api/sessions/{id}` | Update title or `end_reason` |
|
||||
| `DELETE` | `/api/sessions/{id}` | Delete a session |
|
||||
| `GET` | `/api/sessions/{id}/messages` | Message history for a session |
|
||||
| `POST` | `/api/sessions/{id}/fork` | Branch the session via `SessionDB` lineage (matches CLI `/branch` semantics) |
|
||||
| `POST` | `/api/sessions/{id}/chat` | Run one synchronous agent turn |
|
||||
| `POST` | `/api/sessions/{id}/chat/stream` | SSE wrapper over a single turn — emits `assistant.delta`, `tool.started`, `tool.completed`, `run.completed` events |
|
||||
|
||||
`/v1/capabilities` advertises the full surface via `session_*` feature flags and `endpoints.session_*` entries so external UIs can detect support and fall back safely. Inline images are supported in `chat` and `chat/stream` payloads (multimodal-aware path).
|
||||
|
||||
```bash
|
||||
# fork a session and run one turn
|
||||
curl -X POST http://localhost:8642/api/sessions/$ID/fork \
|
||||
-H "Authorization: Bearer $API_SERVER_KEY" \
|
||||
-d '{"title": "explore alt path"}'
|
||||
|
||||
# stream a turn over SSE
|
||||
curl -N -X POST http://localhost:8642/api/sessions/$ID/chat/stream \
|
||||
-H "Authorization: Bearer $API_SERVER_KEY" \
|
||||
-d '{"input": "what files changed in the last hour?"}'
|
||||
```
|
||||
|
||||
## Skills and toolsets discovery
|
||||
|
||||
`GET /v1/skills` and `GET /v1/toolsets` let external clients enumerate the agent's capabilities deterministically over REST instead of asking the model. Both are read-only and gated by `API_SERVER_KEY`.
|
||||
|
||||
```bash
|
||||
curl http://localhost:8642/v1/skills \
|
||||
-H "Authorization: Bearer $API_SERVER_KEY"
|
||||
# → [{"name": "github-pr-workflow", "description": "...", "category": "..."}, ...]
|
||||
|
||||
curl http://localhost:8642/v1/toolsets \
|
||||
-H "Authorization: Bearer $API_SERVER_KEY"
|
||||
# → [{"name": "core", "label": "...", "description": "...", "enabled": true,
|
||||
# "configured": true, "tools": ["read_file", "write_file", ...]}, ...]
|
||||
```
|
||||
|
||||
`/v1/skills` returns the same metadata the skills hub uses internally. `/v1/toolsets` returns toolsets resolved for the `api_server` platform with the concrete `tools` list each one expands to. Both are advertised under `endpoints.*` in `/v1/capabilities`.
|
||||
|
||||
## Long-term memory scoping (`X-Hermes-Session-Key`)
|
||||
|
||||
Multi-user frontends like Open WebUI need a stable per-channel identifier for long-term memory (Honcho, etc.) that is **independent** of the transcript-scoped `X-Hermes-Session-Id` (which rotates on `/new`). Pass `X-Hermes-Session-Key` on `/v1/chat/completions`, `/v1/responses`, or `/v1/runs` and Hermes threads it through to `AIAgent(gateway_session_key=...)`, where the Honcho memory provider uses it to derive a stable scope.
|
||||
|
||||
```http
|
||||
POST /v1/chat/completions HTTP/1.1
|
||||
Authorization: Bearer ***
|
||||
X-Hermes-Session-Id: transcript-alpha
|
||||
X-Hermes-Session-Key: agent:main:webui:dm:user-42
|
||||
```
|
||||
|
||||
Rules: max 256 chars, control characters (`\r`, `\n`, `\x00`) are rejected, and the value is echoed back on responses (JSON + SSE). `/v1/capabilities` advertises support via `"session_key_header": "X-Hermes-Session-Key"`. Without the key, Honcho's `per-session` strategy produces a different scope per `session_id` — exactly the behavior Hermes had before.
|
||||
|
||||
## System Prompt Handling
|
||||
|
||||
When a frontend sends a `system` message (Chat Completions) or `instructions` field (Responses API), hermes-agent **layers it on top** of its core system prompt. Your agent keeps all its tools, memory, and skills — the frontend's system prompt adds extra instructions.
|
||||
@@ -327,9 +387,7 @@ Authorization: Bearer ***
|
||||
Configure the key via `API_SERVER_KEY` env var. If you need a browser to call Hermes directly, also set `API_SERVER_CORS_ORIGINS` to an explicit allowlist.
|
||||
|
||||
:::warning Security
|
||||
The API server gives full access to hermes-agent's toolset, **including terminal commands**. When binding to a non-loopback address like `0.0.0.0`, `API_SERVER_KEY` is **required**. Also keep `API_SERVER_CORS_ORIGINS` narrow to control browser access.
|
||||
|
||||
The default bind address (`127.0.0.1`) is for local-only use. Browser access is disabled by default; enable it only for explicit trusted origins.
|
||||
The API server gives full access to hermes-agent's toolset, **including terminal commands**. `API_SERVER_KEY` is **required for every deployment**, including the default loopback bind on `127.0.0.1`. Keep `API_SERVER_CORS_ORIGINS` narrow to control browser access when you explicitly allow browser callers.
|
||||
:::
|
||||
|
||||
## Configuration
|
||||
@@ -341,7 +399,7 @@ The default bind address (`127.0.0.1`) is for local-only use. Browser access is
|
||||
| `API_SERVER_ENABLED` | `false` | Enable the API server |
|
||||
| `API_SERVER_PORT` | `8642` | HTTP server port |
|
||||
| `API_SERVER_HOST` | `127.0.0.1` | Bind address (localhost only by default) |
|
||||
| `API_SERVER_KEY` | _(none)_ | Bearer token for auth |
|
||||
| `API_SERVER_KEY` | _(required)_ | Bearer token for auth |
|
||||
| `API_SERVER_CORS_ORIGINS` | _(none)_ | Comma-separated allowed browser origins |
|
||||
| `API_SERVER_MODEL_NAME` | _(profile name)_ | Model name on `/v1/models`. Defaults to profile name, or `hermes-agent` for default profile. |
|
||||
|
||||
|
||||
@@ -185,6 +185,25 @@ Then set in `~/.hermes/.env`:
|
||||
CAMOFOX_URL=http://localhost:9377
|
||||
```
|
||||
|
||||
If Camofox is running in Docker and you want it to open web apps served from the host machine, enable loopback rewriting. `CAMOFOX_URL` should still point at the host-published control API, but page URLs such as `http://127.0.0.1:3000` must be opened from inside the container as `http://host.docker.internal:3000`:
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
browser:
|
||||
camofox:
|
||||
rewrite_loopback_urls: true
|
||||
loopback_host_alias: host.docker.internal # default; use a LAN IP if needed
|
||||
```
|
||||
|
||||
Equivalent env vars:
|
||||
|
||||
```bash
|
||||
CAMOFOX_REWRITE_LOOPBACK_URLS=true
|
||||
CAMOFOX_LOOPBACK_HOST_ALIAS=host.docker.internal
|
||||
```
|
||||
|
||||
The rewrite only applies to page navigation URLs with loopback hosts (`localhost`, `127.0.0.1`, `::1`). It does not change `CAMOFOX_URL`. Leave it disabled for non-Docker Camofox installs, where the browser already runs on the host and loopback URLs are correct.
|
||||
|
||||
Or configure via `hermes tools` → Browser Automation → Camofox.
|
||||
|
||||
When `CAMOFOX_URL` is set, all browser tools automatically route through Camofox instead of Browserbase or agent-browser.
|
||||
@@ -376,9 +395,9 @@ BROWSERBASE_ADVANCED_STEALTH=false
|
||||
# Session reconnection after disconnects — requires paid plan (default: "true")
|
||||
BROWSERBASE_KEEP_ALIVE=true
|
||||
|
||||
# Custom session timeout in milliseconds (default: project default)
|
||||
# Examples: 600000 (10min), 1800000 (30min)
|
||||
BROWSERBASE_SESSION_TIMEOUT=600000
|
||||
# Custom session timeout in seconds (max 21600 = 6 hours) (default: project default)
|
||||
# Examples: 600 (10min), 1800 (30min), 21600 (6h max)
|
||||
BROWSERBASE_SESSION_TIMEOUT=1800
|
||||
|
||||
# Inactivity timeout before auto-cleanup in seconds (default: 120)
|
||||
BROWSER_INACTIVITY_TIMEOUT=120
|
||||
|
||||
@@ -219,6 +219,62 @@ terminal:
|
||||
|
||||
See the [Security guide](/user-guide/security#environment-variable-passthrough) for full details.
|
||||
|
||||
### `HERMES_*` variables in the child
|
||||
|
||||
The child process receives only a small, fixed set of operational `HERMES_*`
|
||||
variables by exact name:
|
||||
|
||||
- `HERMES_HOME`
|
||||
- `HERMES_PROFILE`
|
||||
- `HERMES_CONFIG`
|
||||
- `HERMES_ENV`
|
||||
|
||||
(plus `HERMES_RPC_DIR` / `HERMES_RPC_SOCKET` / `TZ` / `HOME`, which Hermes
|
||||
injects explicitly so the RPC channel works).
|
||||
|
||||
:::note Behavior change
|
||||
Earlier versions passed **any** variable whose name began with `HERMES_`
|
||||
through to the child. That broad prefix was removed for security hardening: it
|
||||
could leak `HERMES_*`-named configuration that doesn't match a secret substring
|
||||
(for example `HERMES_BASE_URL`, `HERMES_KANBAN_DB`, or a `HERMES_*_WEBHOOK`
|
||||
endpoint) into arbitrary sandboxed code.
|
||||
|
||||
If an `execute_code` script — or a repo/plugin module it imports at import time
|
||||
— relied on a `HERMES_*` variable outside the four operational names above, it
|
||||
will now find that variable **unset** in the child. The drop is intentional,
|
||||
not a bug.
|
||||
:::
|
||||
|
||||
**Workaround — opt the variable back in explicitly.** Both routes pass the
|
||||
variable through `execute_code` *and* `terminal` children, and neither weakens
|
||||
the secret-stripping guarantee (Hermes-managed provider credentials can never
|
||||
be re-allowed this way):
|
||||
|
||||
1. **Per-machine, in `config.yaml`** — add the exact variable name to the
|
||||
passthrough allowlist:
|
||||
|
||||
```yaml
|
||||
terminal:
|
||||
env_passthrough:
|
||||
- HERMES_KANBAN_DB
|
||||
- HERMES_BASE_URL
|
||||
```
|
||||
|
||||
2. **Per-skill, in the skill's frontmatter** — declare it so it is registered
|
||||
automatically whenever that skill is loaded:
|
||||
|
||||
```yaml
|
||||
required_environment_variables:
|
||||
- HERMES_KANBAN_DB
|
||||
```
|
||||
|
||||
**Diagnosing it.** When the child drops one or more non-allowlisted `HERMES_*`
|
||||
variables, Hermes emits a one-line `debug` log naming them and pointing at the
|
||||
`env_passthrough` escape hatch. Run with debug logging (`hermes logs --level
|
||||
DEBUG`, or check `~/.hermes/logs/agent.log`) and look for
|
||||
`execute_code: dropped N non-allowlisted HERMES_* var(s)` if a script behaves
|
||||
as though a `HERMES_*` variable is missing.
|
||||
|
||||
Hermes always writes the script and the auto-generated `hermes_tools.py` RPC stub into a temp staging directory that is cleaned up after execution. In `strict` mode the script also *runs* there; in `project` mode it runs in the session's working directory (the staging directory stays on `PYTHONPATH` so imports still resolve). The child process runs in its own process group so it can be cleanly killed on timeout or interruption.
|
||||
|
||||
## execute_code vs terminal
|
||||
|
||||
@@ -9,6 +9,10 @@ Hermes can optionally hand `openai/*` and `openai-codex/*` turns to the [Codex C
|
||||
|
||||
This is **opt-in only**. Default Hermes behavior is unchanged unless you flip the flag. Hermes never auto-routes you onto this runtime.
|
||||
|
||||
:::tip
|
||||
Not using OpenAI Codex? `hermes setup --portal` configures a non-Codex backend with Claude/Gemini/etc. in one step. See [Nous Portal](/integrations/nous-portal).
|
||||
:::
|
||||
|
||||
## Why
|
||||
|
||||
- Run OpenAI agent turns against your **ChatGPT subscription** (no API key required) using the same auth flow Codex CLI uses.
|
||||
|
||||
@@ -11,6 +11,10 @@ Credential pools let you register multiple API keys or OAuth tokens for the same
|
||||
|
||||
This is different from [fallback providers](./fallback-providers.md), which switch to a *different* provider entirely. Credential pools are same-provider rotation; fallback providers are cross-provider failover. Pools are tried first — if all pool keys are exhausted, *then* the fallback provider activates.
|
||||
|
||||
:::tip
|
||||
Credential pools are mainly for API-key providers (OpenRouter, Anthropic). A single [Nous Portal](/integrations/nous-portal) OAuth covers 300+ models, so most users don't need a pool when on Portal.
|
||||
:::
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
@@ -18,8 +22,11 @@ Your request
|
||||
→ Pick key from pool (round_robin / least_used / fill_first / random)
|
||||
→ Send to provider
|
||||
→ 429 rate limit?
|
||||
→ Retry same key once (transient blip)
|
||||
→ Second 429 → rotate to next pool key
|
||||
→ Plan/usage limit reached (e.g. ChatGPT/Codex "usage limit reached")?
|
||||
→ Rotate to next pool key immediately (no retry — the cap won't clear on retry)
|
||||
→ Generic / transient 429?
|
||||
→ Retry same key once (transient blip)
|
||||
→ Second 429 → rotate to next pool key
|
||||
→ All keys exhausted → fallback_model (different provider)
|
||||
→ 402 billing error?
|
||||
→ Immediately rotate to next pool key (24h cooldown)
|
||||
|
||||
@@ -21,6 +21,10 @@ Cron jobs can:
|
||||
|
||||
All of this is available to Hermes itself through the `cronjob` tool, so you can create, pause, edit, and remove jobs by asking in plain language — no CLI required.
|
||||
|
||||
:::tip
|
||||
Cron jobs use whatever provider `hermes model` selected. `hermes setup --portal` is the lowest-friction option for unattended runs since OAuth refresh is automatic. See [Nous Portal](/integrations/nous-portal).
|
||||
:::
|
||||
|
||||
:::warning
|
||||
Cron-run sessions cannot recursively create more cron jobs. Hermes disables cron management tools inside cron executions to prevent runaway scheduling loops.
|
||||
:::
|
||||
@@ -113,12 +117,12 @@ cronjob(
|
||||
When `workdir` is set:
|
||||
|
||||
- `AGENTS.md`, `CLAUDE.md`, and `.cursorrules` from that directory are injected into the system prompt (same discovery order as the interactive CLI)
|
||||
- `terminal`, `read_file`, `write_file`, `patch`, `search_files`, and `execute_code` all use that directory as their working directory (via `TERMINAL_CWD`)
|
||||
- `terminal`, `read_file`, `write_file`, `patch`, `search_files`, and `execute_code` all use that directory as their working directory
|
||||
- The path must be an absolute directory that exists — relative paths and missing directories are rejected at create / update time
|
||||
- Pass `--workdir ""` (or `workdir=""` via the tool) on edit to clear it and restore the old behaviour
|
||||
|
||||
:::note Serialization
|
||||
Jobs with a `workdir` run sequentially on the scheduler tick, not in the parallel pool. This is deliberate — `TERMINAL_CWD` is process-global, so two workdir jobs running at the same time would corrupt each other's cwd. Workdir-less jobs still run in parallel as before.
|
||||
Jobs with a `workdir` run sequentially on the scheduler tick, not in the parallel pool. This is deliberate: the cron worker applies the job workdir through process-global terminal state, so two workdir jobs running at the same time would corrupt each other's cwd. Workdir-less jobs still run in parallel as before.
|
||||
:::
|
||||
|
||||
## Running cron jobs in a specific profile
|
||||
@@ -204,10 +208,11 @@ Cron jobs now have a fuller lifecycle than just create/remove.
|
||||
|
||||
```bash
|
||||
hermes cron list
|
||||
hermes cron pause <job_id>
|
||||
hermes cron resume <job_id>
|
||||
hermes cron run <job_id>
|
||||
hermes cron remove <job_id>
|
||||
hermes cron pause <job_id_or_name>
|
||||
hermes cron resume <job_id_or_name>
|
||||
hermes cron run <job_id_or_name>
|
||||
hermes cron remove <job_id_or_name>
|
||||
hermes cron edit <job_id_or_name> [...flags]
|
||||
hermes cron status
|
||||
hermes cron tick
|
||||
```
|
||||
@@ -218,6 +223,9 @@ What they do:
|
||||
- `resume` — re-enable the job and compute the next future run
|
||||
- `run` — trigger the job on the next scheduler tick
|
||||
- `remove` — delete it entirely
|
||||
- `edit` — modify schedule, prompt, profile, delivery, etc.
|
||||
|
||||
**Name-based lookup.** All four mutating verbs (`pause`, `resume`, `run`, `remove`, `edit`) plus the agent's `cronjob` tool now accept a job **name** (case-insensitive) in place of the hex ID. The agent and CLI both prefer an exact ID match if one exists; ambiguous name matches (multiple jobs sharing the same name) are refused with the full list of candidate IDs so you can pick one explicitly. Names are not unique, so this guard is load-bearing — it prevents silently mutating the wrong job when two share a name.
|
||||
|
||||
## How it works
|
||||
|
||||
|
||||
@@ -130,30 +130,45 @@ The same subcommands are available as the `/curator` slash command inside a runn
|
||||
|
||||
## What "agent-created" means
|
||||
|
||||
A skill is considered agent-created if its name is **not** in:
|
||||
The curator only manages skills explicitly marked as **agent-created** in
|
||||
`~/.hermes/skills/.usage.json`. A skill qualifies when ALL of the following
|
||||
are true:
|
||||
|
||||
- `~/.hermes/skills/.bundled_manifest` (skills copied from the repo on install), and
|
||||
- `~/.hermes/skills/.hub/lock.json` (skills installed via `hermes skills install`).
|
||||
1. Its name is **not** in `~/.hermes/skills/.bundled_manifest` (bundled skills shipped with the repo).
|
||||
2. Its name is **not** in `~/.hermes/skills/.hub/lock.json` (hub-installed skills).
|
||||
3. Its `.usage.json` entry has `"created_by": "agent"` or `"agent_created": true`.
|
||||
|
||||
Everything else in `~/.hermes/skills/` is fair game for the curator. This includes:
|
||||
Currently, only the **background self-improvement review fork** sets this marker
|
||||
— when it creates a new umbrella skill during its periodic review pass (~every 10
|
||||
agent turns). The background fork runs with a write origin of `"background_review"`
|
||||
(via `tools/skill_provenance.py`), which is the only path that triggers the
|
||||
`mark_agent_created()` call in `skill_manage`.
|
||||
|
||||
- Skills the agent saved via `skill_manage(action="create")` during a conversation.
|
||||
- Skills you created manually with a hand-written `SKILL.md`.
|
||||
- Skills added via external skill directories you've pointed Hermes at.
|
||||
Skills the foreground agent creates via `skill_manage(action="create")` during a
|
||||
conversation are **not** marked as agent-created — they are considered
|
||||
user-directed and the curator intentionally leaves them alone.
|
||||
|
||||
:::warning Your hand-written skills look the same as agent-saved ones
|
||||
Provenance here is **binary** (bundled/hub vs. everything else). The curator cannot tell a hand-authored skill you rely on for private workflows apart from a skill the self-improvement loop saved mid-session. Both land in the "agent-created" bucket.
|
||||
:::warning Your hand-written skills are NOT curated
|
||||
If you manually created a `SKILL.md` or pointed Hermes at an external skill
|
||||
directory, that skill will have a `.usage.json` entry with `created_by: null`
|
||||
(or the field absent). The curator will not touch it. The same applies to
|
||||
skills the foreground agent created at your request.
|
||||
|
||||
Before the first real pass (7 days after installation by default), take a moment to:
|
||||
|
||||
1. Run `hermes curator run --dry-run` to see exactly what the curator would propose.
|
||||
2. Use `hermes curator pin <name>` to fence off anything you don't want touched.
|
||||
3. Or set `curator.enabled: false` in `config.yaml` if you'd rather manage the library yourself.
|
||||
|
||||
Archives are always recoverable via `hermes curator restore <name>`, but it's easier to pin up-front than to chase down a consolidation after the fact.
|
||||
**To see which skills the curator actually manages**, run `hermes curator status`.
|
||||
If the agent-created count is 0, no skills are currently in the curator's
|
||||
jurisdiction — the LLM review pass is skipped and the report will show
|
||||
`Model: (not resolved) via (not resolved)` with `Duration: 0s`.
|
||||
:::
|
||||
|
||||
If you want to protect a specific skill from ever being touched — for example a hand-authored skill you rely on — use `hermes curator pin <name>`. See the next section.
|
||||
Skills that ARE agent-created follow the full lifecycle:
|
||||
|
||||
- `active` → (30d unused) `stale` → (90d unused) `archived`
|
||||
- Pinned skills bypass all auto-transitions
|
||||
- Archives are recoverable via `hermes curator restore <name>`
|
||||
|
||||
If you want to protect a specific skill from ever being touched — for example a
|
||||
hand-authored skill you rely on — use `hermes curator pin <name>`. See the next
|
||||
section.
|
||||
|
||||
## Pinning a skill
|
||||
|
||||
@@ -217,6 +232,15 @@ Every curator run writes a timestamped directory under `~/.hermes/logs/curator/`
|
||||
|
||||
`REPORT.md` is a quick way to see what a given run did — which skills transitioned, what the LLM reviewer said, which skills it patched. Good for auditing without having to grep `agent.log`.
|
||||
|
||||
:::note No candidates? Report shows `(not resolved)`
|
||||
When the curator has **no agent-created skills** to review, the LLM review pass
|
||||
is skipped entirely. The report header will show
|
||||
`Model: (not resolved) via (not resolved)` with `Duration: 0s` — this does **not**
|
||||
indicate a configuration error or model resolution failure. It simply means there
|
||||
were no candidates, so no model was ever invoked. The auto-transition phase still
|
||||
runs and reports its counts normally.
|
||||
:::
|
||||
|
||||
### Rename map in the summary
|
||||
|
||||
If a run consolidated multiple skills under an umbrella (or merged near-duplicates), the user-visible summary printed at the end of the run includes an explicit rename map showing every `old-name → new-name` pair the curator applied. This is in addition to per-skill transition lines, so when a wave of renames lands you can spot them at a glance without diffing the JSON report. The hint also surfaces under `hermes curator pin` so you can pin the umbrella name immediately if you want to lock the new label in.
|
||||
|
||||
@@ -63,8 +63,10 @@ personality entry that biases toward artifact-style replies on
|
||||
messaging platforms.
|
||||
|
||||
**Project-level:** add the bias to `AGENTS.md` / `CLAUDE.md` /
|
||||
`.cursorrules` in a project the agent works from, or to your global
|
||||
custom instructions in `~/.hermes/config.yaml` under `agent.custom_instructions`.
|
||||
`.cursorrules` in a project the agent works from, to your global
|
||||
persona in `~/.hermes/SOUL.md`, or as a named preset under
|
||||
`agent.personalities` in `~/.hermes/config.yaml` (switchable per session
|
||||
via `/personality`).
|
||||
|
||||
The mechanic the agent has to use is simple: render the file to an
|
||||
absolute path (e.g. `/tmp/q3-revenue.png`) and mention that path as
|
||||
|
||||
@@ -17,7 +17,7 @@ All three are **drop-in at runtime**: no repo clone, no `npm run build`, no patc
|
||||
If you just want to use the dashboard, see [Web Dashboard](./web-dashboard). If you want to reskin the terminal CLI (not the web dashboard), see [Skins & Themes](./skins) — the CLI skin system is unrelated to dashboard themes.
|
||||
|
||||
:::note How the pieces compose
|
||||
Themes and plugins are independent but synergistic. A theme can stand alone (just a YAML file). A plugin can stand alone (just a tab). Together they let you build a complete visual reskin with custom HUDs — the bundled `strike-freedom-cockpit` demo does exactly that. See [Combined theme + plugin demo](#combined-theme--plugin-demo).
|
||||
Themes and plugins are independent but synergistic. A theme can stand alone (just a YAML file). A plugin can stand alone (just a tab). Together they let you build a complete visual reskin with custom HUDs — the example `strike-freedom-cockpit` demo (lives in the `hermes-example-plugins` companion repo — see [Combined theme + plugin demo](#combined-theme--plugin-demo) for install steps) does exactly that.
|
||||
:::
|
||||
|
||||
---
|
||||
@@ -470,7 +470,7 @@ Plugins use Lucide icon names. The dashboard maps these by name — unknown name
|
||||
|
||||
Currently mapped: `Activity`, `BarChart3`, `Clock`, `Code`, `Database`, `Eye`, `FileText`, `Globe`, `Heart`, `KeyRound`, `MessageSquare`, `Package`, `Puzzle`, `Settings`, `Shield`, `Sparkles`, `Star`, `Terminal`, `Wrench`, `Zap`.
|
||||
|
||||
Need a different icon? Open a PR to `apps/dashboard/src/App.tsx`'s `ICON_MAP` — pure additive change.
|
||||
Need a different icon? Open a PR to `web/src/App.tsx`'s `ICON_MAP` — pure additive change.
|
||||
|
||||
### The Plugin SDK
|
||||
|
||||
|
||||
@@ -29,18 +29,18 @@ hermes fallback
|
||||
|
||||
`hermes fallback` reuses the provider picker from `hermes model` — same provider list, same credential prompts, same validation. Use the subcommands `add`, `list` (alias `ls`), `remove` (alias `rm`), and `clear` to manage the chain. Changes persist under the top-level `fallback_providers:` list in `config.yaml`.
|
||||
|
||||
If you'd rather edit the YAML directly, add a `fallback_model` section to `~/.hermes/config.yaml`:
|
||||
If you'd rather edit the YAML directly, add a top-level `fallback_providers` list to `~/.hermes/config.yaml`:
|
||||
|
||||
```yaml
|
||||
fallback_model:
|
||||
provider: openrouter
|
||||
model: anthropic/claude-sonnet-4
|
||||
fallback_providers:
|
||||
- provider: openrouter
|
||||
model: anthropic/claude-sonnet-4
|
||||
```
|
||||
|
||||
Both `provider` and `model` are **required**. If either is missing, the fallback is disabled.
|
||||
Each entry requires both `provider` and `model`. Entries missing either field are ignored.
|
||||
|
||||
:::note `fallback_model` vs `fallback_providers`
|
||||
`fallback_model` (singular) is the legacy single-fallback key — Hermes still honors it for back-compat. `fallback_providers` (plural, list) supports multiple fallbacks tried in order; `hermes fallback` writes to this key. When both are set, Hermes merges them with `fallback_providers` taking priority.
|
||||
`fallback_providers` (plural, list) is the current config shape and supports multiple fallbacks tried in order. `fallback_model` (singular) is the legacy single-fallback key — Hermes still honors it for back-compat, but `hermes fallback` writes the current `fallback_providers` key and migrates legacy config on write. When both are set, `fallback_providers` takes priority.
|
||||
:::
|
||||
|
||||
### Supported Providers
|
||||
@@ -90,11 +90,11 @@ Both `provider` and `model` are **required**. If either is missing, the fallback
|
||||
For a custom OpenAI-compatible endpoint, add `base_url` and optionally `key_env`:
|
||||
|
||||
```yaml
|
||||
fallback_model:
|
||||
provider: custom
|
||||
model: my-local-model
|
||||
base_url: http://localhost:8000/v1
|
||||
key_env: MY_LOCAL_KEY # env var name containing the API key
|
||||
fallback_providers:
|
||||
- provider: custom
|
||||
model: my-local-model
|
||||
base_url: http://localhost:8000/v1
|
||||
key_env: MY_LOCAL_KEY # env var name containing the API key
|
||||
```
|
||||
|
||||
### When Fallback Triggers
|
||||
@@ -128,9 +128,9 @@ model:
|
||||
provider: anthropic
|
||||
default: claude-sonnet-4-6
|
||||
|
||||
fallback_model:
|
||||
provider: openrouter
|
||||
model: anthropic/claude-sonnet-4
|
||||
fallback_providers:
|
||||
- provider: openrouter
|
||||
model: anthropic/claude-sonnet-4
|
||||
```
|
||||
|
||||
**Nous Portal as fallback for OpenRouter:**
|
||||
@@ -139,25 +139,25 @@ model:
|
||||
provider: openrouter
|
||||
default: anthropic/claude-opus-4
|
||||
|
||||
fallback_model:
|
||||
provider: nous
|
||||
model: nous-hermes-3
|
||||
fallback_providers:
|
||||
- provider: nous
|
||||
model: nous-hermes-3
|
||||
```
|
||||
|
||||
**Local model as fallback for cloud:**
|
||||
```yaml
|
||||
fallback_model:
|
||||
provider: custom
|
||||
model: llama-3.1-70b
|
||||
base_url: http://localhost:8000/v1
|
||||
key_env: LOCAL_API_KEY
|
||||
fallback_providers:
|
||||
- provider: custom
|
||||
model: llama-3.1-70b
|
||||
base_url: http://localhost:8000/v1
|
||||
key_env: LOCAL_API_KEY
|
||||
```
|
||||
|
||||
**Codex OAuth as fallback:**
|
||||
```yaml
|
||||
fallback_model:
|
||||
provider: openai-codex
|
||||
model: gpt-5.3-codex
|
||||
fallback_providers:
|
||||
- provider: openai-codex
|
||||
model: gpt-5.3-codex
|
||||
```
|
||||
|
||||
### Where Fallback Works
|
||||
@@ -166,12 +166,12 @@ fallback_model:
|
||||
|---------|-------------------|
|
||||
| CLI sessions | ✔ |
|
||||
| Messaging gateway (Telegram, Discord, etc.) | ✔ |
|
||||
| Subagent delegation | ✘ (subagents do not inherit fallback config) |
|
||||
| Cron jobs | ✘ (run with a fixed provider) |
|
||||
| Subagent delegation | ✔ (subagents inherit the parent fallback chain) |
|
||||
| Cron jobs | ✔ (cron agents inherit configured fallback providers) |
|
||||
| Auxiliary tasks (vision, compression) | ✘ (use their own provider chain — see below) |
|
||||
|
||||
:::tip
|
||||
There are no environment variables for `fallback_model` — it is configured exclusively through `config.yaml`. This is intentional: fallback configuration is a deliberate choice, not something a stale shell export should override.
|
||||
There are no environment variables for the primary fallback chain — configure it exclusively through `config.yaml` or `hermes fallback`. This is intentional: fallback configuration is a deliberate choice, not something a stale shell export should override.
|
||||
:::
|
||||
|
||||
---
|
||||
@@ -252,20 +252,20 @@ auxiliary:
|
||||
base_url: null # Custom OpenAI-compatible endpoint
|
||||
```
|
||||
|
||||
And the fallback model uses:
|
||||
And the primary fallback chain uses:
|
||||
|
||||
```yaml
|
||||
fallback_model:
|
||||
provider: openrouter
|
||||
model: anthropic/claude-sonnet-4
|
||||
# base_url: http://localhost:8000/v1 # Optional custom endpoint
|
||||
fallback_providers:
|
||||
- provider: openrouter
|
||||
model: anthropic/claude-sonnet-4
|
||||
# base_url: http://localhost:8000/v1 # Optional custom endpoint
|
||||
```
|
||||
|
||||
All three — auxiliary, compression, fallback — work the same way: set `provider` to pick who handles the request, `model` to pick which model, and `base_url` to point at a custom endpoint (overrides provider).
|
||||
|
||||
### Provider Options for Auxiliary Tasks
|
||||
|
||||
These options apply to `auxiliary:`, `compression:`, and `fallback_model:` configs only — `"main"` is **not** a valid value for your top-level `model.provider`. For custom endpoints, use `provider: custom` in your `model:` section (see [AI Providers](/integrations/providers)).
|
||||
These options apply to `auxiliary:`, `compression:`, and `fallback_providers:` entries only — `"main"` is **not** a valid value for your top-level `model.provider`. For custom endpoints, use `provider: custom` in your `model:` section (see [AI Providers](/integrations/providers)).
|
||||
|
||||
| Provider | Description | Requirements |
|
||||
|----------|-------------|-------------|
|
||||
@@ -362,7 +362,7 @@ If no provider is available for compression, Hermes drops middle conversation tu
|
||||
|
||||
## Delegation Provider Override
|
||||
|
||||
Subagents spawned by `delegate_task` do **not** use the primary fallback model. However, they can be routed to a different provider:model pair for cost optimization:
|
||||
Subagents spawned by `delegate_task` inherit the parent agent's primary fallback chain. You can still route subagents to a different primary provider:model pair for cost optimization:
|
||||
|
||||
```yaml
|
||||
delegation:
|
||||
@@ -378,7 +378,7 @@ See [Subagent Delegation](/user-guide/features/delegation) for full configuratio
|
||||
|
||||
## Cron Job Providers
|
||||
|
||||
Cron jobs run with whatever provider is configured at execution time. They do not support a fallback model. To use a different provider for cron jobs, configure `provider` and `model` overrides on the cron job itself:
|
||||
Cron jobs inherit your configured `fallback_providers` chain (or legacy `fallback_model`) when they create an agent. To use a different primary provider for a cron job, configure `provider` and `model` overrides on the cron job itself:
|
||||
|
||||
```python
|
||||
cronjob(
|
||||
@@ -398,7 +398,7 @@ See [Scheduled Tasks (Cron)](/user-guide/features/cron) for full configuration d
|
||||
|
||||
| Feature | Fallback Mechanism | Config Location |
|
||||
|---------|-------------------|----------------|
|
||||
| Main agent model | `fallback_model` in config.yaml — per-turn failover on errors (primary restored each turn) | `fallback_model:` (top-level) |
|
||||
| Main agent model | `fallback_providers` in config.yaml — per-turn failover on errors (primary restored each turn) | `fallback_providers:` (top-level list) |
|
||||
| Auxiliary tasks (any) — auto users | Full auto-detection chain (main agent model first, then provider chain) on capacity errors | `auxiliary.<task>.provider: auto` |
|
||||
| Auxiliary tasks (any) — explicit provider | `fallback_chain` (if set) → main agent model → warn + raise, on capacity errors only | `auxiliary.<task>.fallback_chain` |
|
||||
| Vision | Layered (see above) + internal OpenRouter retry | `auxiliary.vision` |
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
---
|
||||
title: Image Generation
|
||||
description: Generate images via FAL.ai — 9 models including FLUX 2, GPT Image (1.5 & 2), Nano Banana Pro, Ideogram, Recraft V4 Pro, and more, selectable via `hermes tools`.
|
||||
description: Generate images via FAL.ai — 11 models including FLUX 2, GPT Image (1.5 & 2), Nano Banana Pro, Ideogram, Recraft V4 Pro, Krea 2, and more, selectable via `hermes tools`.
|
||||
sidebar_label: Image Generation
|
||||
sidebar_position: 6
|
||||
---
|
||||
|
||||
# Image Generation
|
||||
|
||||
Hermes Agent generates images from text prompts via FAL.ai. Nine models are supported out of the box, each with different speed, quality, and cost tradeoffs. The active model is user-configurable via `hermes tools` and persists in `config.yaml`.
|
||||
Hermes Agent generates images from text prompts via FAL.ai. Eleven models are supported out of the box, each with different speed, quality, and cost tradeoffs. The active model is user-configurable via `hermes tools` and persists in `config.yaml`.
|
||||
|
||||
## Supported Models
|
||||
|
||||
@@ -22,6 +22,8 @@ Hermes Agent generates images from text prompts via FAL.ai. Nine models are supp
|
||||
| `fal-ai/ideogram/v3` | ~5s | Best typography | $0.03–0.09/image |
|
||||
| `fal-ai/recraft/v4/pro/text-to-image` | ~8s | Design, brand systems, production-ready | $0.25/image |
|
||||
| `fal-ai/qwen-image` | ~12s | LLM-based, complex text | $0.02/MP |
|
||||
| `fal-ai/krea/v2/medium/text-to-image` | ~15-25s | Illustration, anime, painting, expressive/artistic styles | $0.030–0.035/image |
|
||||
| `fal-ai/krea/v2/large/text-to-image` | ~25-60s | Photorealism, raw textured looks (motion blur, grain, film) | $0.060–0.065/image |
|
||||
|
||||
Prices are FAL's pricing at time of writing; check [fal.ai](https://fal.ai/) for current numbers.
|
||||
|
||||
|
||||
@@ -604,7 +604,10 @@ hermes kanban create "<title>" [--body ...] [--assignee <profile>]
|
||||
[--max-retries N]
|
||||
[--skill <name>]...
|
||||
[--json]
|
||||
hermes kanban list [--mine] [--assignee P] [--status S] [--tenant T] [--archived] [--json]
|
||||
hermes kanban list [--mine] [--assignee P] [--status S] [--tenant T] [--archived]
|
||||
[--workflow-template-id <id>] [--current-step-key <key>]
|
||||
[--sort created|created-desc|priority|priority-desc|status|assignee|title|updated]
|
||||
[--json]
|
||||
hermes kanban show <id> [--json]
|
||||
hermes kanban assign <id> <profile> # or 'none' to unassign
|
||||
hermes kanban link <parent_id> <child_id>
|
||||
@@ -646,6 +649,62 @@ All commands are also available as a slash command in the interactive CLI and in
|
||||
|
||||
`--max-retries` is a per-task circuit-breaker override for the dispatcher. `--max-retries 1` blocks the task on the first non-successful attempt, while `--max-retries 3` allows two retries and blocks on the third failure. Omit it to use `kanban.failure_limit` from `config.yaml`, then the built-in default.
|
||||
|
||||
### Concurrency, scheduling, and child promotion config
|
||||
|
||||
| Config key | Default | What it does |
|
||||
|------------|---------|--------------|
|
||||
| `kanban.max_in_progress` | unset (unlimited) | Caps the number of simultaneously running tasks. When the board already has N running, the dispatcher skips spawning more — useful for slow workers (local LLMs, resource-constrained hosts) so they finish what they have before more pile up and time out. Invalid or below-1 values log a warning and behave as unlimited. |
|
||||
| `kanban.auto_promote_children` | `true` | After `decompose_triage_task()` produces children with no parent-blocker dependencies, they're automatically promoted to `ready` so the dispatcher can pick them up. Set to `false` to require manual review — children stay in `todo` until you promote them. |
|
||||
| `kanban.default_workdir` | unset | Board-level default working directory applied to new tasks when neither `--workspace` nor the task itself overrides it. Per-task `workspace:` still wins. |
|
||||
|
||||
```yaml
|
||||
kanban:
|
||||
max_in_progress: 2
|
||||
auto_promote_children: false
|
||||
default_workdir: ~/work/active-project
|
||||
```
|
||||
|
||||
### Scheduled task starts (`scheduled_at`)
|
||||
|
||||
Set `scheduled_at` on a task to delay dispatch until a specific time. The dispatcher skips ready tasks whose `scheduled_at` is in the future and picks them up on the first tick after that timestamp.
|
||||
|
||||
```bash
|
||||
hermes kanban create "nightly backup audit" \
|
||||
--assignee ops --scheduled-at "2026-06-01T03:00:00Z"
|
||||
```
|
||||
|
||||
### Respawn guard
|
||||
|
||||
The dispatcher refuses to re-spawn a ready task when it hit a quota/auth/429 error on the previous run (`blocker_auth`), or completed a run successfully within the guard window (`recent_success`), or a recent task comment links to a GitHub PR (`active_pr`). This prevents repeat worker storms on the same bug or task while a human catches up. See the `respawn_guarded` row in the [event reference](#event-reference).
|
||||
|
||||
### Drag-to-delete and bulk delete (dashboard)
|
||||
|
||||
The dashboard exposes a **trash drop zone** on the kanban page — drag any card into it to delete the task (cascades through `task_events`, child links, and subscriptions). A confirmation prompt protects against accidents. Bulk delete is also reachable via `DELETE /api/plugins/kanban/tasks` with a JSON body `{"ids": ["t_abc", "t_def", ...]}`.
|
||||
|
||||
### Worker visibility endpoints
|
||||
|
||||
The dashboard plugin API now exposes three read-only endpoints for external monitors:
|
||||
|
||||
| Endpoint | Returns |
|
||||
|----------|---------|
|
||||
| `GET /api/plugins/kanban/workers/active` | Currently spawned workers with PID, profile, task id, started-at, last heartbeat |
|
||||
| `GET /api/plugins/kanban/runs/{id}` | Single-run detail — task id, status, started/ended, exit code, log path |
|
||||
| `GET /api/plugins/kanban/inspect` | Combined dispatcher snapshot — backlog, in-progress count vs. `max_in_progress`, recent events |
|
||||
|
||||
All three are gated by the same dashboard plugin auth as the rest of the kanban plugin API.
|
||||
|
||||
### Kanban Swarm topology helper
|
||||
|
||||
`hermes kanban swarm` creates a durable **Kanban Swarm v1** graph in one shot: a completed root/blackboard card, N parallel worker cards, a verifier card gated on all workers, and a synthesizer card gated on the verifier. Shared swarm context (the "blackboard") is stored as structured JSON comments on the root card so any worker can read it.
|
||||
|
||||
```bash
|
||||
hermes kanban swarm "Design a multi-region failover plan" \
|
||||
--workers researcher,architect,sre \
|
||||
--verifier reviewer --synthesizer writer
|
||||
```
|
||||
|
||||
The resulting graph dispatches normally — workers run in parallel, the verifier wakes after they all finish, the synthesizer wakes after the verifier marks the work clean.
|
||||
|
||||
## `/kanban` slash command {#kanban-slash-command}
|
||||
|
||||
Every `hermes kanban <action>` verb is also reachable as `/kanban <action>` — from inside an interactive `hermes chat` session **and** from any gateway platform (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, email, SMS). Both surfaces call the exact same `hermes_cli.kanban.run_slash()` entry point that reuses the `hermes kanban` argparse tree, so the argument surface, flags, and output format are identical across CLI, `/kanban`, and `hermes kanban`. You don't have to leave the chat to drive the board.
|
||||
|
||||
@@ -229,6 +229,20 @@ On first connect, Hermes prints an authorize URL, opens your browser when possib
|
||||
|
||||
See [OAuth over SSH / Remote Hosts](../../guides/oauth-over-ssh.md#mcp-servers) for the full walkthrough, including DCR-less servers (e.g. Slack), pre-registered `client_id`/`client_secret`, scope customization, and re-auth via `hermes mcp login <server>`.
|
||||
|
||||
**Pitfall — providers that don't support automatic registration (Google Drive, Atlassian).** Some servers reject the dynamic client registration step (RFC 7591) that bare `auth: oauth` relies on — Google's official Drive server (`https://drivemcp.googleapis.com/mcp/v1`) returns a `400 Bad Request`, so no OAuth client is created and no token is acquired. The symptom is subtle: these servers also serve `tools/list` *without* auth, so `hermes mcp login` can list the tools and look like it worked, but every real tool call later times out. `hermes mcp login` now detects this (it checks that a token actually landed on disk) and tells you to supply your own OAuth client. Create one in the provider's console and add it to config:
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
googledrive:
|
||||
url: "https://drivemcp.googleapis.com/mcp/v1"
|
||||
auth: oauth
|
||||
oauth:
|
||||
client_id: "<your-oauth-client-id>"
|
||||
client_secret: "<your-oauth-client-secret>"
|
||||
```
|
||||
|
||||
Then run `hermes mcp login googledrive` — with the pre-registered client, Hermes skips registration and runs the normal browser authorization flow.
|
||||
|
||||
**Pitfall — config auto-reload race.** When you edit `~/.hermes/config.yaml` from inside a running Hermes session, the CLI auto-reloads MCP connections with a 30s timeout. That's not enough for an interactive OAuth flow. Add the entry, then run `hermes mcp login <server>` from a fresh terminal — it waits the full 5 minutes for you to complete auth.
|
||||
|
||||
## Basic configuration reference
|
||||
|
||||
@@ -68,7 +68,7 @@ hermes memory setup # select "honcho" — runs the Honcho-specific post-s
|
||||
|
||||
The legacy `hermes honcho setup` command still works (it now redirects to `hermes memory setup`), but is only registered after Honcho is selected as the active memory provider.
|
||||
|
||||
**Config:** `$HERMES_HOME/honcho.json` (profile-local) or `~/.honcho/config.json` (global). Resolution order: `$HERMES_HOME/honcho.json` > `~/.hermes/honcho.json` > `~/.honcho/config.json`. See the [config reference](https://github.com/hermes-ai/hermes-agent/blob/main/plugins/memory/honcho/README.md) and the [Honcho integration guide](https://docs.honcho.dev/v3/guides/integrations/hermes).
|
||||
**Config:** `$HERMES_HOME/honcho.json` (profile-local) or `~/.honcho/config.json` (global). Resolution order: `$HERMES_HOME/honcho.json` > `~/.hermes/honcho.json` > `~/.honcho/config.json`. See the [config reference](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/honcho/README.md) and the [Honcho integration guide](https://docs.honcho.dev/v3/guides/integrations/hermes).
|
||||
|
||||
<details>
|
||||
<summary>Full config reference</summary>
|
||||
@@ -255,7 +255,7 @@ See the [Honcho page](./honcho.md#observation-directional-vs-unified) for the fu
|
||||
|
||||
</details>
|
||||
|
||||
See the [config reference](https://github.com/hermes-ai/hermes-agent/blob/main/plugins/memory/honcho/README.md) and [Honcho integration guide](https://docs.honcho.dev/v3/guides/integrations/hermes).
|
||||
See the [config reference](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/honcho/README.md) and [Honcho integration guide](https://docs.honcho.dev/v3/guides/integrations/hermes).
|
||||
|
||||
|
||||
---
|
||||
@@ -520,6 +520,27 @@ echo 'SUPERMEMORY_API_KEY=***' >> ~/.hermes/.env
|
||||
|
||||
**Support:** [Discord](https://supermemory.link/discord) · [support@supermemory.com](mailto:support@supermemory.com)
|
||||
|
||||
### Memori
|
||||
|
||||
Structured long-term memory using Memori Cloud, with background completed-turn capture, tool-aware turn context, and explicit recall tools for facts, summaries, quota, signup, and feedback.
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Best for** | Agent-controlled recall with structured project and session attribution |
|
||||
| **Requires** | `pip install hermes-memori` + `hermes-memori install` + [Memori API key](https://app.memorilabs.ai/signup) |
|
||||
| **Data storage** | Memori Cloud |
|
||||
| **Cost** | Memori pricing |
|
||||
|
||||
**Tools:** `memori_recall` (search long-term memory), `memori_recall_summary` (summarized context), `memori_quota` (usage/quota), `memori_signup` (request signup email), `memori_feedback` (send integration feedback)
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
pip install hermes-memori
|
||||
hermes-memori install
|
||||
hermes config set memory.provider memori
|
||||
hermes memory setup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Provider Comparison
|
||||
@@ -534,6 +555,7 @@ echo 'SUPERMEMORY_API_KEY=***' >> ~/.hermes/.env
|
||||
| **RetainDB** | Cloud | $20/mo | 5 | `requests` | Delta compression |
|
||||
| **ByteRover** | Local/Cloud | Free/Paid | 3 | `brv` CLI | Pre-compression extraction |
|
||||
| **Supermemory** | Cloud | Paid | 4 | `supermemory` | Context fencing + session graph ingest + multi-container |
|
||||
| **Memori** | Cloud | Free/Paid | 5 | `hermes-memori` | Tool-aware memory + structured recall |
|
||||
|
||||
## Profile Isolation
|
||||
|
||||
|
||||
@@ -8,6 +8,10 @@ sidebar_position: 1
|
||||
|
||||
Hermes Agent includes a rich set of capabilities that extend far beyond basic chat. From persistent memory and file-aware context to browser automation and voice conversations, these features work together to make Hermes a powerful autonomous assistant.
|
||||
|
||||
:::tip Don't know where to start?
|
||||
`hermes setup --portal` covers a model provider plus all four Tool Gateway tools (web search, image generation, TTS, browser) in one command. See [Nous Portal](/integrations/nous-portal).
|
||||
:::
|
||||
|
||||
## Core
|
||||
|
||||
- **[Tools & Toolsets](tools.md)** — Tools are functions that extend the agent's capabilities. They're organized into logical toolsets that can be enabled or disabled per platform, covering web search, terminal execution, file editing, memory, delegation, and more.
|
||||
@@ -43,7 +47,7 @@ Hermes Agent includes a rich set of capabilities that extend far beyond basic ch
|
||||
- **[Memory Providers](memory-providers.md)** — Plug in external memory backends (Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, Supermemory) for cross-session user modeling and personalization beyond the built-in memory system.
|
||||
- **[API Server](api-server.md)** — Expose Hermes as an OpenAI-compatible HTTP endpoint. Connect any frontend that speaks the OpenAI format — Open WebUI, LobeChat, LibreChat, and more.
|
||||
- **[IDE Integration (ACP)](acp.md)** — Use Hermes inside ACP-compatible editors such as VS Code, Zed, and JetBrains. Chat, tool activity, file diffs, and terminal commands render inside your editor.
|
||||
- **[RL Training](rl-training.md)** — Generate trajectory data from agent sessions for reinforcement learning and model fine-tuning.
|
||||
- **[Batch Processing](batch-processing.md)** — Run the agent over many prompts or tasks in parallel from the CLI, with structured outputs and trajectory capture suitable for evals or downstream training pipelines.
|
||||
|
||||
## Customization
|
||||
|
||||
|
||||
@@ -11,6 +11,10 @@ When using [OpenRouter](https://openrouter.ai) as your LLM provider, Hermes Agen
|
||||
|
||||
OpenRouter routes requests to many providers (e.g., Anthropic, Google, AWS Bedrock, Together AI). Provider routing lets you optimize for cost, speed, quality, or enforce specific provider requirements.
|
||||
|
||||
:::tip
|
||||
Traffic routed through [Nous Portal](/integrations/nous-portal) still respects per-model routing and priority configs — and Portal subscribers get 10% off token-billed providers.
|
||||
:::
|
||||
|
||||
## Configuration
|
||||
|
||||
Add a `provider_routing` section to your `~/.hermes/config.yaml`:
|
||||
|
||||
@@ -411,7 +411,7 @@ hermes skills tap add myorg/skills-repo # Add a custom GitHub source
|
||||
| `well-known` | `well-known:https://mintlify.com/docs/.well-known/skills/mintlify` | Skills served directly from `/.well-known/skills/index.json` on a website. Search using the site or docs URL. |
|
||||
| `url` | `https://sharethis.chat/SKILL.md` | Direct HTTP(S) URL to a single-file `SKILL.md`. Name resolution: frontmatter → URL slug → interactive prompt → `--name` flag. |
|
||||
| `github` | `openai/skills/k8s` | Direct GitHub repo/path installs and custom taps. |
|
||||
| `clawhub`, `lobehub`, `browse-sh`, `claude-marketplace` | Source-specific identifiers | Community or marketplace integrations. |
|
||||
| `clawhub`, `lobehub`, `browse-sh` | Source-specific identifiers | Community or marketplace integrations. |
|
||||
|
||||
### Integrated hubs and registries
|
||||
|
||||
@@ -419,7 +419,7 @@ Hermes currently integrates with these skills ecosystems and discovery sources:
|
||||
|
||||
#### 1. Official optional skills (`official`)
|
||||
|
||||
These are maintained in the Hermes repository itself and install with builtin trust.
|
||||
These are maintained in the Hermes repository itself and install with built-in trust.
|
||||
|
||||
- Catalog: [Official Optional Skills Catalog](../../reference/optional-skills-catalog)
|
||||
- Source in repo: `optional-skills/`
|
||||
@@ -467,6 +467,7 @@ Default taps (browsable without any setup):
|
||||
- [openai/skills](https://github.com/openai/skills)
|
||||
- [anthropics/skills](https://github.com/anthropics/skills)
|
||||
- [huggingface/skills](https://github.com/huggingface/skills)
|
||||
- [NVIDIA/skills](https://github.com/NVIDIA/skills) — NVIDIA-verified skills (signed `skill.oms.sig` + governance `skill-card.md`)
|
||||
- [garrytan/gstack](https://github.com/garrytan/gstack)
|
||||
|
||||
- Example:
|
||||
@@ -476,6 +477,25 @@ hermes skills install openai/skills/k8s
|
||||
hermes skills tap add myorg/skills-repo
|
||||
```
|
||||
|
||||
**Category groupings (`skills.sh.json`).** A GitHub tap may ship a
|
||||
`skills.sh.json` file at its repo root following the
|
||||
[skills.sh schema](https://skills.sh/schemas/skills.sh.schema.json). Its
|
||||
`groupings` (each with a `title` and a list of skill names) are read at index
|
||||
time and become the category labels shown in the
|
||||
[Skills Hub](https://hermes-agent.nousresearch.com/docs) page — instead of a
|
||||
tag-derived guess. This is generic: any tap that ships the file gets real
|
||||
categorization, no Hermes-side changes required.
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://skills.sh/schemas/skills.sh.schema.json",
|
||||
"groupings": [
|
||||
{ "title": "Inference AI", "skills": ["dynamo-recipe-runner", "dynamo-router-sla"] },
|
||||
{ "title": "Decision Optimization", "skills": ["cuopt-developer", "cuopt-install"] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. ClawHub (`clawhub`)
|
||||
|
||||
A third-party skills marketplace integrated as a community source.
|
||||
@@ -569,15 +589,15 @@ hermes skills install skills-sh/anthropics/skills/pdf --force
|
||||
Important behavior:
|
||||
- `--force` can override policy blocks for caution/warn-style findings.
|
||||
- `--force` does **not** override a `dangerous` scan verdict.
|
||||
- Official optional skills (`official/...`) are treated as builtin trust and do not show the third-party warning panel.
|
||||
- Official optional skills (`official/...`) are treated as built-in trust and do not show the third-party warning panel.
|
||||
|
||||
### Trust levels
|
||||
|
||||
| Level | Source | Policy |
|
||||
|-------|--------|--------|
|
||||
| `builtin` | Ships with Hermes | Always trusted |
|
||||
| `official` | `optional-skills/` in the repo | Builtin trust, no third-party warning |
|
||||
| `trusted` | Trusted registries/repos such as `openai/skills`, `anthropics/skills`, `huggingface/skills` | More permissive policy than community sources |
|
||||
| `official` | `optional-skills/` in the repo | Built-in trust, no third-party warning |
|
||||
| `trusted` | Trusted registries/repos such as `openai/skills`, `anthropics/skills`, `huggingface/skills`, `NVIDIA/skills` | More permissive policy than community sources |
|
||||
| `community` | Everything else (`skills.sh`, well-known endpoints, custom GitHub repos, most marketplaces) | Non-dangerous findings can be overridden with `--force`; `dangerous` verdicts stay blocked |
|
||||
|
||||
### Update lifecycle
|
||||
|
||||
@@ -72,9 +72,9 @@ automatically when the bearer approaches expiry.
|
||||
hermes proxy providers
|
||||
```
|
||||
|
||||
Currently shipped: `nous` (Nous Portal). More OAuth providers can be
|
||||
added by implementing the `UpstreamAdapter` interface in
|
||||
`hermes_cli/proxy/adapters/`.
|
||||
Currently shipped: `nous` (Nous Portal) and `xai` (xAI / Grok). More
|
||||
OAuth providers can be added by implementing the `UpstreamAdapter`
|
||||
interface in `hermes_cli/proxy/adapters/`.
|
||||
|
||||
## Check status
|
||||
|
||||
|
||||
@@ -0,0 +1,159 @@
|
||||
---
|
||||
title: Tool Search
|
||||
sidebar_position: 95
|
||||
---
|
||||
|
||||
# Tool Search
|
||||
|
||||
When you have many MCP servers or non-core plugin tools attached to a
|
||||
session, their JSON schemas can consume a substantial fraction of the
|
||||
context window on every turn — even when only a few of them are relevant
|
||||
to what the user actually asked for.
|
||||
|
||||
**Tool Search** is Hermes' opt-in progressive-disclosure layer for that
|
||||
problem. When activated, MCP and plugin tools are replaced in the
|
||||
model-visible tools array by three bridge tools, and the model loads each
|
||||
specific tool's schema on demand.
|
||||
|
||||
:::info Built-in Hermes tools never defer
|
||||
The tools that make up Hermes' core capability set (`terminal`,
|
||||
`read_file`, `write_file`, `patch`, `search_files`, `todo`, `memory`,
|
||||
`browser_*`, `web_search`, `web_extract`, `clarify`, `execute_code`,
|
||||
`delegate_task`, `session_search`, `send_message`, and the rest of
|
||||
`_HERMES_CORE_TOOLS`) are *always* loaded directly. Only MCP tools and
|
||||
non-core plugin tools are eligible for deferral.
|
||||
:::
|
||||
|
||||
## How it works
|
||||
|
||||
When Tool Search activates for a turn, the model sees three new tools in
|
||||
place of the deferred ones:
|
||||
|
||||
```
|
||||
tool_search(query, limit?) — search the deferred-tool catalog
|
||||
tool_describe(name) — load the full schema for one tool
|
||||
tool_call(name, arguments) — invoke a deferred tool
|
||||
```
|
||||
|
||||
A typical interaction looks like:
|
||||
|
||||
```
|
||||
Model: tool_search("create a github issue")
|
||||
→ { matches: [{ name: "mcp_github_create_issue", ... }, ...] }
|
||||
Model: tool_describe("mcp_github_create_issue")
|
||||
→ { parameters: { type: "object", properties: { ... } } }
|
||||
Model: tool_call("mcp_github_create_issue", { title: "...", body: "..." })
|
||||
→ { ok: true, issue_number: 42 }
|
||||
```
|
||||
|
||||
When the model invokes `tool_call`, Hermes **unwraps the bridge** and
|
||||
dispatches the underlying tool exactly as if the model had called it
|
||||
directly. Pre-tool-call hooks, guardrails, approval prompts, and
|
||||
post-tool-call hooks all run against the real tool name — not against
|
||||
`tool_call`. The activity feed in the CLI and gateway also unwraps so you
|
||||
see the underlying tool, not the bridge.
|
||||
|
||||
## When does it activate?
|
||||
|
||||
By default Tool Search runs in `auto` mode: it activates only when the
|
||||
deferrable tool schemas would consume at least 10% of the active model's
|
||||
context window. Below that, the tools-array assembly is a pure
|
||||
pass-through and you pay no overhead.
|
||||
|
||||
This decision is re-evaluated every time the tools array is built, so:
|
||||
|
||||
- A session with just a few MCP tools and a long context model never
|
||||
activates Tool Search.
|
||||
- A session with many MCP servers attached (15+ tools typically) starts
|
||||
activating it.
|
||||
- Removing MCP servers mid-session correctly returns to direct exposure
|
||||
on the next assembly.
|
||||
|
||||
## Configuration
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
tool_search:
|
||||
enabled: auto # auto (default), on, or off
|
||||
threshold_pct: 10 # percentage of context — only used in auto mode
|
||||
search_default_limit: 5
|
||||
max_search_limit: 20
|
||||
```
|
||||
|
||||
| Key | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `enabled` | `auto` | `auto` activates above threshold; `on` always activates if there's at least one deferrable tool; `off` disables entirely. |
|
||||
| `threshold_pct` | `10` | Percentage of context length at which `auto` mode kicks in. Range 0–100. |
|
||||
| `search_default_limit` | `5` | Hits returned when the model calls `tool_search` without a `limit`. |
|
||||
| `max_search_limit` | `20` | Hard upper bound the model can request via `limit`. Range 1–50. |
|
||||
|
||||
You can also flip the legacy boolean shape:
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
tool_search: true # equivalent to {enabled: auto}
|
||||
```
|
||||
|
||||
## When NOT to use it
|
||||
|
||||
Tool Search trades a fixed per-turn token cost (the three bridge tool
|
||||
schemas, ~300 tokens) and at least one extra round trip (search →
|
||||
describe → call) for the savings on the deferred schemas. It's a clear
|
||||
win when you have many tools and use few per turn; it's overhead when
|
||||
you have few tools total.
|
||||
|
||||
The `auto` default handles this for you. If you set `enabled: on`
|
||||
unconditionally, expect a slight per-turn cost on small toolsets.
|
||||
|
||||
## Trade-offs that don't go away
|
||||
|
||||
These come from the prompt-cache integrity invariant — they are inherent
|
||||
to any progressive-disclosure design, not specific to this implementation:
|
||||
|
||||
- **One extra round trip on cold tools.** The first time the model needs
|
||||
a deferred tool, it spends one or two extra model calls to find and
|
||||
load the schema. The token savings on the static side are real, but a
|
||||
portion is paid back at runtime.
|
||||
- **No cache benefit on deferred schemas.** A loaded `tool_describe`
|
||||
result enters the conversation history (so it does get cached on
|
||||
subsequent turns) but it never benefits from the system-prompt cache
|
||||
prefix.
|
||||
- **Model-quality dependence.** Tool Search assumes the model can write a
|
||||
reasonable search query for the tool it wants. Smaller models do this
|
||||
less well; the published Anthropic numbers (49% → 74% on Opus 4 with
|
||||
vs. without tool search) show the upside but also that ~26 points of
|
||||
accuracy is still retrieval failure.
|
||||
- **Toolset edits invalidate cache.** Adding or removing a tool mid-
|
||||
session changes the bridge tools' descriptions (which include the
|
||||
count of deferred tools) and the catalog, so the prompt cache is
|
||||
invalidated. This is the same trade-off as any toolset edit.
|
||||
|
||||
## Implementation details
|
||||
|
||||
- **Retrieval:** BM25 over tokenized tool name + description + parameter
|
||||
names. Falls back to a literal substring match on the tool name when
|
||||
BM25 returns no positive-score hits, which protects against
|
||||
zero-IDF degenerate cases (e.g. searching `"github"` against a
|
||||
catalog where every tool name contains "github").
|
||||
- **Catalog is stateless across turns.** It rebuilds from the current
|
||||
tool-defs list every assembly — no session-keyed `Map`. This avoids
|
||||
the class of bug where a stored catalog drifts out of sync with the
|
||||
live tool registry.
|
||||
- **The catalog is scoped to the session's toolsets.** `tool_search`,
|
||||
`tool_describe`, and `tool_call` only ever see and invoke tools the
|
||||
session was actually granted. A subagent, kanban worker, or gateway
|
||||
session restricted to a subset of toolsets cannot use the bridge to
|
||||
discover or call a tool outside that subset — the deferred catalog is
|
||||
the deferrable slice of the session's own enabled/disabled toolsets,
|
||||
not the whole process registry.
|
||||
- **No JS sandbox.** Hermes uses the simpler "structured tools" mode
|
||||
(search / describe / call as plain functions). The JS-sandbox "code
|
||||
mode" some other implementations offer is a large surface area; we
|
||||
skip it.
|
||||
|
||||
## See also
|
||||
|
||||
- `tools/tool_search.py` — the implementation
|
||||
- `tests/tools/test_tool_search.py` — the regression suite
|
||||
- The `openclaw-tool-search-report` PDF in the original implementation
|
||||
PR for the research that shaped the design
|
||||
@@ -113,6 +113,7 @@ Each provider has a documented per-request input-character cap. Hermes truncates
|
||||
| ElevenLabs | Model-aware (see below) |
|
||||
| NeuTTS | 2000 |
|
||||
| KittenTTS | 2000 |
|
||||
| Piper | 5000 |
|
||||
|
||||
**ElevenLabs** picks a cap from the configured `model_id`:
|
||||
|
||||
|
||||
@@ -9,6 +9,10 @@ sidebar_position: 7
|
||||
|
||||
Hermes Agent supports **multimodal vision** — you can paste images from your clipboard directly into the CLI and ask the agent to analyze, describe, or work with them. Images are sent to the model as base64-encoded content blocks, so any vision-capable model can process them.
|
||||
|
||||
:::tip
|
||||
Portal subscribers get vision-capable models (Claude, GPT-5, Gemini) in the same catalog — no extra credentials needed. See [Nous Portal](/integrations/nous-portal).
|
||||
:::
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Copy an image to your clipboard (screenshot, browser image, etc.)
|
||||
|
||||
@@ -8,6 +8,10 @@ description: "Browser-based dashboard for managing configuration, API keys, sess
|
||||
|
||||
The web dashboard is a browser-based UI for managing your Hermes Agent installation. Instead of editing YAML files or running CLI commands, you can configure settings, manage API keys, and monitor sessions from a clean web interface.
|
||||
|
||||
:::tip
|
||||
Hosted-mode auth uses Nous Portal OAuth; if you also want the dashboard to talk to a real backend, `hermes setup --portal` wires up the model and tool gateway too. See [Nous Portal](/integrations/nous-portal).
|
||||
:::
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
@@ -491,7 +495,7 @@ If you're contributing to the web dashboard frontend:
|
||||
hermes dashboard --no-open
|
||||
|
||||
# Terminal 2: start the Vite dev server with HMR
|
||||
cd apps/dashboard/
|
||||
cd web/
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Web Search & Extract
|
||||
description: Search the web, extract page content, and crawl websites with multiple backend providers — including free self-hosted SearXNG.
|
||||
description: Search the web and extract page content with multiple backend providers — including free self-hosted SearXNG.
|
||||
sidebar_label: Web Search
|
||||
sidebar_position: 6
|
||||
---
|
||||
@@ -10,22 +10,22 @@ sidebar_position: 6
|
||||
Hermes Agent includes two model-callable web tools backed by multiple providers:
|
||||
|
||||
- **`web_search`** — search the web and return ranked results
|
||||
- **`web_extract`** — fetch and extract readable content from one or more URLs (with built-in deep-crawl support when the backend provides it)
|
||||
- **`web_extract`** — fetch and extract readable content from one or more URLs
|
||||
|
||||
Both are configured through a single backend selection. Providers are chosen via `hermes tools` or set directly in `config.yaml`. Recursive crawling capabilities (Firecrawl/Tavily) are exposed through `web_extract` rather than as a separate `web_crawl` tool.
|
||||
Both are configured through a single backend selection. Providers are chosen via `hermes tools` or set directly in `config.yaml`.
|
||||
|
||||
## Backends
|
||||
|
||||
| Provider | Env Var | Search | Extract | Crawl | Free tier |
|
||||
|----------|---------|--------|---------|-------|-----------|
|
||||
| **Firecrawl** (default) | `FIRECRAWL_API_KEY` | ✔ | ✔ | ✔ | 500 credits/mo |
|
||||
| **SearXNG** | `SEARXNG_URL` | ✔ | — | — | ✔ Free (self-hosted) |
|
||||
| **Brave Search (free tier)** | `BRAVE_SEARCH_API_KEY` | ✔ | — | — | 2 000 queries/mo |
|
||||
| **DDGS (DuckDuckGo)** | — (no key) | ✔ | — | — | ✔ Free |
|
||||
| **Tavily** | `TAVILY_API_KEY` | ✔ | ✔ | ✔ | 1 000 searches/mo |
|
||||
| **Exa** | `EXA_API_KEY` | ✔ | ✔ | — | 1 000 searches/mo |
|
||||
| **Parallel** | `PARALLEL_API_KEY` | ✔ | ✔ | — | Paid |
|
||||
| **xAI (Grok)** | `XAI_API_KEY` or `hermes auth login xai-oauth` | ✔ | — | — | Paid (SuperGrok or per-token) |
|
||||
| Provider | Env Var | Search | Extract | Free tier |
|
||||
|----------|---------|--------|---------|-----------|
|
||||
| **Firecrawl** (default) | `FIRECRAWL_API_KEY` | ✔ | ✔ | 500 credits/mo |
|
||||
| **SearXNG** | `SEARXNG_URL` | ✔ | — | ✔ Free (self-hosted) |
|
||||
| **Brave Search (free tier)** | `BRAVE_SEARCH_API_KEY` | ✔ | — | 2 000 queries/mo |
|
||||
| **DDGS (DuckDuckGo)** | — (no key) | ✔ | — | ✔ Free |
|
||||
| **Tavily** | `TAVILY_API_KEY` | ✔ | ✔ | 1 000 searches/mo |
|
||||
| **Exa** | `EXA_API_KEY` | ✔ | ✔ | 1 000 searches/mo |
|
||||
| **Parallel** | `PARALLEL_API_KEY` | ✔ | ✔ | Paid |
|
||||
| **xAI (Grok)** | `XAI_API_KEY` or `hermes auth login xai-oauth` | ✔ | — | Paid (SuperGrok or per-token) |
|
||||
|
||||
Brave Search, DDGS, and xAI are **search-only** — pair any of them with Firecrawl/Tavily/Exa/Parallel when you also need `web_extract`. DDGS uses the [`ddgs` Python package](https://pypi.org/project/ddgs/) under the hood; if it isn't already installed, run `pip install ddgs` (or let Hermes lazy-install it on first use). xAI runs Grok's server-side `web_search` tool on the Responses API — results are LLM-generated rather than index-backed, so titles, descriptions, and URL choice are all model output (see the [trust-model caveat](#xai-grok) below).
|
||||
|
||||
@@ -46,7 +46,7 @@ Backends return raw page markdown, which can be huge (forum threads, docs sites,
|
||||
| Under 5 000 | Returned as-is — no LLM call, full markdown reaches the agent |
|
||||
| 5 000 – 500 000 | Single-pass summary via the `web_extract` auxiliary model, capped at ~5 000 chars of output |
|
||||
| 500 000 – 2 000 000 | Chunked: split into 100 k-char chunks, summarize each in parallel, then synthesize a final summary (~5 000 chars) |
|
||||
| Over 2 000 000 | Refused with a hint to use `web_crawl` with focused extraction instructions or a more specific source |
|
||||
| Over 2 000 000 | Refused with a hint to use a more focused source URL |
|
||||
|
||||
The summary keeps quotes, code blocks, and key facts in their original formatting — it's a content compressor, not a paraphraser. If summarization fails or times out, Hermes falls back to the first ~5 000 chars of raw content rather than a useless error.
|
||||
|
||||
@@ -89,7 +89,7 @@ hermes tools
|
||||
|
||||
### Firecrawl (default)
|
||||
|
||||
Full-featured search, extract, and crawl. Recommended for most users.
|
||||
Full-featured search and extract. Recommended for most users.
|
||||
|
||||
```bash
|
||||
# ~/.hermes/.env
|
||||
@@ -113,7 +113,7 @@ When `FIRECRAWL_API_URL` is set, the API key is optional (disable server auth wi
|
||||
|
||||
SearXNG is a privacy-respecting, open-source metasearch engine that aggregates results from 70+ search engines. **No API key required** — just point Hermes at a running SearXNG instance.
|
||||
|
||||
SearXNG is **search-only** — `web_extract` (including its crawl modes) requires a separate extract provider.
|
||||
SearXNG is **search-only** — `web_extract` requires a separate extract provider.
|
||||
|
||||
#### Option A — Self-host with Docker (recommended)
|
||||
|
||||
@@ -222,7 +222,7 @@ Public instances have rate limits, variable uptime, and may disable JSON format
|
||||
|
||||
#### Pair SearXNG with an extract provider
|
||||
|
||||
SearXNG handles search; you need a separate provider for `web_extract` (including any deep-crawl modes). Use the per-capability keys:
|
||||
SearXNG handles search; you need a separate provider for `web_extract`. Use the per-capability keys:
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
@@ -237,7 +237,7 @@ With this config, Hermes uses SearXNG for all search queries and Firecrawl for U
|
||||
|
||||
### Tavily
|
||||
|
||||
AI-optimised search, extract, and crawl with a generous free tier.
|
||||
AI-optimised search and extract with a generous free tier.
|
||||
|
||||
```bash
|
||||
# ~/.hermes/.env
|
||||
@@ -341,7 +341,7 @@ Use different providers for search vs extract. This lets you combine free search
|
||||
# ~/.hermes/config.yaml
|
||||
web:
|
||||
search_backend: "searxng" # used by web_search
|
||||
extract_backend: "firecrawl" # used by web_extract (and its deep-crawl modes)
|
||||
extract_backend: "firecrawl" # used by web_extract
|
||||
```
|
||||
|
||||
When per-capability keys are empty, both fall through to `web.backend`. When `web.backend` is also empty, the backend is auto-detected from whichever API key/URL is present.
|
||||
|
||||
@@ -11,6 +11,10 @@ The `x_search` tool lets the agent search X (Twitter) posts, profiles, and threa
|
||||
|
||||
**Use this instead of `web_search`** when you specifically want current discussion, reactions, or claims **on X**. For general web pages, keep using `web_search` / `web_extract`.
|
||||
|
||||
:::tip
|
||||
If you're paying Portal for an xAI model anyway, Live Search calls bill against the same xAI key configured for chat. See [Nous Portal](/integrations/nous-portal).
|
||||
:::
|
||||
|
||||
## Authentication
|
||||
|
||||
`x_search` registers when **either** xAI credential path is available:
|
||||
|
||||
@@ -21,7 +21,7 @@ This page shows how to combine worktrees with Hermes so each session has a clean
|
||||
Hermes treats the **current working directory** as the project root:
|
||||
|
||||
- CLI: the directory where you run `hermes` or `hermes chat`
|
||||
- Messaging gateways: the directory set by `MESSAGING_CWD`
|
||||
- Messaging gateways: the directory set by `terminal.cwd` in `~/.hermes/config.yaml`
|
||||
|
||||
If you run multiple agents in the **same checkout**, their changes can interfere with each other:
|
||||
|
||||
@@ -171,4 +171,3 @@ This combination gives you:
|
||||
- Strong guarantees that different agents and experiments do not step on each other.
|
||||
- Fast iteration cycles with easy recovery from bad edits.
|
||||
- Clean, reviewable pull requests.
|
||||
|
||||
|
||||
@@ -8,10 +8,17 @@ description: "Set up Hermes Agent as an email assistant via IMAP/SMTP"
|
||||
|
||||
Hermes can receive and reply to emails using standard IMAP and SMTP protocols. Send an email to the agent's address and it replies in-thread — no special client or bot API needed. Works with Gmail, Outlook, Yahoo, Fastmail, or any provider that supports IMAP/SMTP.
|
||||
|
||||
:::info No External Dependencies
|
||||
The Email adapter uses Python's built-in `imaplib`, `smtplib`, and `email` modules. No additional packages or external services are required.
|
||||
:::info Gateway adapter only: no external dependencies
|
||||
This page covers the Email gateway adapter, which uses Python's built-in `imaplib`, `smtplib`, and `email` modules. No additional packages or external services are required for this gateway path.
|
||||
:::
|
||||
|
||||
This is separate from the bundled [Himalaya email skill](/docs/user-guide/skills/bundled/email/email-himalaya), which lets the agent manage email through terminal commands and requires the external `himalaya` CLI plus a Himalaya config file.
|
||||
|
||||
| Use case | What to configure | External dependency |
|
||||
|---|---|---|
|
||||
| Let people email the Hermes agent and receive replies | Email gateway adapter on this page | None beyond an IMAP/SMTP email account |
|
||||
| Let the agent inspect, compose, move, and manage mailbox messages from terminal tools | Himalaya email skill | `himalaya` CLI and `~/.config/himalaya/config.toml` |
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -55,6 +55,40 @@ If scan-to-create is not available, the wizard falls back to manual input:
|
||||
Keep the App Secret private. Anyone with it can impersonate your app.
|
||||
:::
|
||||
|
||||
### Configure Permissions
|
||||
|
||||
In the Feishu developer console, go to **Permission Management** and add the following scopes. You can bulk-import them in the permissions page.
|
||||
|
||||
**Required permissions:**
|
||||
|
||||
| Scope | Purpose |
|
||||
|-------|---------|
|
||||
| `im:message` | Receive and read messages |
|
||||
| `im:message:send_as_bot` | Send messages as the bot |
|
||||
| `im:resource` | Access images, files, and audio sent by users |
|
||||
| `im:chat` | Access chat/group metadata |
|
||||
| `im:chat:readonly` | Read chat list and membership |
|
||||
|
||||
**Recommended permissions (for full functionality):**
|
||||
|
||||
| Scope | Purpose |
|
||||
|-------|---------|
|
||||
| `im:message.reactions:readonly` | Receive emoji reaction events |
|
||||
| `admin:app.info:readonly` | Auto-detect bot identity for @mention gating |
|
||||
| `contact:user.id:readonly` | Resolve user IDs for allowlist matching |
|
||||
|
||||
### Configure Events
|
||||
|
||||
In **Events and Callbacks**:
|
||||
|
||||
1. Set the connection mode to **Long Connection (WebSocket)** (recommended) or configure a webhook URL
|
||||
2. In the **Event Configuration** section, subscribe to:
|
||||
- `im.message.receive_v1` — required for receiving messages
|
||||
|
||||
### Publish the App
|
||||
|
||||
After configuring permissions and events, go to **Version Management** and publish a new version of the app. The permissions won't take effect until a version is published and approved (for enterprise apps, this may require admin approval).
|
||||
|
||||
## Step 2: Choose a Connection Mode
|
||||
|
||||
### Recommended: WebSocket mode
|
||||
|
||||
@@ -13,6 +13,8 @@ process does not need a public URL, a tunnel, or a TLS certificate. It connects,
|
||||
authenticates, and listens on a subscription — the same way a Telegram bot listens
|
||||
on a token.
|
||||
|
||||
> Run `hermes gateway setup` and pick **Google Chat** for a guided walk-through.
|
||||
|
||||
:::note Workspace edition
|
||||
Google Chat is part of Google Workspace. You can use this integration with a
|
||||
personal Workspace (`@yourdomain.com` registered through Google) or a work
|
||||
@@ -237,7 +239,7 @@ specifically, as the user who asked for the file.
|
||||
4. On the host, register the client with Hermes:
|
||||
|
||||
```bash
|
||||
python -m gateway.platforms.google_chat_user_oauth \
|
||||
python -m plugins.platforms.google_chat.oauth \
|
||||
--client-secret /path/to/client_secret.json
|
||||
```
|
||||
|
||||
@@ -330,7 +332,7 @@ The one-time host setup wasn't done. From a terminal on the host that runs
|
||||
Hermes:
|
||||
|
||||
```bash
|
||||
python -m gateway.platforms.google_chat_user_oauth \
|
||||
python -m plugins.platforms.google_chat.oauth \
|
||||
--client-secret /path/to/client_secret.json
|
||||
```
|
||||
|
||||
|
||||
@@ -250,3 +250,26 @@ Agent automatically:
|
||||
entity_id="light.hallway")
|
||||
3. Sends notification: "Front door opened. Hallway lights turned on."
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Environment variables not picked up.**
|
||||
The adapter reads credentials from `~/.hermes/.env` (auto-merged at startup) or
|
||||
from `config.yaml`. Double-check the file lives under the active Hermes profile
|
||||
home and that there's no stray quoting around the URL/token. Restart the gateway
|
||||
after editing — env changes are only applied on process start.
|
||||
|
||||
**`conversation entity not found` / agent never replies.**
|
||||
Home Assistant's conversation API requires a configured *Assist* conversation
|
||||
agent. In HA, open **Settings → Voice assistants → Add assistant** and note the
|
||||
resulting entity id (looks like `conversation.home_assistant` or
|
||||
`conversation.openai_<name>`). Set that entity id in the adapter's
|
||||
`conversation_entity` setting; the default may not exist on your instance.
|
||||
|
||||
**REST auth failing (`401 Unauthorized`).**
|
||||
The token must be a *Long-Lived Access Token* created from your HA user profile
|
||||
page (**Profile → Security → Long-lived access tokens**). Short-lived UI
|
||||
session tokens won't work. Also verify the base URL includes the scheme and
|
||||
port (e.g. `http://homeassistant.local:8123`) and is reachable from the host
|
||||
running Hermes — `curl -H "Authorization: Bearer <token>" <url>/api/` should
|
||||
return `{"message": "API running."}`.
|
||||
|
||||
@@ -10,6 +10,10 @@ Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Ho
|
||||
|
||||
For the full voice feature set — including CLI microphone mode, spoken replies in messaging, and Discord voice-channel conversations — see [Voice Mode](/user-guide/features/voice-mode) and [Use Voice Mode with Hermes](/guides/use-voice-mode-with-hermes).
|
||||
|
||||
:::tip
|
||||
Bots need both a model provider and tool providers (TTS, web). A [Nous Portal](/integrations/nous-portal) subscription bundles all of them.
|
||||
:::
|
||||
|
||||
## Platform Comparison
|
||||
|
||||
| Platform | Voice | Images | Files | Threads | Reactions | Typing | Streaming |
|
||||
|
||||
@@ -10,6 +10,8 @@ Run Hermes Agent as a [LINE](https://line.me/) bot via the official LINE Messagi
|
||||
|
||||
LINE is the dominant messaging app in Japan, Taiwan, and Thailand. If your users live there, this is how they reach you.
|
||||
|
||||
> Run `hermes gateway setup` and pick **LINE** for a guided walk-through.
|
||||
|
||||
## How the bot responds
|
||||
|
||||
| Context | Behavior |
|
||||
|
||||
@@ -25,6 +25,7 @@ platforms:
|
||||
msgraph_webhook:
|
||||
enabled: true
|
||||
extra:
|
||||
host: 127.0.0.1
|
||||
port: 8646
|
||||
client_state: "replace-with-a-strong-secret"
|
||||
accepted_resources:
|
||||
@@ -40,6 +41,8 @@ MSGRAPH_WEBHOOK_CLIENT_STATE=<generate-with-openssl-rand-hex-32>
|
||||
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings
|
||||
```
|
||||
|
||||
Note: the bind host is read from `extra.host` in `config.yaml` (see the example above); there is no `MSGRAPH_WEBHOOK_HOST` env-var override.
|
||||
|
||||
Start the gateway: `hermes gateway run`. The listener exposes:
|
||||
|
||||
- `POST /msgraph/webhook` — change notifications from Graph
|
||||
@@ -58,14 +61,14 @@ All settings go under `platforms.msgraph_webhook.extra`:
|
||||
|
||||
| Setting | Default | Description |
|
||||
|---------|---------|-------------|
|
||||
| `host` | `0.0.0.0` | Bind address for the HTTP listener. |
|
||||
| `host` | `0.0.0.0` | Bind address for the HTTP listener. Non-loopback binds require `allowed_source_cidrs`; loopback (`127.0.0.1` / `::1`) is the easiest dev-tunnel / reverse-proxy setup. |
|
||||
| `port` | `8646` | Bind port. |
|
||||
| `webhook_path` | `/msgraph/webhook` | URL path Graph POSTs to. |
|
||||
| `health_path` | `/health` | Readiness endpoint. |
|
||||
| `client_state` | — | Shared secret Graph echoes in every notification. Compared with `hmac.compare_digest` — generate with `openssl rand -hex 32`. |
|
||||
| `accepted_resources` | `[]` (accept all) | Allowlist of Graph resource paths/patterns. Trailing `*` acts as prefix match. Leading `/` is tolerated. Example: `["communications/onlineMeetings", "chats/*/messages"]`. |
|
||||
| `max_seen_receipts` | `5000` | Dedupe cache size for notification IDs. Oldest entries evicted when the cap is hit. |
|
||||
| `allowed_source_cidrs` | `[]` (allow all) | Optional source-IP allowlist. See below. |
|
||||
| `allowed_source_cidrs` | `[]` | Required for non-loopback binds. Leave empty only when the listener is bound to loopback and fronted by a local tunnel / reverse proxy. |
|
||||
|
||||
Each setting also has an equivalent env var (`MSGRAPH_WEBHOOK_*`) that merges into the config at gateway startup — see the [environment variables reference](/reference/environment-variables#microsoft-graph-teams-meetings).
|
||||
|
||||
@@ -75,7 +78,7 @@ Each setting also has an equivalent env var (`MSGRAPH_WEBHOOK_*`) that merges in
|
||||
|
||||
Every Graph notification includes the `clientState` string your subscription registered with. The listener rejects any notification whose `clientState` doesn't match, using timing-safe comparison. This is Microsoft's documented mechanism — treat the value as a strong shared secret.
|
||||
|
||||
If `client_state` is unset, the listener accepts every well-formed POST. **Don't run without it in production.**
|
||||
If `client_state` is unset, the listener refuses to start.
|
||||
|
||||
### Source-IP allowlisting (production deployments)
|
||||
|
||||
@@ -86,6 +89,7 @@ platforms:
|
||||
msgraph_webhook:
|
||||
enabled: true
|
||||
extra:
|
||||
host: 0.0.0.0
|
||||
client_state: "..."
|
||||
allowed_source_cidrs:
|
||||
- "52.96.0.0/14"
|
||||
@@ -99,7 +103,7 @@ Or as an env var:
|
||||
MSGRAPH_WEBHOOK_ALLOWED_SOURCE_CIDRS="52.96.0.0/14,52.104.0.0/14"
|
||||
```
|
||||
|
||||
Empty allowlist = accept from anywhere (default; preserves dev-tunnel workflows). Invalid CIDR strings log a warning and are ignored. **Review the Microsoft IP list quarterly** — it changes.
|
||||
Binding a non-loopback host such as `0.0.0.0`, `::`, or a LAN IP without `allowed_source_cidrs` is refused at startup. If you're using a dev tunnel or reverse proxy on the same machine, bind Hermes to `127.0.0.1` or `::1` and leave the allowlist empty there. Invalid CIDR strings log a warning and are ignored. **Review the Microsoft IP list quarterly** — it changes.
|
||||
|
||||
### HTTPS termination
|
||||
|
||||
@@ -107,7 +111,7 @@ The listener speaks plain HTTP. Terminate TLS at your reverse proxy (Caddy, Ngin
|
||||
|
||||
### Response hygiene
|
||||
|
||||
On success the listener returns `202 Accepted` with an empty body — internal counters stay out of the wire response. Operators can observe counts via `/health`.
|
||||
On success the listener returns `202 Accepted` with an empty body — internal counters stay out of the wire response. Operators can observe counts via `/health`, which is guarded by the same source-IP rules as the webhook path.
|
||||
|
||||
Status code table:
|
||||
|
||||
@@ -127,8 +131,9 @@ Status code table:
|
||||
| Graph subscription validation fails | Public URL is reachable, `/msgraph/webhook` path matches, GET with `validationToken` echoes the token verbatim as `text/plain` within 10 seconds. |
|
||||
| Notifications POST but nothing ingests | `client_state` matches what you registered the subscription with. Re-run `openssl rand -hex 32` and create a new subscription if the value drifted. Check `accepted_resources` includes the resource path Graph is sending. |
|
||||
| Every notification 403s | `clientState` mismatch (forged, or subscription registered with a different value). Re-create the subscription with `hermes teams-pipeline subscribe --client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE" ...` (ships with the pipeline runtime PR). |
|
||||
| Listener refuses to start on `0.0.0.0` | Set `allowed_source_cidrs` to Microsoft's current webhook egress ranges, or bind Hermes to `127.0.0.1` / `::1` behind your tunnel or reverse proxy. |
|
||||
| Listener starts but `curl http://localhost:8646/health` hangs | Port binding collision. Check `ss -tlnp \| grep 8646` and change `port:` if needed. |
|
||||
| Real Graph requests from Microsoft get 403'd | Source IP allowlist is too narrow. Remove `allowed_source_cidrs` temporarily, confirm traffic flows, then widen the list to include the current Microsoft egress ranges. |
|
||||
| Real Graph requests from Microsoft get 403'd | Source IP allowlist is too narrow. Widen the list to include the current Microsoft egress ranges. If you're still validating the tunnel path, bind Hermes to loopback and let the tunnel handle public exposure. |
|
||||
|
||||
## Related Docs
|
||||
|
||||
|
||||
@@ -4,6 +4,8 @@
|
||||
|
||||
ntfy makes a great lightweight push channel for Hermes: subscribe to a topic from the [ntfy mobile app](https://ntfy.sh/docs/subscribe/phone/), send messages to the topic to talk to the agent, get the response back on your phone.
|
||||
|
||||
> Run `hermes gateway setup` and pick **ntfy** for a guided walk-through.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A topic name (any unique string — `hermes-myname-2026` works fine)
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
[SimpleX Chat](https://simplex.chat/) is a private, decentralised messaging platform where users own their contacts and groups. Unlike other platforms, SimpleX assigns no persistent user IDs — every contact is identified by an opaque internal ID generated at connection time, which makes it one of the most private messengers available.
|
||||
|
||||
> Run `hermes gateway setup` and pick **SimpleX** for a guided walk-through.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- The **simplex-chat** CLI installed and running as a daemon
|
||||
@@ -13,7 +15,7 @@ Download the latest release from the [simplex-chat GitHub releases](https://gith
|
||||
|
||||
```bash
|
||||
# Linux / macOS binary
|
||||
curl -L https://github.com/simplex-chat/simplex-chat/releases/latest/download/simplex-chat-ubuntu-22_04-x86-64 -o simplex-chat
|
||||
curl -L https://github.com/simplex-chat/simplex-chat/releases/latest/download/simplex-chat-ubuntu-22_04-x86_64 -o simplex-chat
|
||||
chmod +x simplex-chat
|
||||
```
|
||||
|
||||
|
||||
@@ -8,6 +8,10 @@ description: "Set up the Microsoft Teams meeting summary pipeline with Microsoft
|
||||
|
||||
Use the Teams meeting pipeline when you want Hermes to ingest Microsoft Graph meeting events, fetch transcripts first, fall back to recordings plus STT when needed, and deliver a structured summary to downstream sinks.
|
||||
|
||||
Prerequisites: see [Microsoft Teams](./teams.md) for the underlying bot/credential setup.
|
||||
|
||||
> Run `hermes gateway setup` and pick **Teams Meetings** for a guided walk-through.
|
||||
|
||||
This page focuses on setup and enablement:
|
||||
- Graph credentials
|
||||
- webhook listener configuration
|
||||
@@ -65,6 +69,7 @@ The webhook listener is a gateway platform named `msgraph_webhook`. At minimum,
|
||||
|
||||
```bash
|
||||
MSGRAPH_WEBHOOK_ENABLED=true
|
||||
MSGRAPH_WEBHOOK_HOST=127.0.0.1
|
||||
MSGRAPH_WEBHOOK_PORT=8646
|
||||
MSGRAPH_WEBHOOK_CLIENT_STATE=<random-shared-secret>
|
||||
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings
|
||||
@@ -91,6 +96,7 @@ platforms:
|
||||
msgraph_webhook:
|
||||
enabled: true
|
||||
extra:
|
||||
host: 127.0.0.1
|
||||
port: 8646
|
||||
client_state: "replace-me"
|
||||
accepted_resources:
|
||||
@@ -120,6 +126,8 @@ platforms:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
If you bind the listener to a non-loopback host such as `0.0.0.0`, you must also set `allowed_source_cidrs` to Microsoft's webhook egress ranges. Loopback binds (`127.0.0.1` / `::1`) are the intended dev-tunnel and local reverse-proxy setup.
|
||||
|
||||
## Teams Delivery Modes
|
||||
|
||||
The pipeline supports two Teams summary-delivery modes inside the existing Teams plugin.
|
||||
|
||||
@@ -10,6 +10,8 @@ Connect Hermes Agent to Microsoft Teams as a bot. Unlike Slack's Socket Mode, Te
|
||||
|
||||
Need meeting summaries from Microsoft Graph events rather than normal bot conversations? Use the dedicated setup page: [Teams Meetings](/user-guide/messaging/teams-meetings).
|
||||
|
||||
> Run `hermes gateway setup` and pick **Microsoft Teams** for a guided walk-through.
|
||||
|
||||
## How the Bot Responds
|
||||
|
||||
| Context | Behavior |
|
||||
|
||||
@@ -319,7 +319,7 @@ With STT disabled, the gateway still downloads the voice/audio attachment into H
|
||||
|
||||
Your tools or skills can then read that path directly (e.g., hand it off to a local diarization pipeline, a richer transcription model, or upload it to long-term storage). The file extension reflects the original format Telegram delivered (`.ogg` for voice notes, `.mp3`/`.m4a`/etc. for audio attachments).
|
||||
|
||||
This pairs naturally with the [local Bot API server](#large-files-20mb--via-local-bot-api-server) section below, which lifts Telegram's 20MB getFile ceiling to 2GB — useful when the recordings you want to process are longer than a couple of minutes.
|
||||
This pairs naturally with the [local Bot API server](#large-files-20mb-via-local-bot-api-server) section below, which lifts Telegram's 20MB getFile ceiling to 2GB — useful when the recordings you want to process are longer than a couple of minutes.
|
||||
|
||||
### Outgoing Voice (Text-to-Speech)
|
||||
|
||||
@@ -1233,6 +1233,14 @@ HERMES_TELEGRAM_NOTIFICATIONS=all
|
||||
|
||||
Unknown values log a warning and fall back to `important`.
|
||||
|
||||
## Status messages edited in place
|
||||
|
||||
The Telegram adapter routes recurring agent status callbacks (e.g. "Compressing context…", "Calling tool…") through `send_or_update_status()`, which keeps a `{(chat_id, status_key) → message_id}` cache and **edits the existing bubble** on subsequent emits instead of appending a new one each time. Distinct `status_key` values get their own messages; distinct chats never collide. If the edit fails (e.g. the user deleted the message, or it's older than Telegram allows for edits), the cache entry is dropped and the next emit posts a fresh message and re-caches its ID. No config required — this is the default Telegram behavior. Other adapters that don't implement `send_or_update_status` fall through to plain `send()` unchanged.
|
||||
|
||||
## Pin incoming user message during agent turn
|
||||
|
||||
When a user sends a message that triggers an agent turn, the Telegram adapter pins that incoming message for the duration of the turn and unpins it when the response is finished — a lightweight visual indicator that the bot is actively working on the message rather than ignoring it. The pin uses `disable_notification=true` to avoid extra pings. No config required.
|
||||
|
||||
## Security
|
||||
|
||||
:::warning
|
||||
|
||||
@@ -12,6 +12,10 @@ Hermes supports two WeCom integration modes:
|
||||
- **WeCom Callback** (this page) — self-built app, receives encrypted XML callbacks. Shows as a first-class app in users' WeCom sidebar. Supports multi-corp routing.
|
||||
:::
|
||||
|
||||
See also: [WeCom Bot](./wecom.md) for the bot-style integration.
|
||||
|
||||
> Run `hermes gateway setup` and pick **WeCom Callback** for a guided walk-through.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. You register a self-built application in the WeCom Admin Console
|
||||
@@ -147,3 +151,28 @@ The crypto implementation is compatible with Tencent's official WXBizMsgCrypt SD
|
||||
- **No typing indicators** — the callback model doesn't support typing status
|
||||
- **Text only** — currently supports text messages for input; image/file/voice input not yet implemented. The agent is aware of outbound media capabilities via the WeCom platform hint (images, documents, video, voice).
|
||||
- **Response latency** — agent sessions take 3–30 minutes; users see the reply when processing completes
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Signature verification failing.**
|
||||
WeCom signs every request with the **Token** you registered in the admin
|
||||
console. A mismatch between the token configured in Hermes and the token the
|
||||
admin console expects is the most common cause. Re-copy both the **Token** and
|
||||
**EncodingAESKey** from the admin console — they're easy to truncate. Whitespace
|
||||
in `~/.hermes/.env` values around `=` will also break signature checks. After
|
||||
fixing, restart `hermes gateway run`.
|
||||
|
||||
**Callback URL not reachable / verification step fails.**
|
||||
WeCom hits the public URL you registered. Confirm:
|
||||
1. Your reverse proxy / tunnel forwards `/wecom/callback` to the gateway's port.
|
||||
2. The URL in the admin console is HTTPS (WeCom rejects plain HTTP).
|
||||
3. From outside your network, `curl -i https://<your-domain>/wecom/callback`
|
||||
returns something other than a timeout (a 4xx without query params is fine —
|
||||
it just means the listener is reachable).
|
||||
|
||||
**Port not reachable / listener not bound.**
|
||||
Check `hermes gateway run` logs for the bound host/port. If the adapter bound to
|
||||
`127.0.0.1` you must front it with a reverse proxy or tunnel — WeCom's servers
|
||||
can't reach loopback. Set `extra.host: 0.0.0.0` in `config.yaml` (plus
|
||||
`allowed_source_cidrs` if exposing directly) or keep loopback and use a tunnel
|
||||
such as Cloudflare Tunnel / nginx.
|
||||
|
||||
@@ -8,6 +8,8 @@ description: "Connect Hermes Agent to WeCom via the AI Bot WebSocket gateway"
|
||||
|
||||
Connect Hermes to [WeCom](https://work.weixin.qq.com/) (企业微信), Tencent's enterprise messaging platform. The adapter uses WeCom's AI Bot WebSocket gateway for real-time bidirectional communication — no public endpoint or webhook needed.
|
||||
|
||||
See also: [WeCom Callback](./wecom-callback.md) for inbound webhook setup.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A WeCom organization account
|
||||
|
||||
@@ -142,6 +142,25 @@ WEIXIN_DM_POLICY=allowlist
|
||||
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2
|
||||
```
|
||||
|
||||
`WEIXIN_ALLOWED_USERS` is an **inbound filter**, not an invitation system. QR
|
||||
login connects one iLink bot identity to Hermes. Other people do not scan the
|
||||
Hermes QR code with their own accounts; they must message the connected iLink
|
||||
bot/contact through WeChat, and Hermes will process the DM only if the sender's
|
||||
Weixin user ID is present in `WEIXIN_ALLOWED_USERS`.
|
||||
|
||||
A practical setup flow is:
|
||||
|
||||
1. Pair Hermes once with `hermes gateway setup` and note the connected iLink bot
|
||||
account.
|
||||
2. Have each allowed user send a direct message to that bot/contact.
|
||||
3. Read the sender/user ID from the gateway logs or the inbound event payload.
|
||||
4. Add those IDs to `WEIXIN_ALLOWED_USERS`, then restart the gateway.
|
||||
|
||||
If only the account that scanned the QR code can talk to Hermes, verify that the
|
||||
other users are messaging the iLink bot identity itself, not the personal WeChat
|
||||
account that performed the QR login. The iLink bot is a separate identity, and
|
||||
ordinary WeChat contact/group routing can be limited by Tencent's iLink behavior.
|
||||
|
||||
### Group Policy
|
||||
|
||||
Controls which groups the bot responds in **when iLink delivers group events for the connected identity**. For QR-login iLink bot identities (e.g. `...@im.bot`), group events are typically not delivered at all, so this policy may have no effect — see the iLink bot limitation warning at the top of the page.
|
||||
|
||||
@@ -8,6 +8,8 @@ description: "Set up Hermes Agent as a WhatsApp bot via the built-in Baileys bri
|
||||
|
||||
Hermes connects to WhatsApp through a built-in bridge based on **Baileys**. This works by emulating a WhatsApp Web session — **not** through the official WhatsApp Business API. No Meta developer account or Business verification is required.
|
||||
|
||||
> Run `hermes gateway setup` and pick **WhatsApp** for a guided walk-through.
|
||||
|
||||
:::warning Unofficial API — Ban Risk
|
||||
WhatsApp does **not** officially support third-party bots outside the Business API. Using a third-party bridge carries a small risk of account restrictions. To minimize risk:
|
||||
- **Use a dedicated phone number** for the bot (not your personal number)
|
||||
|
||||
@@ -0,0 +1,332 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Running Many Gateways at Once
|
||||
|
||||
Operate multiple [profiles](./profiles.md) — each with its own bot tokens,
|
||||
sessions, and memory — as managed services on a single machine. This page
|
||||
covers the operational concerns: starting them all together, viewing logs
|
||||
across profiles, preventing the host from sleeping, and recovering from common
|
||||
launchd/systemd quirks.
|
||||
|
||||
If you only run one Hermes agent, you don't need this page — see
|
||||
[Profiles](./profiles.md) for the basics.
|
||||
|
||||
## When to use this
|
||||
|
||||
You want this setup when you have two or more Hermes agents that should all
|
||||
be online at the same time. Common reasons:
|
||||
|
||||
- A personal assistant on one Telegram bot and a coding agent on another
|
||||
- One agent per family member or one per Slack workspace
|
||||
- Sandbox + production instances of the same configuration
|
||||
- A research agent + a writing agent + a cron-driven bot — each with isolated
|
||||
memory and skills
|
||||
|
||||
Every profile already gets its own per-platform LaunchAgent
|
||||
(`ai.hermes.gateway-<name>.plist`) or systemd user service
|
||||
(`hermes-gateway-<name>.service`). This guide adds the patterns for managing
|
||||
them collectively.
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
# Create profiles (once)
|
||||
hermes profile create coder
|
||||
hermes profile create personal-bot
|
||||
hermes profile create research
|
||||
|
||||
# Configure each
|
||||
coder setup
|
||||
personal-bot setup
|
||||
research setup
|
||||
|
||||
# Install each gateway as a managed service
|
||||
coder gateway install
|
||||
personal-bot gateway install
|
||||
research gateway install
|
||||
|
||||
# Start them all
|
||||
coder gateway start
|
||||
personal-bot gateway start
|
||||
research gateway start
|
||||
```
|
||||
|
||||
That's it — three independent agents, each on its own process, restarting
|
||||
automatically on crash and on user login.
|
||||
|
||||
## Start, stop, or restart all gateways at once
|
||||
|
||||
The CLI ships with single-profile lifecycle commands. To act across every
|
||||
profile, wrap them in a shell loop. Put the snippet below in
|
||||
`~/.local/bin/hermes-gateways` and `chmod +x` it:
|
||||
|
||||
```sh
|
||||
#!/bin/sh
|
||||
set -eu
|
||||
|
||||
# Add or remove profile names here as you create / delete profiles.
|
||||
profiles="default coder personal-bot research"
|
||||
|
||||
usage() {
|
||||
echo "Usage: hermes-gateways {start|stop|restart|status|list}"
|
||||
}
|
||||
|
||||
run_for_profile() {
|
||||
profile="$1"
|
||||
action="$2"
|
||||
if [ "$profile" = "default" ]; then
|
||||
hermes gateway "$action"
|
||||
else
|
||||
hermes -p "$profile" gateway "$action"
|
||||
fi
|
||||
}
|
||||
|
||||
action="${1:-}"
|
||||
case "$action" in
|
||||
start|stop|restart|status)
|
||||
for profile in $profiles; do
|
||||
echo "==> $action $profile"
|
||||
run_for_profile "$profile" "$action"
|
||||
done
|
||||
;;
|
||||
list)
|
||||
hermes gateway list
|
||||
;;
|
||||
*)
|
||||
usage
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
hermes-gateways start # start every configured profile
|
||||
hermes-gateways stop # stop every configured profile
|
||||
hermes-gateways restart # restart all
|
||||
hermes-gateways status # status across all
|
||||
hermes-gateways list # delegates to `hermes gateway list`
|
||||
```
|
||||
|
||||
:::tip
|
||||
The `default` profile is targeted with `hermes gateway <action>` (no `-p`),
|
||||
not `hermes -p default gateway <action>`. The wrapper above handles both forms.
|
||||
:::
|
||||
|
||||
## Manage one profile
|
||||
|
||||
The shortcut commands every profile installs:
|
||||
|
||||
```bash
|
||||
coder gateway run # foreground (Ctrl-C to stop)
|
||||
coder gateway start # start the managed service
|
||||
coder gateway stop # stop the managed service
|
||||
coder gateway restart # restart
|
||||
coder gateway status # status
|
||||
coder gateway install # create the LaunchAgent / systemd unit
|
||||
coder gateway uninstall # remove the service file
|
||||
```
|
||||
|
||||
These are equivalent to `hermes -p coder gateway <action>` — useful if a
|
||||
profile alias is not on `PATH` or if you target profiles dynamically from a
|
||||
script.
|
||||
|
||||
## Service files
|
||||
|
||||
Each profile installs its own service with a unique name, so installations
|
||||
never clash:
|
||||
|
||||
| Platform | Path |
|
||||
| -------- | ----------------------------------------------------------------- |
|
||||
| macOS | `~/Library/LaunchAgents/ai.hermes.gateway-<profile>.plist` |
|
||||
| Linux | `~/.config/systemd/user/hermes-gateway-<profile>.service` |
|
||||
|
||||
The default profile keeps the historical names: `ai.hermes.gateway.plist` /
|
||||
`hermes-gateway.service`.
|
||||
|
||||
## Viewing logs
|
||||
|
||||
Each profile writes to its own log files:
|
||||
|
||||
```bash
|
||||
# Default profile
|
||||
tail -f ~/.hermes/logs/gateway.log
|
||||
tail -f ~/.hermes/logs/gateway.error.log
|
||||
|
||||
# Named profile
|
||||
tail -f ~/.hermes/profiles/<name>/logs/gateway.log
|
||||
tail -f ~/.hermes/profiles/<name>/logs/gateway.error.log
|
||||
```
|
||||
|
||||
Stream every profile's log simultaneously:
|
||||
|
||||
```bash
|
||||
tail -f ~/.hermes/logs/gateway.log ~/.hermes/profiles/*/logs/gateway.log
|
||||
```
|
||||
|
||||
The CLI also has a structured log viewer:
|
||||
|
||||
```bash
|
||||
hermes logs --tail # follow default profile
|
||||
hermes -p coder logs --tail # follow one profile
|
||||
hermes logs --help # filters, levels, JSON output
|
||||
```
|
||||
|
||||
## Identify what's actually running
|
||||
|
||||
```bash
|
||||
hermes profile list # profiles + model + gateway state
|
||||
hermes-gateways status # full status across every profile
|
||||
launchctl list | grep hermes # macOS — PIDs and labels
|
||||
systemctl --user list-units 'hermes-gateway-*' # Linux — units
|
||||
```
|
||||
|
||||
## Editing configuration
|
||||
|
||||
Every profile keeps its config inside its own directory:
|
||||
|
||||
```
|
||||
~/.hermes/profiles/<name>/
|
||||
├── .env # API keys, bot tokens (chmod 600)
|
||||
├── config.yaml # model, provider, toolsets, gateway settings
|
||||
└── SOUL.md # personality / system prompt
|
||||
```
|
||||
|
||||
The default profile uses `~/.hermes/` directly with the same three files.
|
||||
|
||||
Edit them with any editor or via the CLI:
|
||||
|
||||
```bash
|
||||
hermes config set model.model anthropic/claude-sonnet-4 # default profile
|
||||
coder config set model.model openai/gpt-5 # named profile
|
||||
```
|
||||
|
||||
After editing `.env` or `config.yaml`, restart the affected gateway:
|
||||
|
||||
```bash
|
||||
coder gateway restart
|
||||
# or, for everything:
|
||||
hermes-gateways restart
|
||||
```
|
||||
|
||||
## Keeping the host awake
|
||||
|
||||
The gateway process can run all day, but the operating system will still try
|
||||
to sleep when idle. Two patterns:
|
||||
|
||||
### macOS — `caffeinate`
|
||||
|
||||
`caffeinate` is built into macOS and prevents sleep while it runs. No install.
|
||||
|
||||
```bash
|
||||
caffeinate -dis # block display, idle, and system sleep
|
||||
caffeinate -dis -t 28800 # same, auto-exit after 8 hours
|
||||
caffeinate -i -w $(cat ~/.hermes/gateway.pid) & # awake while default gateway runs
|
||||
|
||||
# Persistent: run in background and forget
|
||||
nohup caffeinate -dis >/dev/null 2>&1 &
|
||||
disown
|
||||
|
||||
# Inspect / stop
|
||||
pmset -g assertions | grep -iE 'caffeinate|prevent|user is active'
|
||||
pkill caffeinate
|
||||
```
|
||||
|
||||
| Flag | Effect |
|
||||
| ------ | ------------------------------------------------- |
|
||||
| `-d` | block display sleep |
|
||||
| `-i` | block idle system sleep (default) |
|
||||
| `-m` | block disk sleep |
|
||||
| `-s` | block system sleep (AC-powered Macs only) |
|
||||
| `-u` | simulate user activity (prevents screen lock) |
|
||||
| `-t N` | auto-exit after `N` seconds |
|
||||
| `-w P` | exit when PID `P` exits |
|
||||
|
||||
:::warning Lid-close still sleeps the Mac
|
||||
`caffeinate` cannot override the hardware-driven lid-close sleep on MacBooks.
|
||||
For lid-closed operation, change your Energy Saver / Battery preferences or
|
||||
use a third-party tool.
|
||||
:::
|
||||
|
||||
### Linux — `systemd-inhibit` or `loginctl`
|
||||
|
||||
```bash
|
||||
# Inhibit suspend while a command runs
|
||||
systemd-inhibit --what=idle:sleep --who=hermes --why="gateways running" \
|
||||
sleep infinity &
|
||||
|
||||
# Allow user services to keep running after logout (recommended)
|
||||
sudo loginctl enable-linger "$USER"
|
||||
```
|
||||
|
||||
After enabling lingering, your systemd user units (including
|
||||
`hermes-gateway-<profile>.service`) continue running across SSH disconnects
|
||||
and reboots.
|
||||
|
||||
## Token-conflict safety
|
||||
|
||||
Each profile must use unique bot tokens for each platform. If two profiles
|
||||
share a Telegram, Discord, Slack, WhatsApp, or Signal token, the second
|
||||
gateway refuses to start with an error naming the conflicting profile.
|
||||
|
||||
To audit:
|
||||
|
||||
```bash
|
||||
grep -H 'TELEGRAM_BOT_TOKEN\|DISCORD_BOT_TOKEN' \
|
||||
~/.hermes/.env ~/.hermes/profiles/*/.env
|
||||
```
|
||||
|
||||
## Updating the code
|
||||
|
||||
`hermes update` pulls the latest code once and syncs new bundled skills into
|
||||
every profile:
|
||||
|
||||
```bash
|
||||
hermes update
|
||||
hermes-gateways restart
|
||||
```
|
||||
|
||||
User-modified skills are never overwritten.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Could not find service in domain for user gui: 501"
|
||||
|
||||
You ran `hermes gateway start` after a previous `hermes gateway stop`. The
|
||||
CLI's `stop` does a full `launchctl unload`, which removes the service from
|
||||
launchd's registry. The CLI catches this specific error on `start` and
|
||||
automatically re-loads the plist (`↻ launchd job was unloaded; reloading
|
||||
service definition`). The service starts normally. Nothing to fix.
|
||||
|
||||
### Stale PID after a crash
|
||||
|
||||
If a profile's gateway shows `not running` but a process is still alive:
|
||||
|
||||
```bash
|
||||
ps -ef | grep "hermes_cli.*-p <profile>"
|
||||
cat ~/.hermes/profiles/<profile>/gateway.pid
|
||||
kill -TERM <pid> # graceful
|
||||
kill -KILL <pid> # if that fails after a few seconds
|
||||
<profile> gateway start
|
||||
```
|
||||
|
||||
### Forcing a hard reset of one service
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
launchctl unload ~/Library/LaunchAgents/ai.hermes.gateway-<profile>.plist
|
||||
launchctl load ~/Library/LaunchAgents/ai.hermes.gateway-<profile>.plist
|
||||
|
||||
# Linux
|
||||
systemctl --user restart hermes-gateway-<profile>.service
|
||||
```
|
||||
|
||||
### Health check
|
||||
|
||||
```bash
|
||||
hermes doctor # default profile
|
||||
hermes -p <profile> doctor # one profile
|
||||
```
|
||||
@@ -24,6 +24,10 @@ That's it. `coder` is now its own Hermes profile with its own config, memory, an
|
||||
|
||||
## Creating a profile
|
||||
|
||||
:::tip
|
||||
Quickest setup: run `hermes setup --portal` inside the new profile to wire up models + tools at once. See [Nous Portal](/integrations/nous-portal).
|
||||
:::
|
||||
|
||||
### Blank profile
|
||||
|
||||
```bash
|
||||
|
||||
@@ -30,10 +30,23 @@ The approval system supports three modes, configured via `approvals.mode` in `~/
|
||||
|
||||
```yaml
|
||||
approvals:
|
||||
mode: manual # manual | smart | off
|
||||
timeout: 60 # seconds to wait for user response (default: 60)
|
||||
mode: manual # manual | smart | off
|
||||
timeout: 60 # seconds to wait for user response (default: 60)
|
||||
cron_mode: deny # deny | approve — what cron jobs do when they hit a dangerous command
|
||||
mcp_reload_confirm: true # /reload-mcp asks before invalidating the MCP tool cache
|
||||
destructive_slash_confirm: true # /clear, /new, /reset, /undo prompt before discarding state
|
||||
```
|
||||
|
||||
The full set of keys:
|
||||
|
||||
| Key | Default | What it controls |
|
||||
|---|---|---|
|
||||
| `mode` | `manual` | Approval policy for dangerous shell commands — see the table below. |
|
||||
| `timeout` | `60` | Seconds Hermes waits for an approval reply before timing out. |
|
||||
| `cron_mode` | `deny` | How [cron jobs](./features/cron.md) behave headlessly when they trigger a dangerous-command prompt. `deny` blocks the command (the agent must find another path); `approve` auto-approves everything in cron context. |
|
||||
| `mcp_reload_confirm` | `true` | When true, `/reload-mcp` asks before rebuilding the MCP tool set. Rebuilding invalidates the provider prompt cache (tool schemas live in the system prompt), so the next message re-sends full input tokens. Users who click **Always Approve** flip this key to `false`. |
|
||||
| `destructive_slash_confirm` | `true` | When true, destructive session slash commands (`/clear`, `/new`, `/reset`, `/undo`) prompt before discarding conversation state. Three-option dialog (Approve Once / Always Approve / Cancel) routed through native yes/no buttons on Telegram, Discord, and Slack; text fallback elsewhere. Users who click **Always Approve** flip this key to `false`. TUI uses its own modal overlay (set `HERMES_TUI_NO_CONFIRM=1` to opt out there). |
|
||||
|
||||
| Mode | Behavior |
|
||||
|------|----------|
|
||||
| **manual** (default) | Always prompt the user for approval on dangerous commands |
|
||||
@@ -73,7 +86,7 @@ When YOLO is active, Hermes shows two persistent visual reminders so it's hard t
|
||||
YOLO mode disables **all** dangerous command safety checks for the session — **except** the hardline blocklist (see below). Use only when you fully trust the commands being generated (e.g., well-tested automation scripts in disposable environments).
|
||||
:::
|
||||
|
||||
For destructive session slash commands (`/clear`, `/new` / `/reset`, `/undo`, `/exit --delete`), the CLI also prompts for confirmation before running them. See [Slash Commands — Confirmation prompts for destructive commands](../reference/slash-commands.md#confirmation-prompts-for-destructive-commands).
|
||||
For destructive session slash commands (`/clear`, `/new` / `/reset`, `/undo`, `/quit --delete` — `/exit --delete` is an alias), the CLI also prompts for confirmation before running them. See [Slash Commands — Confirmation prompts for destructive commands](../reference/slash-commands.md#confirmation-prompts-for-destructive-commands).
|
||||
|
||||
### Hardline Blocklist (Always-On Floor)
|
||||
|
||||
@@ -422,7 +435,7 @@ terminal:
|
||||
- my_custom_oauth_token.json
|
||||
```
|
||||
|
||||
Paths are relative to `~/.hermes/`. Files are mounted to `/root/.hermes/` inside the container.
|
||||
Paths are relative to `~/.hermes/`. Files are mounted to `/root/.hermes/` inside the container. This list is read by `tools/credential_files.py` (`terminal.credential_files`) — it lives under the `terminal:` block but is loaded by the credential-files module, not the core terminal backend, so it isn't part of the bundled `DEFAULT_CONFIG` snapshot.
|
||||
|
||||
### What Each Sandbox Filters
|
||||
|
||||
@@ -573,7 +586,7 @@ Blocked files show a warning:
|
||||
4. **Store secrets securely** — keep API keys in `~/.hermes/.env` with proper file permissions
|
||||
5. **Enable DM pairing** — use pairing codes instead of hardcoding user IDs when possible
|
||||
6. **Review command allowlist** — periodically audit `command_allowlist` in config.yaml
|
||||
7. **Set `MESSAGING_CWD`** — don't let the agent operate from sensitive directories
|
||||
7. **Set `terminal.cwd`** — don't let the agent operate from sensitive directories
|
||||
8. **Run as non-root** — never run the gateway as root
|
||||
9. **Monitor logs** — check `~/.hermes/logs/` for unauthorized access attempts
|
||||
10. **Keep updated** — run `hermes update` regularly for security patches
|
||||
|
||||
@@ -4,6 +4,8 @@ title: "Sessions"
|
||||
description: "Session persistence, resume, search, management, and per-platform session tracking"
|
||||
---
|
||||
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl';
|
||||
|
||||
# Sessions
|
||||
|
||||
Hermes Agent automatically saves every conversation as a session. Sessions enable conversation resume, cross-session search, and full conversation history management.
|
||||
@@ -144,7 +146,7 @@ Session IDs are shown when you exit a CLI session, and can be found with `hermes
|
||||
|
||||
When you resume a session, Hermes displays a compact recap of the previous conversation in a styled panel before the input prompt:
|
||||
|
||||
<img className="docs-terminal-figure" src="/img/docs/session-recap.svg" alt="Stylized preview of the Previous Conversation recap panel shown when resuming a Hermes session." />
|
||||
<img className="docs-terminal-figure" src={useBaseUrl('/img/docs/session-recap.svg')} alt="Stylized preview of the Previous Conversation recap panel shown when resuming a Hermes session." />
|
||||
<p className="docs-figure-caption">Resume mode shows a compact recap panel with recent user and assistant turns before returning you to the live prompt.</p>
|
||||
|
||||
The recap:
|
||||
|
||||
@@ -21,7 +21,7 @@ Manage Apple Notes via memo CLI: create, search, edit.
|
||||
| License | MIT |
|
||||
| Platforms | macos |
|
||||
| Tags | `Notes`, `Apple`, `macOS`, `note-taking` |
|
||||
| Related skills | [`obsidian`](/user-guide/skills/bundled/note-taking/note-taking-obsidian) |
|
||||
| Related skills | [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -84,6 +84,38 @@ remindctl add --title "Call mom" --list Personal --due tomorrow
|
||||
remindctl add --title "Meeting prep" --due "2026-02-15 09:00"
|
||||
```
|
||||
|
||||
### Due Time vs Alarm / Early Nudge
|
||||
|
||||
`--due` and `--alarm` are different fields:
|
||||
|
||||
- `--due` sets the reminder's due date/time.
|
||||
- `--alarm` sets the EventKit alarm/notification trigger. Timed due reminders may default to an alarm at the due time, but pass `--alarm` explicitly when the user asks for an earlier nudge.
|
||||
|
||||
For a reminder due at 2:00 PM with a notification 30 minutes earlier:
|
||||
|
||||
```bash
|
||||
remindctl add --title "Hairdresser" --due "2026-05-15 14:00" --alarm "2026-05-15 13:30"
|
||||
```
|
||||
|
||||
To edit an existing reminder:
|
||||
|
||||
```bash
|
||||
remindctl edit 87354 --due "2026-05-15 14:00" --alarm "2026-05-15 13:30"
|
||||
```
|
||||
|
||||
The Reminders UI may show or group the item by the alarm time because that is when the notification fires. Verify with JSON instead of assuming the due time moved:
|
||||
|
||||
```bash
|
||||
remindctl today --json
|
||||
```
|
||||
|
||||
Expected shape:
|
||||
|
||||
- `dueDate`: actual due time
|
||||
- `alarmDate`: notification / early nudge time
|
||||
|
||||
Apple's public `EKReminder` docs list only reminder-specific properties. Alarm support comes from inherited `EKCalendarItem` behavior exposed by remindctl's `--alarm` flag.
|
||||
|
||||
### Complete / Delete
|
||||
|
||||
```bash
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ Delegate coding to Claude Code CLI (features, PRs).
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `Coding-Agent`, `Claude`, `Anthropic`, `Code-Review`, `Refactoring`, `PTY`, `Automation` |
|
||||
| Related skills | [`codex`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`opencode`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) |
|
||||
| Related skills | [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ Delegate coding to OpenAI Codex CLI (features, PRs).
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `Coding-Agent`, `Codex`, `OpenAI`, `Code-Review`, `Refactoring` |
|
||||
| Related skills | [`claude-code`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
|
||||
| Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+4
-4
@@ -463,15 +463,15 @@ Common "why is Hermes doing X to my output / tool calls / commands?" toggles —
|
||||
|
||||
### Secret redaction in tool output
|
||||
|
||||
Secret redaction is **off by default** — tool output (terminal stdout, `read_file`, web content, subagent summaries, etc.) passes through unmodified. If the user wants Hermes to auto-mask strings that look like API keys, tokens, and secrets before they enter the conversation context and logs:
|
||||
Secret redaction is **on by default** — tool output (terminal stdout, `read_file`, web content, subagent summaries, etc.) is scanned for strings that look like API keys, tokens, and secrets before it enters the conversation context and logs. Leave it enabled for normal use:
|
||||
|
||||
```bash
|
||||
hermes config set security.redact_secrets true # enable globally
|
||||
hermes config set security.redact_secrets true # keep enabled globally
|
||||
```
|
||||
|
||||
**Restart required.** `security.redact_secrets` is snapshotted at import time — toggling it mid-session (e.g. via `export HERMES_REDACT_SECRETS=true` from a tool call) will NOT take effect for the running process. Tell the user to run `hermes config set security.redact_secrets true` in a terminal, then start a new session. This is deliberate — it prevents an LLM from flipping the toggle on itself mid-task.
|
||||
**Restart required.** `security.redact_secrets` is snapshotted at import time — toggling it mid-session (e.g. via `export HERMES_REDACT_SECRETS=false` from a tool call) will NOT take effect for the running process. Tell the user to change it in config from a terminal, then start a new session. This is deliberate — it prevents an LLM from flipping the toggle on itself mid-task.
|
||||
|
||||
Disable again with:
|
||||
Disable only when you deliberately need raw credential-like strings for debugging or redactor development:
|
||||
```bash
|
||||
hermes config set security.redact_secrets false
|
||||
```
|
||||
|
||||
+295
@@ -0,0 +1,295 @@
|
||||
---
|
||||
title: "Kanban Codex Lane"
|
||||
sidebar_label: "Kanban Codex Lane"
|
||||
description: "Use when a Hermes Kanban worker wants to run Codex CLI as an isolated implementation lane while Hermes keeps ownership of task lifecycle, reconciliation, tes..."
|
||||
---
|
||||
|
||||
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
|
||||
|
||||
# Kanban Codex Lane
|
||||
|
||||
Use when a Hermes Kanban worker wants to run Codex CLI as an isolated implementation lane while Hermes keeps ownership of task lifecycle, reconciliation, testing, and handoff.
|
||||
|
||||
## Skill metadata
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Source | Bundled (installed by default) |
|
||||
| Path | `skills/autonomous-ai-agents/kanban-codex-lane` |
|
||||
| Version | `1.0.0` |
|
||||
| Author | Hermes Agent |
|
||||
| License | MIT |
|
||||
| Tags | `kanban`, `codex`, `worktrees`, `autonomous-agents`, `prediction-market-bot` |
|
||||
| Related skills | [`kanban-worker`](/docs/user-guide/skills/bundled/devops/devops-kanban-worker), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
:::info
|
||||
The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
|
||||
:::
|
||||
|
||||
# Kanban Codex Lane
|
||||
|
||||
## Overview
|
||||
|
||||
This skill defines the lightweight Hermes+Codex dual-lane convention for Kanban workers. Hermes is always the task owner: it calls `kanban_show`, decides whether Codex is appropriate, creates or selects an isolated workspace, starts and monitors Codex, reconciles any diff, runs verification, and writes the final `kanban_complete` or `kanban_block` handoff. Codex is an input lane only. Codex output is not a task completion signal, not a trusted reviewer, and not allowed to write durable Kanban state directly.
|
||||
|
||||
The convention exists so a Hermes worker can use Codex for bounded implementation help without changing the dispatcher. The dispatcher must still spawn Hermes workers. A worker may optionally spawn Codex inside its own run, then accept, partially accept, or reject the lane after independent review and tests.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use the Codex lane when all of these are true:
|
||||
|
||||
- The Kanban task is a coding, refactor, documentation, test, or mechanical migration task with clear acceptance criteria.
|
||||
- A bounded diff can be evaluated by Hermes in one run.
|
||||
- The repo can be copied or checked out in an isolated git worktree/branch.
|
||||
- Hermes can run the relevant tests itself after Codex exits.
|
||||
- The prompt can state all safety constraints and files that must not change.
|
||||
|
||||
Do not use the Codex lane when any of these are true:
|
||||
|
||||
- The task requires human judgment that is not already captured in the Kanban body.
|
||||
- The worker lacks repo access, Codex auth, or time to reconcile the result.
|
||||
- The change touches secrets, credential stores, private user data, or production order-entry systems.
|
||||
- A small direct edit is faster and safer than spawning another agent.
|
||||
- The task is research-only and should produce a written handoff rather than a diff.
|
||||
- The worker would be tempted to mark Done based only on Codex self-report.
|
||||
|
||||
## Ownership Rules
|
||||
|
||||
1. Hermes owns the Kanban lifecycle. Codex must never call `kanban_complete`, `kanban_block`, `kanban_create`, gateway messaging, or any Hermes board CLI as a substitute for the worker.
|
||||
2. Hermes owns final acceptance. Treat Codex commits/diffs as untrusted patches until reviewed and verified.
|
||||
3. Hermes owns test execution. Codex may run tests, but those runs are advisory; repeat required verification from Hermes with the repo's canonical wrapper.
|
||||
4. Hermes owns safety. If Codex changes safety boundaries, risk gates, live trading behavior, or secrets handling, reject the lane even if tests pass.
|
||||
5. Hermes owns cleanup. Kill stuck Codex processes and remove temporary worktrees when they are no longer needed.
|
||||
|
||||
## Required Worktree and Branch Pattern
|
||||
|
||||
Never run Codex directly in a shared dirty checkout. Use a branch/worktree name that ties the lane to the Kanban task and keeps untrusted edits isolated.
|
||||
|
||||
Recommended variables:
|
||||
|
||||
```bash
|
||||
TASK_ID="${HERMES_KANBAN_TASK:-t_manual}"
|
||||
REPO="/path/to/repo"
|
||||
BASE="$(git -C "$REPO" rev-parse --abbrev-ref HEAD)"
|
||||
SAFE_TASK="$(printf '%s' "$TASK_ID" | tr -cd '[:alnum:]_-')"
|
||||
BRANCH="codex/${SAFE_TASK}/$(date -u +%Y%m%d%H%M%S)"
|
||||
WORKTREE="/tmp/${SAFE_TASK}-codex-lane"
|
||||
```
|
||||
|
||||
Create the isolated lane:
|
||||
|
||||
```bash
|
||||
git -C "$REPO" fetch --all --prune
|
||||
git -C "$REPO" worktree add -b "$BRANCH" "$WORKTREE" "$BASE"
|
||||
git -C "$WORKTREE" status --short --branch
|
||||
```
|
||||
|
||||
If the current Kanban workspace is already an isolated git worktree created for this task, you may create a sibling Codex branch inside it only if `git status --short` is clean except for intentional Hermes edits. Otherwise create a separate temporary worktree and cherry-pick or copy accepted commits back after reconciliation.
|
||||
|
||||
Cleanup after reconciliation:
|
||||
|
||||
```bash
|
||||
git -C "$REPO" worktree remove "$WORKTREE"
|
||||
git -C "$REPO" branch -D "$BRANCH" # only after accepted commits were copied/cherry-picked or intentionally rejected
|
||||
```
|
||||
|
||||
Keep the worktree if it is needed as an artifact for review; record it in `codex_lane.artifacts` and mention it in the handoff.
|
||||
|
||||
## Codex Capability Checks
|
||||
|
||||
Run these before spawning Codex. Missing Codex is a normal reason to skip the lane, not a task blocker if Hermes can do the task directly.
|
||||
|
||||
```bash
|
||||
command -v codex
|
||||
codex --version
|
||||
codex features list | grep -i goals || true
|
||||
```
|
||||
|
||||
If `/goal` support is required, enable or launch with the feature flag only after checking availability:
|
||||
|
||||
```bash
|
||||
codex features enable goals || true
|
||||
codex --enable goals --version
|
||||
```
|
||||
|
||||
Authentication can be via `OPENAI_API_KEY` or the Codex CLI OAuth state (often `~/.codex/auth.json`). Do not print token files. A missing `OPENAI_API_KEY` is not proof that auth is unavailable.
|
||||
|
||||
## Mode Selection
|
||||
|
||||
Use `codex exec` for bounded one-shot edits where Codex should exit on its own:
|
||||
|
||||
```python
|
||||
terminal(
|
||||
command="codex exec --full-auto '$(cat /tmp/codex_prompt.md)'",
|
||||
workdir=WORKTREE,
|
||||
background=True,
|
||||
pty=True,
|
||||
notify_on_complete=True,
|
||||
)
|
||||
```
|
||||
|
||||
Use Codex `/goal` only for broader multi-step work that benefits from durable objective tracking. Launch interactively in a PTY/tmux session or with `codex --enable goals` if the feature is disabled by default. Keep the goal objective self-contained: repo path, task id, safety constraints, allowed scope, acceptance criteria, tests, and commit expectations.
|
||||
|
||||
Example `/goal` objective text to paste into Codex:
|
||||
|
||||
```text
|
||||
/goal Work in this repository only: <WORKTREE>. Task: <TASK_ID> <TITLE>.
|
||||
Hermes owns the Kanban lifecycle; do not call Hermes kanban tools or messaging.
|
||||
Create small commits on branch <BRANCH>. Follow the PMB safety constraints in the prompt.
|
||||
Run the requested verification commands and report exact outputs. Stop after producing a diff and summary.
|
||||
```
|
||||
|
||||
Do not use `--yolo` for prediction-market-bot or safety-sensitive repos. Prefer `--full-auto` inside the isolated worktree, then rely on Hermes reconciliation.
|
||||
|
||||
## Prompt Construction
|
||||
|
||||
Use the linked template at `templates/pmb-codex-lane-prompt.md` for prediction-market-bot work. For other repos, keep the same structure and replace the PMB-specific safety block with repo-specific invariants.
|
||||
|
||||
Every Codex prompt must include:
|
||||
|
||||
- `task_id`, title, and full Kanban acceptance criteria.
|
||||
- Repo path, worktree path, branch name, and allowed file scope.
|
||||
- Explicit statement: Hermes owns Kanban lifecycle; Codex is an input lane only.
|
||||
- Required output: concise summary, files changed, commits, tests run, and known risks.
|
||||
- Prohibited actions: secrets access, external messaging, board mutation, unrelated refactors, dependency upgrades unless required.
|
||||
- Verification commands Codex may run and commands Hermes will run afterward.
|
||||
|
||||
For PMB, include these mandatory safety constraints verbatim:
|
||||
|
||||
```text
|
||||
PMB safety constraints:
|
||||
- live-SIM is paper-only; do not add or enable live REST order entry.
|
||||
- Never use market orders.
|
||||
- Do not add execution crossing or bypass price/risk checks.
|
||||
- Do not fake passive fills, fills, PnL, order states, or reconciliation evidence.
|
||||
- Do not weaken risk gates, limits, kill switches, or fail-closed behavior.
|
||||
- Keep research/selection outside the C++ hot path unless explicitly requested.
|
||||
- Do not read, print, write, or require secrets/tokens/credentials.
|
||||
```
|
||||
|
||||
## Monitoring, Timeout, and Kill Behavior
|
||||
|
||||
Start long Codex lanes in the background with PTY and completion notification:
|
||||
|
||||
```python
|
||||
result = terminal(
|
||||
command="codex exec --full-auto '$(cat /tmp/codex_prompt.md)'",
|
||||
workdir=WORKTREE,
|
||||
background=True,
|
||||
pty=True,
|
||||
notify_on_complete=True,
|
||||
)
|
||||
session_id = result["session_id"]
|
||||
```
|
||||
|
||||
Monitor without interfering:
|
||||
|
||||
```python
|
||||
process(action="poll", session_id=session_id)
|
||||
process(action="log", session_id=session_id, limit=200)
|
||||
process(action="wait", session_id=session_id, timeout=300)
|
||||
```
|
||||
|
||||
Send a Kanban heartbeat every few minutes for lanes longer than two minutes, e.g. `kanban_heartbeat(note="Codex lane running in <WORKTREE>; waiting for tests/diff")`.
|
||||
|
||||
Kill conditions:
|
||||
|
||||
- No useful output for the task's remaining runtime budget.
|
||||
- Codex requests secrets, production credentials, or external permissions.
|
||||
- Codex attempts to modify files outside the worktree.
|
||||
- Codex starts unrelated rewrites or dependency churn.
|
||||
- Codex is still running near the worker timeout and no safe partial artifact exists.
|
||||
|
||||
Kill command:
|
||||
|
||||
```python
|
||||
process(action="kill", session_id=session_id)
|
||||
```
|
||||
|
||||
After kill, inspect `git status --short`, preserve useful patches only if safe, and record `codex_lane.result: timed_out` or `rejected` with a concrete `rejected_reason`.
|
||||
|
||||
## Reconciliation Checklist
|
||||
|
||||
Hermes must perform this checklist before accepting any Codex lane result:
|
||||
|
||||
- [ ] `git -C <WORKTREE> status --short --branch` shows only expected files.
|
||||
- [ ] `git -C <WORKTREE> diff --stat` and `git diff` were reviewed by Hermes.
|
||||
- [ ] No secrets, credentials, generated caches, unrelated data, or local artifacts are included.
|
||||
- [ ] PMB safety constraints were preserved: no live REST order entry, no market orders, no execution crossing, no fake passive fills/PnL, no risk-gate weakening, no secrets.
|
||||
- [ ] Codex commits are small enough to cherry-pick or squash cleanly.
|
||||
- [ ] Hermes ran the canonical tests itself, using `scripts/run_tests.sh` for Hermes Agent or the repo's documented wrapper for other repos.
|
||||
- [ ] Any Codex-run tests are listed separately from Hermes-run tests.
|
||||
- [ ] Accepted commits/diffs were applied to the Hermes-owned workspace/branch.
|
||||
- [ ] Rejected or partial work has a concrete reason and artifact path if useful.
|
||||
|
||||
Acceptance outcomes:
|
||||
|
||||
- `accepted`: Codex diff/commits were reviewed, applied, and verified.
|
||||
- `partial`: Some Codex work was accepted after edits or cherry-picks; rejected parts are documented.
|
||||
- `rejected`: No Codex changes were accepted; reason is documented.
|
||||
- `timed_out`: Codex exceeded the lane budget; useful artifacts may or may not exist.
|
||||
|
||||
## kanban_complete Metadata Schema
|
||||
|
||||
Include this object under `metadata.codex_lane` for every task where the lane was considered. If Codex was not used, set `used: false` and explain why in `rejected_reason` or a sibling `notes` field.
|
||||
|
||||
```json
|
||||
{
|
||||
"codex_lane": {
|
||||
"used": true,
|
||||
"mode": "exec | goal | skipped",
|
||||
"worktree": "/absolute/path/to/codex/worktree",
|
||||
"branch": "codex/t_caa69668/20260508100000",
|
||||
"command": "codex exec --full-auto ...",
|
||||
"result": "accepted | rejected | partial | timed_out",
|
||||
"accepted_commits": ["<sha1>", "<sha2>"],
|
||||
"rejected_reason": "empty when fully accepted; otherwise concrete reason",
|
||||
"tests_run": [
|
||||
{"command": "scripts/run_tests.sh tests/tools/test_x.py", "exit_code": 0, "owner": "hermes"},
|
||||
{"command": "codex-reported: npm test", "exit_code": 0, "owner": "codex"}
|
||||
],
|
||||
"artifacts": ["/absolute/path/to/log-or-patch"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For tasks that intentionally skip Codex:
|
||||
|
||||
```json
|
||||
{
|
||||
"codex_lane": {
|
||||
"used": false,
|
||||
"mode": "skipped",
|
||||
"worktree": null,
|
||||
"branch": null,
|
||||
"command": null,
|
||||
"result": "rejected",
|
||||
"accepted_commits": [],
|
||||
"rejected_reason": "Direct Hermes edit was smaller and safer than spawning Codex.",
|
||||
"tests_run": [],
|
||||
"artifacts": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
1. Treating Codex self-report as verification. Always inspect the diff and rerun tests from Hermes.
|
||||
2. Running Codex in the user's dirty main checkout. Always isolate in a worktree/branch.
|
||||
3. Letting Codex own Kanban. Codex may summarize progress, but Hermes writes board state.
|
||||
4. Forgetting PMB safety invariants in the prompt. Missing safety text is a lane setup failure.
|
||||
5. Using `/goal` for quick edits. Prefer `codex exec` unless durable multi-step continuation is needed.
|
||||
6. Killing a stuck lane without recording why. `rejected_reason` must explain the decision.
|
||||
7. Accepting broad unrelated cleanup because tests pass. Reject or cherry-pick only the scoped changes.
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [ ] Codex was skipped or started only after `command -v codex`, `codex --version`, and optional goals feature checks.
|
||||
- [ ] Codex ran only in an isolated worktree/branch.
|
||||
- [ ] Prompt included task scope, ownership rules, PMB safety constraints when applicable, and verification commands.
|
||||
- [ ] Hermes reviewed `git diff` and safety-sensitive files.
|
||||
- [ ] Hermes ran canonical tests independently.
|
||||
- [ ] `kanban_complete.metadata.codex_lane` follows the schema above.
|
||||
- [ ] Temporary processes and unnecessary worktrees were cleaned up.
|
||||
+1
-1
@@ -21,7 +21,7 @@ Delegate coding to OpenCode CLI (features, PR review).
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `Coding-Agent`, `OpenCode`, `Autonomous`, `Refactoring`, `Code-Review` |
|
||||
| Related skills | [`claude-code`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
|
||||
| Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Dark-themed SVG architecture/cloud/infra diagrams as HTML.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `architecture`, `diagrams`, `SVG`, `HTML`, `visualization`, `infrastructure`, `cloud` |
|
||||
| Related skills | [`concept-diagrams`](/user-guide/skills/optional/creative/creative-concept-diagrams), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw) |
|
||||
| Related skills | [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ ASCII art: pyfiglet, cowsay, boxes, image-to-ascii.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `ASCII`, `Art`, `Banners`, `Creative`, `Unicode`, `Text-Art`, `pyfiglet`, `figlet`, `cowsay`, `boxes` |
|
||||
| Related skills | [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw) |
|
||||
| Related skills | [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Design one-off HTML artifacts (landing, deck, prototype).
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `design`, `html`, `prototype`, `ux`, `ui`, `creative`, `artifact`, `deck`, `motion`, `design-system` |
|
||||
| Related skills | [`design-md`](/user-guide/skills/bundled/creative/creative-design-md), [`popular-web-designs`](/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram) |
|
||||
| Related skills | [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Generate images, video, and audio with ComfyUI — install, launch, manage nodes
|
||||
| License | MIT |
|
||||
| Platforms | macos, linux, windows |
|
||||
| Tags | `comfyui`, `image-generation`, `stable-diffusion`, `flux`, `sd3`, `wan-video`, `hunyuan-video`, `creative`, `generative-ai`, `video-generation` |
|
||||
| Related skills | [`stable-diffusion-image-generation`](/user-guide/skills/optional/mlops/mlops-stable-diffusion), `image_gen` |
|
||||
| Related skills | [`stable-diffusion-image-generation`](/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion), `image_gen` |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Author/validate/export Google's DESIGN.md token spec files.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `design`, `design-system`, `tokens`, `ui`, `accessibility`, `wcag`, `tailwind`, `dtcg`, `google` |
|
||||
| Related skills | [`popular-web-designs`](/user-guide/skills/bundled/creative/creative-popular-web-designs), [`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram) |
|
||||
| Related skills | [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Humanize text: strip AI-isms and add real voice.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `writing`, `editing`, `humanize`, `anti-ai-slop`, `voice`, `prose`, `text` |
|
||||
| Related skills | [`songwriting-and-ai-music`](/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) |
|
||||
| Related skills | [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ p5.js sketches: gen art, shaders, interactive, 3D.
|
||||
| Version | `1.0.0` |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `creative-coding`, `generative-art`, `p5js`, `canvas`, `interactive`, `visualization`, `webgl`, `shaders`, `animation` |
|
||||
| Related skills | [`ascii-video`](/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/user-guide/skills/bundled/creative/creative-manim-video), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw) |
|
||||
| Related skills | [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Use when building creative browser demos with @chenglou/pretext — DOM-free tex
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `creative-coding`, `typography`, `pretext`, `ascii-art`, `canvas`, `generative`, `text-layout`, `kinetic-typography` |
|
||||
| Related skills | [`p5js`](/user-guide/skills/bundled/creative/creative-p5js), [`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram) |
|
||||
| Related skills | [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Throwaway HTML mockups: 2-3 design variants to compare.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `sketch`, `mockup`, `design`, `ui`, `prototype`, `html`, `variants`, `exploration`, `wireframe`, `comparison` |
|
||||
| Related skills | [`spike`](/user-guide/skills/bundled/software-development/software-development-spike), [`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design), [`popular-web-designs`](/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw) |
|
||||
| Related skills | [`spike`](/docs/user-guide/skills/bundled/software-development/software-development-spike), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Control a running TouchDesigner instance via twozero MCP — create operators, s
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `TouchDesigner`, `MCP`, `twozero`, `creative-coding`, `real-time-visuals`, `generative-art`, `audio-reactive`, `VJ`, `installation`, `GLSL` |
|
||||
| Related skills | [`native-mcp`](/user-guide/skills/bundled/mcp/mcp-native-mcp), [`ascii-video`](/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/user-guide/skills/bundled/creative/creative-manim-video), `hermes-video` |
|
||||
| Related skills | [`native-mcp`](/docs/user-guide/skills/bundled/mcp/mcp-native-mcp), [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), `hermes-video` |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ Decomposition playbook + anti-temptation rules for an orchestrator profile routi
|
||||
| Version | `3.0.0` |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `kanban`, `multi-agent`, `orchestration`, `routing` |
|
||||
| Related skills | [`kanban-worker`](/user-guide/skills/bundled/devops/devops-kanban-worker) |
|
||||
| Related skills | [`kanban-worker`](/docs/user-guide/skills/bundled/devops/devops-kanban-worker) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ Pitfalls, examples, and edge cases for Hermes Kanban workers. The lifecycle itse
|
||||
| Version | `2.0.0` |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `kanban`, `multi-agent`, `collaboration`, `workflow`, `pitfalls` |
|
||||
| Related skills | [`kanban-orchestrator`](/user-guide/skills/bundled/devops/devops-kanban-orchestrator) |
|
||||
| Related skills | [`kanban-orchestrator`](/docs/user-guide/skills/bundled/devops/devops-kanban-orchestrator) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
@@ -39,7 +39,7 @@ Your workspace kind determines how you should behave inside `$HERMES_KANBAN_WORK
|
||||
|---|---|---|
|
||||
| `scratch` | Fresh tmp dir, yours alone | Read/write freely; it gets GC'd when the task is archived. |
|
||||
| `dir:<path>` | Shared persistent directory | Other runs will read what you write. Treat it like long-lived state. Path is guaranteed absolute (the kernel rejects relative paths). |
|
||||
| `worktree` | Git worktree at the resolved path | If `.git` doesn't exist, run `git worktree add <path> <branch>` from the main repo first, then cd and work normally. Commit work here. |
|
||||
| `worktree` | Git worktree at the resolved path | If `.git` doesn't exist, run `git worktree add <path> ${HERMES_KANBAN_BRANCH:-wt/$HERMES_KANBAN_TASK}` from the main repo first, then cd and work normally. Commit work here. |
|
||||
|
||||
## Tenant isolation
|
||||
|
||||
@@ -175,6 +175,13 @@ If you open the task and `kanban_show` returns `runs: [...]` with one or more cl
|
||||
- `outcome: "reclaimed"` + `summary: "task archived..."` — operator archived the task out from under the previous run; you probably shouldn't be running at all, check status carefully.
|
||||
- `outcome: "blocked"` — a previous attempt blocked; the unblock comment should be in the thread by now.
|
||||
|
||||
## Notification routing
|
||||
|
||||
You can configure the gateway to receive cross-profile Kanban task notifications by adding `notification_sources` to `~/.hermes/config.yaml`.
|
||||
- `notification_sources: ['*']` accepts subscriptions from all profiles.
|
||||
- `notification_sources: ['default', 'zilor-ppt']` or `"default,zilor-ppt"` restricts subscriptions to specified profiles.
|
||||
- Omitting the key keeps the default behavior (profile isolation).
|
||||
|
||||
## Do NOT
|
||||
|
||||
- Call `delegate_task` as a substitute for `kanban_create`. `delegate_task` is for short reasoning subtasks inside YOUR run; `kanban_create` is for cross-agent handoffs that outlive one API loop.
|
||||
|
||||
@@ -21,7 +21,7 @@ Inspect codebases w/ pygount: LOC, languages, ratios.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `LOC`, `Code Analysis`, `pygount`, `Codebase`, `Metrics`, `Repository` |
|
||||
| Related skills | [`github-repo-management`](/user-guide/skills/bundled/github/github-github-repo-management) |
|
||||
| Related skills | [`github-repo-management`](/docs/user-guide/skills/bundled/github/github-github-repo-management) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ GitHub auth setup: HTTPS tokens, SSH keys, gh CLI login.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `GitHub`, `Authentication`, `Git`, `gh-cli`, `SSH`, `Setup` |
|
||||
| Related skills | [`github-pr-workflow`](/user-guide/skills/bundled/github/github-github-pr-workflow), [`github-code-review`](/user-guide/skills/bundled/github/github-github-code-review), [`github-issues`](/user-guide/skills/bundled/github/github-github-issues), [`github-repo-management`](/user-guide/skills/bundled/github/github-github-repo-management) |
|
||||
| Related skills | [`github-pr-workflow`](/docs/user-guide/skills/bundled/github/github-github-pr-workflow), [`github-code-review`](/docs/user-guide/skills/bundled/github/github-github-code-review), [`github-issues`](/docs/user-guide/skills/bundled/github/github-github-issues), [`github-repo-management`](/docs/user-guide/skills/bundled/github/github-github-repo-management) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Review PRs: diffs, inline comments via gh or REST.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `GitHub`, `Code-Review`, `Pull-Requests`, `Git`, `Quality` |
|
||||
| Related skills | [`github-auth`](/user-guide/skills/bundled/github/github-github-auth), [`github-pr-workflow`](/user-guide/skills/bundled/github/github-github-pr-workflow) |
|
||||
| Related skills | [`github-auth`](/docs/user-guide/skills/bundled/github/github-github-auth), [`github-pr-workflow`](/docs/user-guide/skills/bundled/github/github-github-pr-workflow) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Create, triage, label, assign GitHub issues via gh or REST.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `GitHub`, `Issues`, `Project-Management`, `Bug-Tracking`, `Triage` |
|
||||
| Related skills | [`github-auth`](/user-guide/skills/bundled/github/github-github-auth), [`github-pr-workflow`](/user-guide/skills/bundled/github/github-github-pr-workflow) |
|
||||
| Related skills | [`github-auth`](/docs/user-guide/skills/bundled/github/github-github-auth), [`github-pr-workflow`](/docs/user-guide/skills/bundled/github/github-github-pr-workflow) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ GitHub PR lifecycle: branch, commit, open, CI, merge.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `GitHub`, `Pull-Requests`, `CI/CD`, `Git`, `Automation`, `Merge` |
|
||||
| Related skills | [`github-auth`](/user-guide/skills/bundled/github/github-github-auth), [`github-code-review`](/user-guide/skills/bundled/github/github-github-code-review) |
|
||||
| Related skills | [`github-auth`](/docs/user-guide/skills/bundled/github/github-github-auth), [`github-code-review`](/docs/user-guide/skills/bundled/github/github-github-code-review) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Clone/create/fork repos; manage remotes, releases.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `GitHub`, `Repositories`, `Git`, `Releases`, `Secrets`, `Configuration` |
|
||||
| Related skills | [`github-auth`](/user-guide/skills/bundled/github/github-github-auth), [`github-pr-workflow`](/user-guide/skills/bundled/github/github-github-pr-workflow), [`github-issues`](/user-guide/skills/bundled/github/github-github-issues) |
|
||||
| Related skills | [`github-auth`](/docs/user-guide/skills/bundled/github/github-github-auth), [`github-pr-workflow`](/docs/user-guide/skills/bundled/github/github-github-pr-workflow), [`github-issues`](/docs/user-guide/skills/bundled/github/github-github-issues) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ MCP client: connect servers, register tools (stdio/HTTP).
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `MCP`, `Tools`, `Integrations` |
|
||||
| Related skills | [`mcporter`](/user-guide/skills/optional/mcp/mcp-mcporter) |
|
||||
| Related skills | [`mcporter`](/docs/user-guide/skills/optional/mcp/mcp-mcporter) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Spotify: play, search, queue, manage playlists and devices.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `spotify`, `music`, `playback`, `playlists`, `media` |
|
||||
| Related skills | [`gif-search`](/user-guide/skills/bundled/media/media-gif-search) |
|
||||
| Related skills | [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -22,7 +22,7 @@ OBLITERATUS: abliterate LLM refusals (diff-in-means).
|
||||
| Dependencies | `obliteratus`, `torch`, `transformers`, `bitsandbytes`, `accelerate`, `safetensors` |
|
||||
| Platforms | linux, macos |
|
||||
| Tags | `Abliteration`, `Uncensoring`, `Refusal-Removal`, `LLM`, `Weight-Projection`, `SVD`, `Mechanistic-Interpretability`, `HuggingFace`, `Model-Surgery` |
|
||||
| Related skills | `vllm`, `gguf`, [`huggingface-tokenizers`](/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers) |
|
||||
| Related skills | `vllm`, `gguf`, [`huggingface-tokenizers`](/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `Google`, `Gmail`, `Calendar`, `Drive`, `Sheets`, `Docs`, `Contacts`, `Email`, `OAuth` |
|
||||
| Related skills | [`himalaya`](/user-guide/skills/bundled/email/email-himalaya) |
|
||||
| Related skills | [`himalaya`](/docs/user-guide/skills/bundled/email/email-himalaya) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ Extract text from PDFs/scans (pymupdf, marker-pdf).
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `PDF`, `Documents`, `Research`, `Arxiv`, `Text-Extraction`, `OCR` |
|
||||
| Related skills | [`powerpoint`](/user-guide/skills/bundled/productivity/productivity-powerpoint) |
|
||||
| Related skills | [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Jailbreak LLMs: Parseltongue, GODMODE, ULTRAPLINIAN.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `jailbreak`, `red-teaming`, `G0DM0D3`, `Parseltongue`, `GODMODE`, `uncensoring`, `safety-bypass`, `prompt-engineering`, `L1B3RT4S` |
|
||||
| Related skills | [`obliteratus`](/user-guide/skills/bundled/mlops/mlops-inference-obliteratus) |
|
||||
| Related skills | [`obliteratus`](/docs/user-guide/skills/bundled/mlops/mlops-inference-obliteratus) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Search arXiv papers by keyword, author, category, or ID.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `Research`, `Arxiv`, `Papers`, `Academic`, `Science`, `API` |
|
||||
| Related skills | [`ocr-and-documents`](/user-guide/skills/bundled/productivity/productivity-ocr-and-documents) |
|
||||
| Related skills | [`ocr-and-documents`](/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Karpathy's LLM Wiki: build/query interlinked markdown KB.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `wiki`, `knowledge-base`, `research`, `notes`, `markdown`, `rag-alternative` |
|
||||
| Related skills | [`obsidian`](/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`arxiv`](/user-guide/skills/bundled/research/research-arxiv) |
|
||||
| Related skills | [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -22,7 +22,7 @@ Write ML papers for NeurIPS/ICML/ICLR: design→submit.
|
||||
| Dependencies | `semanticscholar`, `arxiv`, `habanero`, `requests`, `scipy`, `numpy`, `matplotlib`, `SciencePlots` |
|
||||
| Platforms | linux, macos |
|
||||
| Tags | `Research`, `Paper Writing`, `Experiments`, `ML`, `AI`, `NeurIPS`, `ICML`, `ICLR`, `ACL`, `AAAI`, `COLM`, `LaTeX`, `Citations`, `Statistical Analysis` |
|
||||
| Related skills | [`arxiv`](/user-guide/skills/bundled/research/research-arxiv), `ml-paper-writing`, [`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), [`plan`](/user-guide/skills/bundled/software-development/software-development-plan) |
|
||||
| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), `ml-paper-writing`, [`subagent-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ Debug Hermes TUI slash commands: Python, gateway, Ink UI.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `debugging`, `hermes-agent`, `tui`, `slash-commands`, `typescript`, `python` |
|
||||
| Related skills | [`python-debugpy`](/user-guide/skills/bundled/software-development/software-development-python-debugpy), [`node-inspect-debugger`](/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), [`systematic-debugging`](/user-guide/skills/bundled/software-development/software-development-systematic-debugging) |
|
||||
| Related skills | [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy), [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ Author in-repo SKILL.md: frontmatter, validator, structure.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `skills`, `authoring`, `hermes-agent`, `conventions`, `skill-md` |
|
||||
| Related skills | [`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans), [`requesting-code-review`](/user-guide/skills/bundled/software-development/software-development-requesting-code-review) |
|
||||
| Related skills | [`writing-plans`](/docs/user-guide/skills/bundled/software-development/software-development-writing-plans), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+196
@@ -0,0 +1,196 @@
|
||||
---
|
||||
title: "Hermes S6 Container Supervision"
|
||||
sidebar_label: "Hermes S6 Container Supervision"
|
||||
description: "Modify, debug, or extend the s6-overlay supervision tree inside the Hermes Agent Docker image — adding new services, debugging profile gateways, understandin..."
|
||||
---
|
||||
|
||||
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
|
||||
|
||||
# Hermes S6 Container Supervision
|
||||
|
||||
Modify, debug, or extend the s6-overlay supervision tree inside the Hermes Agent Docker image — adding new services, debugging profile gateways, understanding the Architecture B main-program pattern.
|
||||
|
||||
## Skill metadata
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Source | Bundled (installed by default) |
|
||||
| Path | `skills/software-development/hermes-s6-container-supervision` |
|
||||
| Version | `1.0.0` |
|
||||
| Author | Hermes Agent |
|
||||
| License | MIT |
|
||||
| Tags | `docker`, `s6`, `supervision`, `gateway`, `profiles` |
|
||||
| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), `hermes-agent-dev` |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
:::info
|
||||
The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
|
||||
:::
|
||||
|
||||
# Hermes s6-overlay Container Supervision
|
||||
|
||||
## When to use this skill
|
||||
|
||||
Load this skill when you're working on:
|
||||
- Adding or removing a static service in the Hermes Docker image (something that should be supervised at every container start, like the dashboard)
|
||||
- Diagnosing why a per-profile gateway isn't starting, restarting, or surviving `docker restart`
|
||||
- Understanding why the container's CMD is `/opt/hermes/docker/main-wrapper.sh` and how leading-dash args reach the user's program
|
||||
- Modifying `cont-init.d` boot scripts (UID remap, volume seeding, profile reconciliation)
|
||||
- Changing the rendered run-script for per-profile gateways (Phase 4)
|
||||
|
||||
If you're just running the Hermes Agent and want to use Docker, see `website/docs/user-guide/docker.md` instead.
|
||||
|
||||
## Architecture at a glance
|
||||
|
||||
<!-- ascii-guard-ignore -->
|
||||
```
|
||||
/init ← PID 1 (s6-overlay v3.2.3.0)
|
||||
├── cont-init.d ← oneshot setup, runs as root
|
||||
│ ├── 01-hermes-setup ← docker/stage2-hook.sh
|
||||
│ │ ├── UID/GID remap
|
||||
│ │ ├── chown /opt/data
|
||||
│ │ ├── chown /opt/data/profiles (every boot)
|
||||
│ │ ├── seed .env / config.yaml / SOUL.md
|
||||
│ │ └── skills_sync.py
|
||||
│ └── 02-reconcile-profiles ← hermes_cli.container_boot
|
||||
│ ├── chown /run/service (hermes-writable for runtime register)
|
||||
│ └── walk $HERMES_HOME/profiles/<name>/gateway_state.json
|
||||
│ → recreate /run/service/gateway-<name>/
|
||||
│ → auto-start only those with prior_state == "running"
|
||||
│
|
||||
├── s6-rc.d (static services, in /etc/s6-overlay/s6-rc.d/)
|
||||
│ ├── main-hermes/run ← exec sleep infinity (no-op slot)
|
||||
│ └── dashboard/run ← if HERMES_DASHBOARD=1, runs `hermes dashboard`
|
||||
│
|
||||
├── /run/service (s6-svscan watches; tmpfs)
|
||||
│ ├── gateway-coder/ ← runtime-registered per-profile
|
||||
│ │ ├── type ("longrun")
|
||||
│ │ ├── run ("#!/command/with-contenv sh ... exec s6-setuidgid hermes hermes -p coder gateway run")
|
||||
│ │ ├── down (marker — present means "registered but don't auto-start")
|
||||
│ │ └── log/run (s6-log → $HERMES_HOME/logs/gateways/coder/current)
|
||||
│ └── ...
|
||||
│
|
||||
└── CMD ("main program") ← /opt/hermes/docker/main-wrapper.sh
|
||||
└── routes user args: bare exec | hermes subcommand | hermes (no args)
|
||||
— exec'd by /init with stdin/stdout/stderr inherited (TTY for --tui)
|
||||
```
|
||||
<!-- ascii-guard-ignore-end -->
|
||||
|
||||
## Key files
|
||||
|
||||
| Path | Role |
|
||||
|---|---|
|
||||
| `Dockerfile` | s6-overlay install + cont-init.d wiring + `ENTRYPOINT ["/init", "/opt/hermes/docker/main-wrapper.sh"]` |
|
||||
| `docker/stage2-hook.sh` | The "old entrypoint logic" — UID remap, chown, seed, skills sync. Runs as cont-init.d/01-hermes-setup. |
|
||||
| `docker/cont-init.d/02-reconcile-profiles` | Calls `hermes_cli.container_boot` on every boot to restore profile gateway slots from the persistent volume. |
|
||||
| `docker/main-wrapper.sh` | The container's CMD. Routes user args, drops to hermes via `s6-setuidgid`, exec's the chosen program. |
|
||||
| `docker/s6-rc.d/main-hermes/run` | No-op `sleep infinity` — slot exists so the s6-rc user bundle is valid; main hermes runs as the CMD, not as a supervised service. |
|
||||
| `docker/s6-rc.d/dashboard/run` | Conditional service — `exec sleep infinity` unless `HERMES_DASHBOARD` is truthy. |
|
||||
| `docker/entrypoint.sh` | Back-compat shim that `exec`s the stage2 hook. External scripts that hard-coded the old entrypoint path still work. |
|
||||
| `hermes_cli/service_manager.py` | `S6ServiceManager`: `register_profile_gateway`, `unregister_profile_gateway`, `start/stop/restart/is_running`, `list_profile_gateways`. |
|
||||
| `hermes_cli/container_boot.py` | `reconcile_profile_gateways()` — walks persistent profiles, regenerates s6 slots, emits `container-boot.log`. |
|
||||
| `hermes_cli/gateway.py::_dispatch_via_service_manager_if_s6` | Intercepts `hermes gateway start/stop/restart` and routes to s6 when running in a container. |
|
||||
|
||||
## Why Architecture B (CMD as main program, not s6-supervised)
|
||||
|
||||
The original plan (v1–v3) called for main hermes to run as a supervised s6-rc service. Two real s6-overlay v3 mechanics blocked that:
|
||||
|
||||
1. **cont-init.d scripts receive no CMD args** — so the stage2 hook can't parse `docker run <image> chat -q "hi"` to set `HERMES_ARGS` for a service `run` script to consume.
|
||||
2. **`/run/s6/basedir/bin/halt` does NOT propagate the exit code** written to `/run/s6-linux-init-container-results/exitcode`. Containers always exit 143 (SIGTERM) regardless. Confirmed by skarnet (s6 author) in [issue #477](https://github.com/just-containers/s6-overlay/issues/477): _"if you want a container shutdown, you need to either have your CMD exit, or, if you have no CMD, write the container exit code you want then call halt"_.
|
||||
|
||||
So we use the s6-overlay-native CMD pattern: `ENTRYPOINT ["/init", "/opt/hermes/docker/main-wrapper.sh"]`. /init prepends the wrapper to user args automatically — so `docker run <image> --version` becomes `/init main-wrapper.sh --version`, and `--version` doesn't get intercepted by /init's POSIX shell. The wrapper drops to hermes via `s6-setuidgid`, then exec's the chosen program. The program's exit code becomes the container exit code, exactly matching the pre-s6 tini contract.
|
||||
|
||||
Trade-off: main hermes is unsupervised under s6. That exactly matches its behavior under tini (the pre-s6 image). Dashboard supervision is the only **new** guarantee — and per-profile gateways under `/run/service/` get full supervision.
|
||||
|
||||
## Quick recipes
|
||||
|
||||
### Verify s6 is PID 1 in a running container
|
||||
|
||||
```sh
|
||||
docker exec <c> sh -c 'cat /proc/1/comm; readlink /proc/1/exe'
|
||||
# Expect: s6-svscan or init / /package/admin/s6/.../s6-svscan
|
||||
```
|
||||
|
||||
### Inspect a profile gateway service
|
||||
|
||||
```sh
|
||||
# /command/ isn't on docker-exec PATH — use absolute path
|
||||
docker exec <c> /command/s6-svstat /run/service/gateway-<name>
|
||||
# "up (pid …) … seconds" → running
|
||||
# "down (exitcode N) … seconds, normally up, want up, …" → s6 wants it up but the process keeps exiting (crash loop)
|
||||
# "down … normally up, ready …" → user stopped it
|
||||
```
|
||||
|
||||
### Bring a service up/down manually
|
||||
|
||||
```sh
|
||||
docker exec <c> /command/s6-svc -u /run/service/gateway-<name> # up
|
||||
docker exec <c> /command/s6-svc -d /run/service/gateway-<name> # down
|
||||
docker exec <c> /command/s6-svc -t /run/service/gateway-<name> # SIGTERM (restart)
|
||||
```
|
||||
|
||||
### Watch the cont-init reconciler log
|
||||
|
||||
```sh
|
||||
docker exec <c> tail -n 50 /opt/data/logs/container-boot.log
|
||||
# 2026-05-21T06:18:05+0000 profile=coder prior_state=running action=started
|
||||
# 2026-05-21T06:18:05+0000 profile=writer prior_state=stopped action=registered
|
||||
```
|
||||
|
||||
### Add a new static service
|
||||
|
||||
1. Create `docker/s6-rc.d/<name>/type` with `longrun\n` and `docker/s6-rc.d/<name>/run` (use `#!/command/with-contenv sh` + `# shellcheck shell=sh`).
|
||||
2. Drop to hermes via `s6-setuidgid hermes` at the top of run (unless you specifically need root).
|
||||
3. Create empty `docker/s6-rc.d/<name>/dependencies.d/base` so it waits for the base bundle.
|
||||
4. Create empty `docker/s6-rc.d/user/contents.d/<name>` so it joins the user bundle.
|
||||
5. The `COPY docker/s6-rc.d/` in the Dockerfile picks it up automatically — no other changes.
|
||||
|
||||
### Change the per-profile gateway run command
|
||||
|
||||
Edit `S6ServiceManager._render_run_script` in `hermes_cli/service_manager.py`. The function is also called by `hermes_cli/container_boot.py::_register_service` during boot reconciliation, so it's the single source of truth. Update the corresponding assertion in `tests/hermes_cli/test_service_manager.py::test_s6_register_creates_service_dir_and_triggers_scan`.
|
||||
|
||||
### Run the docker test harness
|
||||
|
||||
```sh
|
||||
docker build -t hermes-agent-harness:latest .
|
||||
HERMES_TEST_IMAGE=hermes-agent-harness:latest scripts/run_tests.sh tests/docker/ -v
|
||||
# Expect 19 passed, 0 xfailed against the s6 image
|
||||
```
|
||||
|
||||
The harness lives in `tests/docker/` and skips when Docker isn't available. The per-test timeout is bumped to 180s (see `tests/docker/conftest.py`).
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
### "command not found" via `docker exec`
|
||||
|
||||
`/command/` (where s6-overlay puts its binaries) is on PATH only for processes spawned by the supervision tree — services, cont-init.d, main-wrapper.sh. `docker exec <c> s6-svstat …` will fail with "command not found"; always use the absolute path `/command/s6-svstat`. The `hermes` binary works because the Dockerfile adds `/opt/hermes/.venv/bin` to the runtime `ENV PATH`.
|
||||
|
||||
### Profile directory ownership
|
||||
|
||||
The cont-init reconciler runs as hermes (`s6-setuidgid hermes` in `02-reconcile-profiles`). If a profile dir ends up root-owned (e.g. because `docker exec <c> hermes profile create …` ran as root by default), the reconciler can't read SOUL.md and fails with `PermissionError`. Mitigation: `stage2-hook.sh` chowns `$HERMES_HOME/profiles` to hermes on **every** boot, idempotently. Don't remove that block.
|
||||
|
||||
### Files written by `docker exec` are root-owned
|
||||
|
||||
`docker exec` defaults to root. Either pass `--user hermes` or rely on the stage2 chown sweep next reboot. Don't write files under `$HERMES_HOME/profiles/<name>/` as root manually — the next reconcile pass will sweep them but in-flight operations may hit perm errors.
|
||||
|
||||
### Service slot exists but s6-svstat says "s6-supervise not running"
|
||||
|
||||
The service directory is on tmpfs and was wiped on container restart. Either the cont-init reconciler hasn't run yet (give it a moment after `docker restart`) or it failed. Check `docker logs <c> | grep '02-reconcile'`.
|
||||
|
||||
### Gateway starts then immediately exits (`down (exitcode 1)` in svstat)
|
||||
|
||||
Most likely the profile has no model or auth configured. The service slot is correct — the gateway itself is unconfigured. Run `hermes -p <profile> setup` first. The s6 supervisor will keep restarting it; that's the desired behavior (when you fix the config, the next attempt succeeds and stays up).
|
||||
|
||||
### Reconciler skipped a profile
|
||||
|
||||
The reconciler keys on the **presence of `SOUL.md`** as the "real profile" marker. `hermes profile create` always seeds it. If a profile dir is missing SOUL.md (stray directory, partial restore, backup-in-progress), the reconciler skips it intentionally. Add a `SOUL.md` (even empty) to opt back in.
|
||||
|
||||
### "Help, the container exits 143!"
|
||||
|
||||
Check whether something is invoking `s6-svscanctl -t` or `/run/s6/basedir/bin/halt` — both cause /init to begin stage 3 shutdown but return 143 (SIGTERM) rather than the desired exit code. This was the Phase 2 architecture pivot from A to B. For container shutdown with a real exit code, you must let the CMD (main-wrapper.sh) exit normally; do **not** try to control exit from a finish script.
|
||||
|
||||
## Related skills
|
||||
|
||||
- `hermes-agent-dev`: General hermes-agent codebase navigation
|
||||
- `hermes-tool-quirks`: Specific Hermes-tool workarounds (sed/grep/etc.) — load when debugging the s6 stack's interaction with hermes built-in tools.
|
||||
+1
-1
@@ -21,7 +21,7 @@ Debug Node.js via --inspect + Chrome DevTools Protocol CLI.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `debugging`, `nodejs`, `node-inspect`, `cdp`, `breakpoints`, `ui-tui` |
|
||||
| Related skills | [`systematic-debugging`](/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`python-debugpy`](/user-guide/skills/bundled/software-development/software-development-python-debugpy), [`debugging-hermes-tui-commands`](/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands) |
|
||||
| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy), [`debugging-hermes-tui-commands`](/docs/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ Plan mode: write markdown plan to .hermes/plans/, no exec.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `planning`, `plan-mode`, `implementation`, `workflow` |
|
||||
| Related skills | [`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans), [`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development) |
|
||||
| Related skills | [`writing-plans`](/docs/user-guide/skills/bundled/software-development/software-development-writing-plans), [`subagent-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ Debug Python: pdb REPL + debugpy remote (DAP).
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos |
|
||||
| Tags | `debugging`, `python`, `pdb`, `debugpy`, `breakpoints`, `dap`, `post-mortem` |
|
||||
| Related skills | [`systematic-debugging`](/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`node-inspect-debugger`](/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), [`debugging-hermes-tui-commands`](/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands) |
|
||||
| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), [`debugging-hermes-tui-commands`](/docs/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ Pre-commit review: security scan, quality gates, auto-fix.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `code-review`, `security`, `verification`, `quality`, `pre-commit`, `auto-fix` |
|
||||
| Related skills | [`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), [`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans), [`test-driven-development`](/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`github-code-review`](/user-guide/skills/bundled/github/github-github-code-review) |
|
||||
| Related skills | [`subagent-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), [`writing-plans`](/docs/user-guide/skills/bundled/software-development/software-development-writing-plans), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`github-code-review`](/docs/user-guide/skills/bundled/github/github-github-code-review) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ Throwaway experiments to validate an idea before build.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `spike`, `prototype`, `experiment`, `feasibility`, `throwaway`, `exploration`, `research`, `planning`, `mvp`, `proof-of-concept` |
|
||||
| Related skills | [`sketch`](/user-guide/skills/bundled/creative/creative-sketch), [`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans), [`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), [`plan`](/user-guide/skills/bundled/software-development/software-development-plan) |
|
||||
| Related skills | [`sketch`](/docs/user-guide/skills/bundled/creative/creative-sketch), [`writing-plans`](/docs/user-guide/skills/bundled/software-development/software-development-writing-plans), [`subagent-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ Execute plans via delegate_task subagents (2-stage review).
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `delegation`, `subagent`, `implementation`, `workflow`, `parallel` |
|
||||
| Related skills | [`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans), [`requesting-code-review`](/user-guide/skills/bundled/software-development/software-development-requesting-code-review), [`test-driven-development`](/user-guide/skills/bundled/software-development/software-development-test-driven-development) |
|
||||
| Related skills | [`writing-plans`](/docs/user-guide/skills/bundled/software-development/software-development-writing-plans), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ description: "4-phase root cause debugging: understand bugs before fixing"
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `debugging`, `troubleshooting`, `problem-solving`, `root-cause`, `investigation` |
|
||||
| Related skills | [`test-driven-development`](/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans), [`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development) |
|
||||
| Related skills | [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`writing-plans`](/docs/user-guide/skills/bundled/software-development/software-development-writing-plans), [`subagent-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ TDD: enforce RED-GREEN-REFACTOR, tests before code.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `testing`, `tdd`, `development`, `quality`, `red-green-refactor` |
|
||||
| Related skills | [`systematic-debugging`](/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans), [`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development) |
|
||||
| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`writing-plans`](/docs/user-guide/skills/bundled/software-development/software-development-writing-plans), [`subagent-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ Write implementation plans: bite-sized tasks, paths, code.
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `planning`, `design`, `implementation`, `workflow`, `documentation` |
|
||||
| Related skills | [`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), [`test-driven-development`](/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`requesting-code-review`](/user-guide/skills/bundled/software-development/software-development-requesting-code-review) |
|
||||
| Related skills | [`subagent-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ description: "Send email, manage calendar events, search Drive, read/write Sheet
|
||||
|
||||
# Google Workspace Skill
|
||||
|
||||
Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration for Hermes. Uses OAuth2 with automatic token refresh. Prefers the [Google Workspace CLI (`gws`)](https://github.com/nicholasgasior/gws) when available for broader coverage, and falls back to Google's Python client libraries otherwise.
|
||||
Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration for Hermes. Uses OAuth2 with automatic token refresh. Prefers the [Google Workspace CLI (`gws`)](https://github.com/googleworkspace/cli) when available for broader coverage, and falls back to Google's Python client libraries otherwise.
|
||||
|
||||
**Skill path:** `skills/productivity/google-workspace/`
|
||||
|
||||
|
||||
+195
@@ -0,0 +1,195 @@
|
||||
---
|
||||
title: "Antigravity Cli — Operate the Antigravity CLI (agy): plugins, auth, sandbox"
|
||||
sidebar_label: "Antigravity Cli"
|
||||
description: "Operate the Antigravity CLI (agy): plugins, auth, sandbox"
|
||||
---
|
||||
|
||||
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
|
||||
|
||||
# Antigravity Cli
|
||||
|
||||
Operate the Antigravity CLI (agy): plugins, auth, sandbox.
|
||||
|
||||
## Skill metadata
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Source | Optional — install with `hermes skills install official/autonomous-ai-agents/antigravity-cli` |
|
||||
| Path | `optional-skills/autonomous-ai-agents/antigravity-cli` |
|
||||
| Version | `0.1.0` |
|
||||
| Author | Tony Simons (asimons81), Hermes Agent |
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `Coding-Agent`, `Antigravity`, `CLI`, `Auth`, `Plugins`, `Sandbox` |
|
||||
| Related skills | [`grok`](/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
:::info
|
||||
The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
|
||||
:::
|
||||
|
||||
# Antigravity CLI (`agy`)
|
||||
|
||||
Operator guide for the Antigravity CLI, invoked as `agy`. Run all `agy`
|
||||
commands through the Hermes `terminal` tool; inspect its config and logs with
|
||||
`read_file`. This skill is reference + procedure — it does not wrap a network
|
||||
API, so there is nothing to authenticate from Hermes itself.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Installing, updating, or smoke-testing the `agy` binary
|
||||
- Driving non-interactive `agy --print` / `agy -p` one-shots
|
||||
- Debugging Antigravity auth, sandbox, permissions, or plugin state
|
||||
- Reading Antigravity settings, keybindings, conversations, or logs
|
||||
|
||||
## Mental model
|
||||
|
||||
Antigravity has two layers — keep them distinct or the guidance will be wrong:
|
||||
|
||||
1. **Shell wrapper commands** — `agy help`, `agy install`, `agy plugin`,
|
||||
`agy update`, `agy changelog`. Run these through the `terminal` tool.
|
||||
2. **Interactive in-session slash commands** — `/config`, `/permissions`,
|
||||
`/skills`, `/agents`, etc. These only exist inside a running `agy` TUI
|
||||
session, not on the shell wrapper.
|
||||
|
||||
`agy help` shows the shell wrapper surface, NOT the in-session slash commands.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- The `agy` binary on PATH. Verify through the `terminal` tool:
|
||||
`command -v agy && agy --version`.
|
||||
- No env vars or API keys required by this skill — Antigravity manages its own
|
||||
auth via the OS keyring / browser sign-in (see Authentication below).
|
||||
|
||||
## How to Run
|
||||
|
||||
Invoke every `agy` command through the `terminal` tool. Examples:
|
||||
|
||||
```
|
||||
terminal(command="agy --version")
|
||||
terminal(command="agy help")
|
||||
terminal(command="agy plugin list")
|
||||
terminal(command="agy --print 'Summarize the repo in 3 bullets'", workdir="/path/to/project")
|
||||
```
|
||||
|
||||
For an interactive multi-turn TUI session, launch `agy` with `pty=true` (and
|
||||
tmux for capture/monitoring), the same pattern the `codex` / `claude-code`
|
||||
skills use. For one-shot smoke tests and scripted prompts, prefer
|
||||
`agy --print` (non-interactive).
|
||||
|
||||
To inspect Antigravity's own files, use `read_file` on the paths under Core
|
||||
paths below — do not `cat` them through the terminal.
|
||||
|
||||
## Core paths
|
||||
|
||||
- Binary / entrypoint: `agy`
|
||||
- App data dir: `~/.gemini/antigravity-cli/`
|
||||
- Settings file: `~/.gemini/antigravity-cli/settings.json`
|
||||
- Keybindings file: `~/.gemini/antigravity-cli/keybindings.json`
|
||||
- Logs: `~/.gemini/antigravity-cli/log/cli-*.log`
|
||||
- Conversations: `~/.gemini/antigravity-cli/conversations/`
|
||||
- Brain artifacts: `~/.gemini/antigravity-cli/brain/`
|
||||
- History: `~/.gemini/antigravity-cli/history.jsonl`
|
||||
- Plugin staging: `~/.gemini/antigravity-cli/plugins/<plugin_name>/`
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Wrapper commands
|
||||
- `agy changelog`
|
||||
- `agy help`
|
||||
- `agy install`
|
||||
- `agy plugin` / `agy plugins`
|
||||
- `agy update`
|
||||
|
||||
### Useful flags
|
||||
- `--add-dir`
|
||||
- `--continue` / `-c`
|
||||
- `--conversation`
|
||||
- `--dangerously-skip-permissions`
|
||||
- `--print` / `-p`
|
||||
- `--print-timeout`
|
||||
- `--prompt`
|
||||
- `--prompt-interactive` / `-i`
|
||||
- `--sandbox`
|
||||
- `--log-file`
|
||||
- `--version`
|
||||
|
||||
### Plugin subcommands (`agy plugin --help`)
|
||||
- `list`, `import [source]`, `install <target>`, `uninstall <name>`,
|
||||
`enable <name>`, `disable <name>`, `validate [path]`, `link <mp> <target>`,
|
||||
`help`
|
||||
|
||||
### Install flags (`agy install --help`)
|
||||
- `--dir`, `--skip-aliases`, `--skip-path`
|
||||
|
||||
### In-session slash commands
|
||||
- **Conversation control:** `/resume` (`/switch`), `/rewind` (`/undo`),
|
||||
`/rename <name>`, `/clear`, `/fork`, `/reset`, `/new`
|
||||
- **Settings & tools:** `/config`, `/settings`, `/permissions`, `/model`,
|
||||
`/keybindings`, `/statusline`, `/tasks`, `/skills`, `/mcp`, `/open <path>`,
|
||||
`/usage`, `/logout`, `/agents`
|
||||
- **Prompt helpers:** `@` path autocomplete, `esc esc` clears the prompt (when
|
||||
not streaming), `!` runs a terminal command directly, `?` opens help
|
||||
|
||||
## Settings and permissions
|
||||
|
||||
### Common settings keys (`settings.json`)
|
||||
- `allowNonWorkspaceAccess`
|
||||
- `colorScheme`
|
||||
- `permissions.allow`
|
||||
- `trustedWorkspaces`
|
||||
|
||||
### Permission modes
|
||||
`request-review`, `always-proceed`, `strict`, `proceed-in-sandbox`.
|
||||
|
||||
### Sandbox behavior
|
||||
- `enableTerminalSandbox` is a boolean in `settings.json`; default `false`.
|
||||
- Launch-time overrides (`--sandbox`, `--dangerously-skip-permissions`) can
|
||||
supersede persistent settings for the current session.
|
||||
|
||||
## Authentication behavior
|
||||
|
||||
- The CLI tries the OS secure keyring first.
|
||||
- With no saved session, it falls back to browser-based Google sign-in.
|
||||
- Locally it opens the default browser; over SSH it prints an authorization URL
|
||||
and expects the auth code pasted back.
|
||||
- `/logout` removes saved credentials.
|
||||
|
||||
## Plugins
|
||||
|
||||
- Plugins stage under `~/.gemini/antigravity-cli/plugins/<plugin_name>/`.
|
||||
- They can bundle skills, agents, rules, MCP servers, and hooks.
|
||||
- `agy plugin list` returning no imported plugins is a valid empty state.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- `agy help` shows wrapper commands, not interactive slash commands.
|
||||
- `agy --version` is the safe non-interactive version check; `agy version` is
|
||||
interactive and can fail without a real TTY.
|
||||
- First place to look for failures: `~/.gemini/antigravity-cli/log/cli-*.log`
|
||||
(read with `read_file`).
|
||||
- Don't confuse persistent JSON settings with launch-time overrides.
|
||||
- `~/.gemini/antigravity-cli/bin/agentapi` is a thin wrapper to `agy agentapi`.
|
||||
- On WSL, token storage is file-based, so auth issues are usually local-file /
|
||||
session-state problems, not browser-only problems.
|
||||
- Workspace identity can depend on launch directory and the `.antigravitycli`
|
||||
project marker.
|
||||
|
||||
## Verification
|
||||
|
||||
Confirm the install is real and usable, all through the `terminal` tool (read
|
||||
files with `read_file`):
|
||||
|
||||
1. `terminal(command="command -v agy")`
|
||||
2. `terminal(command="agy --version")`
|
||||
3. `terminal(command="agy help")`
|
||||
4. `terminal(command="agy plugin list")`
|
||||
5. `read_file` on `~/.gemini/antigravity-cli/settings.json`
|
||||
6. `read_file` on the latest `~/.gemini/antigravity-cli/log/cli-*.log`
|
||||
7. If needed, `read_file` on `~/.gemini/antigravity-cli/keybindings.json`
|
||||
|
||||
## Support files
|
||||
|
||||
- `references/cli-docs.md` — condensed notes from the getting-started, usage,
|
||||
and features docs.
|
||||
+1
-1
@@ -21,7 +21,7 @@ Delegate coding tasks to Blackbox AI CLI agent. Multi-model agent with built-in
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `Coding-Agent`, `Blackbox`, `Multi-Agent`, `Judge`, `Multi-Model` |
|
||||
| Related skills | [`claude-code`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
|
||||
| Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
+319
@@ -0,0 +1,319 @@
|
||||
---
|
||||
title: "Grok — Delegate coding to xAI Grok Build CLI (features, PRs)"
|
||||
sidebar_label: "Grok"
|
||||
description: "Delegate coding to xAI Grok Build CLI (features, PRs)"
|
||||
---
|
||||
|
||||
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
|
||||
|
||||
# Grok
|
||||
|
||||
Delegate coding to xAI Grok Build CLI (features, PRs).
|
||||
|
||||
## Skill metadata
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Source | Optional — install with `hermes skills install official/autonomous-ai-agents/grok` |
|
||||
| Path | `optional-skills/autonomous-ai-agents/grok` |
|
||||
| Version | `0.1.0` |
|
||||
| Author | Matt Maximo (MattMaximo), Hermes Agent |
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `Coding-Agent`, `Grok`, `xAI`, `Code-Review`, `Refactoring`, `Automation` |
|
||||
| Related skills | [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
:::info
|
||||
The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
|
||||
:::
|
||||
|
||||
# Grok Build CLI — Hermes Orchestration Guide
|
||||
|
||||
Delegate coding tasks to [Grok Build](https://docs.x.ai/build/overview) (xAI's
|
||||
autonomous coding agent CLI, the `grok` command) via the Hermes terminal. Grok
|
||||
can read files, write code, run shell commands, spawn subagents, and manage git
|
||||
workflows. It runs three ways: an interactive TUI, **headless** (`-p`), and as
|
||||
an **ACP agent** over JSON-RPC.
|
||||
|
||||
This is the third sibling to `codex` and `claude-code`. The orchestration
|
||||
pattern is nearly identical — **prefer headless `-p` for one-shots**, use a PTY
|
||||
for interactive sessions.
|
||||
|
||||
## When to use
|
||||
|
||||
- Building features
|
||||
- Refactoring
|
||||
- PR reviews
|
||||
- Batch issue fixing
|
||||
- Any task where you'd otherwise reach for Codex / Claude Code but want Grok
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Install (preferred):** `npm install -g @xai-official/grok`
|
||||
- The official installer `curl -fsSL https://x.ai/cli/install.sh | bash` also
|
||||
works, but the `x.ai` host is Cloudflare-walled in some environments. The
|
||||
npm path avoids that dependency entirely.
|
||||
- **Auth — SuperGrok / X Premium+ subscription (primary path):**
|
||||
- Run `grok login` once → opens a browser for OAuth → token cached in
|
||||
`~/.grok/auth.json`. This uses your **SuperGrok or X Premium+** subscription
|
||||
(no per-token API billing).
|
||||
- Check sign-in state by looking for `~/.grok/auth.json`, or run a cheap
|
||||
headless smoke test: `grok --no-auto-update -p "Say ok."`
|
||||
- In the TUI, `/logout` signs out and `/login` (or relaunching) signs back in.
|
||||
- **No git repo required** — unlike Codex, Grok runs fine outside a git
|
||||
directory (good for scratch/throwaway tasks).
|
||||
- **Claude Code / AGENTS.md compatible with zero config** — Grok auto-reads
|
||||
`CLAUDE.md`, `.claude/` (skills, agents, MCPs, hooks, rules), and the
|
||||
`AGENTS.md` family. Existing project context just works.
|
||||
|
||||
> **API-key fallback (not the default for this user):** Grok also supports
|
||||
> setting the `XAI_API_KEY` environment variable for pay-as-you-go billing
|
||||
> via `api.x.ai`. Only use
|
||||
> this if `grok login` / SuperGrok auth is unavailable. The subscription path
|
||||
> (`grok login`) is the intended setup here.
|
||||
|
||||
## Two Orchestration Modes
|
||||
|
||||
### Mode 1: Headless (`-p`) — Non-Interactive (PREFERRED)
|
||||
|
||||
Runs a one-shot task, prints the result, and exits. No PTY, no interactive
|
||||
dialogs to navigate. This is the cleanest integration path — the analog of
|
||||
`claude -p` and `codex exec`.
|
||||
|
||||
```
|
||||
terminal(command="grok --no-auto-update -p 'Add a dark mode toggle to settings'", workdir="/path/to/project", timeout=180)
|
||||
```
|
||||
|
||||
Always pass `--no-auto-update` in automation to skip background update checks.
|
||||
|
||||
**When to use headless:**
|
||||
- One-shot coding tasks (fix a bug, add a feature, refactor)
|
||||
- CI/CD automation and scripting
|
||||
- Structured output parsing with `--output-format json`
|
||||
- Any task that doesn't need multi-turn conversation
|
||||
|
||||
### Mode 2: Interactive PTY — Multi-Turn TUI Sessions
|
||||
|
||||
The TUI is a fullscreen, mouse-interactive app. Drive it with `pty=true`. For
|
||||
robust monitoring/input use tmux (same pattern as the `claude-code` skill).
|
||||
|
||||
```
|
||||
# Launch in a tmux session for capture-pane monitoring
|
||||
terminal(command="tmux new-session -d -s grok-work -x 140 -y 40")
|
||||
terminal(command="tmux send-keys -t grok-work 'cd /path/to/project && grok' Enter")
|
||||
|
||||
# Wait for startup, then send a task
|
||||
terminal(command="sleep 5 && tmux send-keys -t grok-work 'Refactor the auth module to use JWT' Enter")
|
||||
|
||||
# Monitor progress
|
||||
terminal(command="sleep 15 && tmux capture-pane -t grok-work -p -S -50")
|
||||
|
||||
# Exit when done
|
||||
terminal(command="tmux send-keys -t grok-work '/quit' Enter && sleep 1 && tmux kill-session -t grok-work")
|
||||
```
|
||||
|
||||
**Tip for headless-but-inline output:** if you want TUI-style output without the
|
||||
fullscreen alt-screen takeover (e.g. for cleaner logs), add `--no-alt-screen`.
|
||||
For pure automation, headless `-p` is still cleaner than the TUI.
|
||||
|
||||
## Headless Deep Dive
|
||||
|
||||
### Common Flags
|
||||
|
||||
| Flag | Effect |
|
||||
|------|--------|
|
||||
| `-p, --single <PROMPT>` | Send one prompt, run headless, exit |
|
||||
| `-m, --model <MODEL>` | Choose a model |
|
||||
| `-s, --session-id <ID>` | Create or resume a named headless session |
|
||||
| `-r, --resume <ID>` | Resume an existing session |
|
||||
| `-c, --continue` | Continue the most recent session in the current directory |
|
||||
| `--cwd <PATH>` | Set the working directory |
|
||||
| `--output-format <FMT>` | `plain` (default), `json`, or `streaming-json` |
|
||||
| `--always-approve` | Auto-approve all tool executions (the `--full-auto` / `--yolo` equivalent) |
|
||||
| `--no-alt-screen` | Run inline, no fullscreen TUI takeover |
|
||||
| `--no-auto-update` | Skip background update checks (use in all automation) |
|
||||
|
||||
### Output Formats
|
||||
|
||||
- `plain` — human-readable text (default)
|
||||
- `json` — one JSON object at the end of the run (parse the result cleanly)
|
||||
- `streaming-json` — newline-delimited JSON events as they arrive
|
||||
|
||||
```
|
||||
# Structured result for parsing
|
||||
terminal(command="grok --no-auto-update -p 'List all TODO comments in src/' --output-format json", workdir="/project", timeout=120)
|
||||
|
||||
# Auto-approve for autonomous building
|
||||
terminal(command="grok --no-auto-update --always-approve -p 'Refactor the database layer and run the tests'", workdir="/project", timeout=300)
|
||||
```
|
||||
|
||||
### Background Mode (Long Tasks)
|
||||
|
||||
```
|
||||
# Start headless in background
|
||||
terminal(command="grok --no-auto-update --always-approve -p 'Refactor the auth module'", workdir="/project", background=true, notify_on_complete=true)
|
||||
# Returns session_id
|
||||
|
||||
# Monitor
|
||||
process(action="poll", session_id="<id>")
|
||||
process(action="log", session_id="<id>")
|
||||
|
||||
# Kill if needed
|
||||
process(action="kill", session_id="<id>")
|
||||
```
|
||||
|
||||
For an interactive (TUI) background session, use `pty=true` + tmux and monitor
|
||||
with `tmux capture-pane`, exactly like the `claude-code` / `codex` skills.
|
||||
|
||||
### Session Continuation
|
||||
|
||||
```
|
||||
# Start a named session
|
||||
terminal(command="grok --no-auto-update -s refactor-db -p 'Start refactoring the database layer' --always-approve", workdir="/project", timeout=240)
|
||||
|
||||
# Resume it later
|
||||
terminal(command="grok --no-auto-update -r refactor-db -p 'Now add connection pooling' --always-approve", workdir="/project", timeout=180)
|
||||
|
||||
# Or continue the most recent session in this directory
|
||||
terminal(command="grok --no-auto-update -c -p 'What did you change last time?'", workdir="/project", timeout=60)
|
||||
```
|
||||
|
||||
## Read-Only Audit → Markdown Note Pattern
|
||||
|
||||
To have Grok review local artifacts and return a clean markdown note (for
|
||||
Obsidian or a repo) without mutating anything:
|
||||
|
||||
1. Prepare stable input files first with Hermes tools (`read_file`,
|
||||
`write_file`). Snapshot only the relevant context into a temp file rather
|
||||
than dumping raw paths.
|
||||
2. Run Grok headless **without** `--always-approve` so it cannot auto-write, and
|
||||
demand `markdown only, no preamble`.
|
||||
3. Save Grok's stdout straight into the destination note with `write_file()`.
|
||||
|
||||
```
|
||||
grok --no-auto-update -p "Read /tmp/current.md and /tmp/inventory.md. Produce markdown only, no preamble. Output a clean note titled 'Cleanup Review'." --output-format plain
|
||||
```
|
||||
|
||||
**Pitfall (same as Claude Code):** for document rewrites, a loose "rewrite this"
|
||||
prompt may return a change summary instead of the full file. Instead: pipe the
|
||||
file in, and demand `Return ONLY the full revised markdown document. No intro,
|
||||
no explanation, no code fences. Start immediately with '# Title'.` Verify the
|
||||
first lines with `read_file()` before overwriting the destination.
|
||||
|
||||
## PR Review Patterns
|
||||
|
||||
### Quick Review (Headless)
|
||||
|
||||
```
|
||||
terminal(command="cd /path/to/repo && git diff main...feature-branch | grok --no-auto-update -p 'Review this diff for bugs, security issues, and style problems. Be thorough.'", timeout=120)
|
||||
```
|
||||
|
||||
### Clone-to-temp Review (safe, no repo mutation)
|
||||
|
||||
```
|
||||
terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && grok --no-auto-update -p 'Review the changes vs origin/main. Check bugs, security, race conditions, missing tests.'", pty=true, timeout=300)
|
||||
```
|
||||
|
||||
### Post the review
|
||||
|
||||
```
|
||||
terminal(command="gh pr comment 42 --body '<review text>'", workdir="/path/to/repo")
|
||||
```
|
||||
|
||||
## Parallel Issue Fixing with Worktrees
|
||||
|
||||
```
|
||||
# Create worktrees
|
||||
terminal(command="git worktree add -b fix/issue-78 /tmp/issue-78 main", workdir="~/project")
|
||||
terminal(command="git worktree add -b fix/issue-99 /tmp/issue-99 main", workdir="~/project")
|
||||
|
||||
# Launch Grok headless in each (background)
|
||||
terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #78: <description>. Commit when done.'", workdir="/tmp/issue-78", background=true, notify_on_complete=true)
|
||||
terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #99: <description>. Commit when done.'", workdir="/tmp/issue-99", background=true, notify_on_complete=true)
|
||||
|
||||
# Monitor
|
||||
process(action="list")
|
||||
|
||||
# After completion: push and open PRs
|
||||
terminal(command="cd /tmp/issue-78 && git push -u origin fix/issue-78")
|
||||
terminal(command="gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'")
|
||||
|
||||
# Cleanup
|
||||
terminal(command="git worktree remove /tmp/issue-78", workdir="~/project")
|
||||
```
|
||||
|
||||
## Useful Subcommands & TUI Commands
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `grok` | Start the interactive TUI |
|
||||
| `grok -p "query"` | Headless one-shot |
|
||||
| `grok login` / `grok logout` | Sign in / out (SuperGrok / X Premium+ OAuth) |
|
||||
| `grok inspect` | Show what Grok discovered in cwd: config sources, instructions, skills, plugins, hooks, MCP servers |
|
||||
| `grok agent stdio` | Run as an ACP agent over JSON-RPC (for IDE/tool integration) |
|
||||
| `grok update` | Update the CLI (needs the `x.ai` host; skip in automation) |
|
||||
|
||||
TUI slash commands (interactive only): `/model <name>`, `/always-approve`,
|
||||
`/plan`, `/context`, `/compact`, `/resume`, `/sessions`, `/fork`, `/usage`,
|
||||
`/quit`. `Shift+Tab` cycles session modes (including Plan mode, which blocks
|
||||
write tools except the session plan file).
|
||||
|
||||
## Config (`~/.grok/config.toml`)
|
||||
|
||||
```toml
|
||||
[cli]
|
||||
auto_update = false # skip background update checks persistently
|
||||
|
||||
[ui]
|
||||
permission_mode = "ask" # or "always-approve" to skip tool prompts by default
|
||||
|
||||
[models]
|
||||
default = "grok-build-0.1"
|
||||
```
|
||||
|
||||
Put global preferences in `~/.grok/config.toml` (not project-scoped
|
||||
`.grok/config.toml`). `permission_mode` supersedes the legacy `approval_mode` /
|
||||
`yolo = true` keys.
|
||||
|
||||
## Pitfalls & Gotchas
|
||||
|
||||
1. **Auth is subscription-gated.** `grok login` requires a SuperGrok or X
|
||||
Premium+ subscription. If login fails or there's no `~/.grok/auth.json`,
|
||||
confirm the subscription is active before falling back to `XAI_API_KEY`.
|
||||
2. **Don't conflate Hermes' xAI auth with the `grok` CLI's auth.** Hermes'
|
||||
`x_search` runs on its own xAI OAuth; the standalone `grok` CLI has a
|
||||
separate token in `~/.grok/auth.json`. A working `x_search` does NOT mean
|
||||
`grok` is logged in.
|
||||
3. **Always pass `--no-auto-update` in automation** — otherwise Grok phones home
|
||||
for update checks (and `x.ai`/`storage.googleapis.com` may be unreachable).
|
||||
4. **Prefer npm install over the curl installer** — `npm install -g
|
||||
@xai-official/grok` avoids the Cloudflare-walled `x.ai` host.
|
||||
5. **`--always-approve` is the autonomous-build switch.** Without it, headless
|
||||
runs may stall waiting on tool-approval prompts. Omit it deliberately for
|
||||
read-only review/audit work so Grok can't mutate files.
|
||||
6. **Headless `-p` skips TUI dialogs**; the TUI needs `pty=true` (+ tmux for
|
||||
monitoring), just like Claude Code.
|
||||
7. **Use `--no-alt-screen`** if you run the TUI inline and the fullscreen
|
||||
alt-screen takeover garbles captured output.
|
||||
8. **No git repo needed**, but for PR/commit workflows you still want one — use
|
||||
`mktemp -d && git init` for scratch commit tasks.
|
||||
9. **Clean up tmux sessions** with `tmux kill-session -t <name>` when done.
|
||||
|
||||
## Rules for Hermes Agents
|
||||
|
||||
1. **Prefer headless `-p`** for single tasks — cleanest integration, structured
|
||||
output via `--output-format json`.
|
||||
2. **Always set `workdir`** (or `--cwd`) so Grok targets the right project.
|
||||
3. **Pass `--no-auto-update`** in every automated invocation.
|
||||
4. **Use `--always-approve` only when Grok should write autonomously**; omit it
|
||||
for read-only reviews and audits.
|
||||
5. **Background long tasks** with `background=true, notify_on_complete=true` and
|
||||
monitor via the `process` tool.
|
||||
6. **Use tmux for multi-turn interactive work** and monitor with
|
||||
`tmux capture-pane -t <session> -p -S -50`.
|
||||
7. **Verify auth before relying on it** — check `~/.grok/auth.json` or run a
|
||||
cheap `grok -p "Say ok."` smoke test; don't assume Hermes' xAI auth carries
|
||||
over.
|
||||
8. **Report results to the user** — summarize what Grok changed and what's left.
|
||||
+1
-1
@@ -21,7 +21,7 @@ Configure and use Honcho memory with Hermes -- cross-session user modeling, mult
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `Honcho`, `Memory`, `Profiles`, `Observation`, `Dialectic`, `User-Modeling`, `Session-Summary` |
|
||||
| Related skills | [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
|
||||
| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user