You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: website/docs/getting-started/installation.md
+11Lines changed: 11 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -41,6 +41,17 @@ Native Windows is **not supported**. Please install [WSL2](https://learn.microso
41
41
42
42
The installer handles everything automatically — all dependencies (Python, Node.js, ripgrep, ffmpeg), the repo clone, virtual environment, global `hermes` command setup, and LLM provider configuration. By the end, you're ready to chat.
43
43
44
+
#### Install Layout
45
+
46
+
Where the installer puts things depends on whether you're installing as a normal user or as root:
47
+
48
+
| Installer | Code lives at |`hermes` binary | Data directory |
The root-mode **FHS layout** (`/usr/local/lib/…`, `/usr/local/bin/hermes`) matches where other system-wide developer tools land on Linux. It's useful for shared-machine deployments where one system install should serve every user. Per-user config (auth, skills, sessions) still lives under each user's `~/.hermes/` or explicit `HERMES_HOME`.
Copy file name to clipboardExpand all lines: website/docs/getting-started/updating.md
+27-4Lines changed: 27 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,10 +24,33 @@ This pulls the latest code, updates dependencies, and prompts you to configure a
24
24
25
25
When you run `hermes update`, the following steps occur:
26
26
27
-
1.**Git pull** — pulls the latest code from the `main` branch and updates submodules
28
-
2.**Dependency install** — runs `uv pip install -e ".[all]"` to pick up new or changed dependencies
29
-
3.**Config migration** — detects new config options added since your version and prompts you to set them
30
-
4.**Gateway auto-restart** — if the gateway service is running (systemd on Linux, launchd on macOS), it is **automatically restarted** after the update completes so the new code takes effect immediately
27
+
1.**Pairing-data snapshot** — a lightweight pre-update state snapshot is saved (covers `~/.hermes/pairing/`, Feishu comment rules, and other state files that get modified at runtime). Rollbackable via `hermes backup restore --state pre-update`.
28
+
2.**Git pull** — pulls the latest code from the `main` branch and updates submodules
29
+
3.**Dependency install** — runs `uv pip install -e ".[all]"` to pick up new or changed dependencies
30
+
4.**Config migration** — detects new config options added since your version and prompts you to set them
31
+
5.**Gateway auto-restart** — if the gateway service is running (systemd on Linux, launchd on macOS), it is **automatically restarted** after the update completes so the new code takes effect immediately
32
+
33
+
### Preview-only: `hermes update --check`
34
+
35
+
Want to know if you're behind `origin/main` before actually pulling? Run `hermes update --check` — it fetches, prints your local commit and the latest remote commit side-by-side, and exits `0` if in sync or `1` if behind. No files are modified, no gateway is restarted. Useful in scripts and cron jobs that gate on "is there an update".
36
+
37
+
### Full pre-update backup: `--backup`
38
+
39
+
For high-value profiles (production gateways, shared team installs) you can opt into a full pre-pull backup of `HERMES_HOME` (config, auth, sessions, skills, pairing):
40
+
41
+
```bash
42
+
hermes update --backup
43
+
```
44
+
45
+
Or make it the default for every run:
46
+
47
+
```yaml
48
+
# ~/.hermes/config.yaml
49
+
update:
50
+
backup: true
51
+
```
52
+
53
+
`--backup` was the always-on behavior in earlier builds, but it was adding minutes to every update on large homes, so it's now opt-in. The lightweight pairing-data snapshot above still runs unconditionally.
Copy file name to clipboardExpand all lines: website/docs/guides/build-a-hermes-plugin.md
+16Lines changed: 16 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -242,8 +242,24 @@ def register(ctx):
242
242
- `ctx.register_tool()`puts your tool in the registry — the model sees it immediately
243
243
- `ctx.register_hook()`subscribes to lifecycle events
244
244
- `ctx.register_cli_command()`registers a CLI subcommand (e.g. `hermes my-plugin <subcommand>`)
245
+
- `ctx.register_command()`registers an in-session slash command (e.g. `/myplugin <args>` inside CLI / gateway chat) — see [Register slash commands](#register-slash-commands) below
246
+
- `ctx.dispatch_tool(name, arguments)`— call any other tool (built-in or from another plugin) with the parent agent's context (approvals, credentials, task_id) wired up automatically. Useful from slash-command handlers that need to invoke `terminal`, `read_file`, or any other tool as if the model had called it directly.
245
247
- If this function crashes, the plugin is disabled but Hermes continues fine
246
248
249
+
**`dispatch_tool` example — a slash command that runs a tool:**
250
+
251
+
```python
252
+
def handle_scan(ctx, argstr):
253
+
"""Implement /scan by invoking the terminal tool through the registry."""
254
+
result = ctx.dispatch_tool("terminal", {"command": f"find . -name '{argstr}'"})
255
+
return result # returned to the caller's chat UI
256
+
257
+
def register(ctx):
258
+
ctx.register_command("scan", handle_scan, help="Find files matching a glob")
259
+
```
260
+
261
+
The dispatched tool goes through the normal approval, redaction, and budget pipelines — it's a real tool invocation, not a shortcut around them.
@@ -136,7 +137,7 @@ The OpenAI Codex provider authenticates via device code (open a URL, enter a cod
136
137
:::
137
138
138
139
:::warning
139
-
Even when using Nous Portal, Codex, or a custom endpoint, some tools (vision, web summarization, MoA) use a separate "auxiliary" model — by default Gemini Flash via OpenRouter. An `OPENROUTER_API_KEY` enables these tools automatically. You can also configure which model and provider these tools use — see [Auxiliary Models](/docs/user-guide/configuration#auxiliary-models).
140
+
Even when using Nous Portal, Codex, or a custom endpoint, some tools (vision, web summarization, MoA) use a separate "auxiliary" model. By default (`auxiliary.*.provider: "auto"`), Hermes routes these tasks to your **main chat model** — the same model you picked in `hermes model`. You can override each task individually to route it to a cheaper/faster model (e.g. Gemini Flash on OpenRouter) — see [Auxiliary Models](/docs/user-guide/configuration#auxiliary-models).
140
141
:::
141
142
142
143
:::tip Nous Tool Gateway
@@ -411,6 +412,24 @@ Set `HERMES_QWEN_BASE_URL` only if the portal endpoint relocates (default: `http
411
412
`qwen-oauth`uses the consumer-facing Qwen Portal with OAuth login — ideal for individual users. The `alibaba` provider uses DashScope's enterprise API with a `DASHSCOPE_API_KEY` — ideal for programmatic / production workloads. Both route to Qwen-family models but live at different endpoints.
412
413
:::
413
414
415
+
### Alibaba Coding Plan
416
+
417
+
If you're subscribed to Alibaba's **Coding Plan** (a pricing SKU separate from standard DashScope API access), Hermes exposes it as its own first-class provider: `alibaba-coding-plan`. Endpoint: `https://coding-intl.dashscope.aliyuncs.com/v1`. It's OpenAI-compatible like the regular `alibaba` provider but with a different base URL and billing surface.
418
+
419
+
```yaml
420
+
model:
421
+
provider: alibaba_coding # alias for alibaba-coding-plan
`alibaba_coding` uses the same `DASHSCOPE_API_KEY` your `alibaba` entry already uses — no separate key needed, just a different routing target. Before this provider was registered, users who set `provider: alibaba_coding` in `config.yaml` silently fell through to OpenRouter routing.
432
+
414
433
### MiniMax (OAuth)
415
434
416
435
MiniMax-M2.7 via browser OAuth login — no API key needed. Pick **MiniMax (OAuth)** in `hermes model`, sign in through the browser, and Hermes persists the access + refresh tokens. Uses the Anthropic Messages-compatible endpoint (`/anthropic`) under the hood.
@@ -112,6 +113,33 @@ hermes chat --worktree -q "Review this repo and open a PR"
112
113
hermes chat --ignore-user-config --ignore-rules -q "Repro without my personal setup"
113
114
```
114
115
116
+
### `hermes -z <prompt>` — scripted one-shot
117
+
118
+
For programmatic callers (shell scripts, CI, cron, parent processes piping in a prompt), `hermes -z` is the purest one-shot entry point: **single prompt in, final response text out, nothing else on stdout or stderr.** No banner, no spinner, no tool previews, no `Session:` line — just the agent's final reply as plain text.
119
+
120
+
```bash
121
+
hermes -z "What's the capital of France?"
122
+
# → Paris.
123
+
124
+
# Parent scripts can cleanly capture the response:
Same agent, same tools, same skills — just strips every interactive / cosmetic layer. If you need tool output in the transcript too, use `hermes chat -q` instead; `-z` is explicitly for "I only want the final answer".
142
+
115
143
## `hermes model`
116
144
117
145
Interactive provider + model selector. **This is the command for adding new providers, setting up API keys, and running OAuth flows.** Run it from your terminal — not from inside an active Hermes chat session.
@@ -181,6 +209,12 @@ Subcommands:
181
209
|`uninstall`| Remove the installed service. |
182
210
|`setup`| Interactive messaging-platform setup. |
183
211
212
+
Options:
213
+
214
+
| Option | Description |
215
+
|--------|-------------|
216
+
|`--all`| On `start` / `restart` / `stop`: act on **every profile's** gateway, not just the active `HERMES_HOME`. Useful if you run multiple profiles side-by-side and want to restart them all after `hermes update`. |
217
+
184
218
:::tip WSL users
185
219
Use `hermes gateway run` instead of `hermes gateway start` — WSL's systemd support is unreliable. Wrap it in tmux for persistence: `tmux new -s hermes 'hermes gateway run'`. See [WSL FAQ](/docs/reference/faq#wsl-gateway-keeps-disconnecting-or-hermes-gateway-start-fails) for details.
186
220
:::
@@ -462,6 +496,12 @@ Create a zip archive of your Hermes configuration, skills, sessions, and data. T
462
496
463
497
The backup uses SQLite's `backup()` API for safe copying, so it works correctly even when Hermes is running (WAL-mode safe).
464
498
499
+
**What's excluded from the zip:**
500
+
501
+
-`*.db-wal`, `*.db-shm`, `*.db-journal` — SQLite's WAL / shared-memory / journal sidecars. The `*.db` file already got a consistent snapshot via `sqlite3.backup()`; shipping the live sidecars alongside it would let a restore see a half-committed state.
502
+
-`checkpoints/` — per-session trajectory caches. Hash-keyed and regenerated per session; wouldn't port cleanly to another install anyway.
503
+
- The `hermes-agent` code itself (this is a user-data backup, not a repo snapshot).
Pulls the latest `hermes-agent` code and reinstalls dependencies in your venv, then re-runs the post-install hooks (MCP servers, skills sync, completion install). Safe to run on a live install.
960
+
961
+
| Option | Description |
962
+
|--------|-------------|
963
+
|`--check`| Print the current commit and the latest `origin/main` commit side by side, and exit 0 if in sync or 1 if behind. Does not pull, install, or restart anything. |
964
+
|`--backup`| Create a labeled pre-update snapshot of `HERMES_HOME` (config, auth, sessions, skills, pairing data) before pulling. Default is **off** — the previous always-backup behavior was adding minutes to every update on large homes. Flip it on permanently via `update.backup: true` in `config.yaml`. |
965
+
|`--restart-gateway`| After a successful update, restart the running gateway service. Implies `--all` semantics if multiple profiles are installed. |
966
+
967
+
Additional behavior:
968
+
969
+
-**Pairing data snapshot.** Even when `--backup` is off, `hermes update` takes a lightweight snapshot of `~/.hermes/pairing/` and the Feishu comment rules before `git pull`. You can roll it back with `hermes backup restore --state pre-update` if a pull rewrites a file you were editing.
970
+
-**Legacy `hermes.service` warning.** If Hermes detects a pre-rename `hermes.service` systemd unit (instead of the current `hermes-gateway.service`), it prints a one-time migration hint so you can avoid flap-loop issues.
971
+
-**Exit codes.**`0` on success, `1` on pull/install/post-install errors, `2` on unexpected working-tree changes that block `git pull`.
972
+
973
+
## `hermes fallback`
974
+
975
+
```bash
976
+
hermes fallback # interactive manager
977
+
```
978
+
979
+
Manage the fallback provider chain (used when your primary provider hits a rate limit or returns a fatal error) without hand-editing `config.yaml`. Reuses the provider picker from `hermes model` — same provider list, same credential prompts, same validation.
980
+
981
+
Typical session:
982
+
983
+
1. Press `a` to add a fallback → pick a provider (OAuth-based providers open a browser; API-key providers prompt for the key), then pick the specific model.
984
+
2. Use `↑`/`↓` to reorder fallbacks (first-in-list is tried first).
985
+
3. Press `d` to remove one.
986
+
987
+
All changes persist to `fallback_providers:` under `model:` in `config.yaml`. Interacts with [Credential Pools](/docs/user-guide/features/credential-pools): pools rotate keys *within* a provider, fallbacks switch to a *different* provider entirely.
988
+
989
+
See [Fallback Providers](/docs/user-guide/features/fallback-providers) for behavior details and interaction with `fallback_model` (legacy single-fallback key).
0 commit comments