289cc47631
Broad drift audit against origin/main (b52b63396). Reference pages (most user-visible drift): - slash-commands: add /busy, /curator, /footer, /indicator, /redraw, /steer that were missing; drop non-existent /terminal-setup; fix /q footnote (resolves to /queue, not /quit); extend CLI-only list with all 24 CLI-only commands in the registry - cli-commands: add dedicated sections for hermes curator / fallback / hooks (new subcommands not previously documented); remove stale hermes honcho standalone section (the plugin registers dynamically via hermes memory); list curator/fallback/hooks in top-level table; fix completion to include fish - toolsets-reference: document the real 52-toolset count; split browser vs browser-cdp; add discord / discord_admin / spotify / yuanbao; correct hermes-cli tool count from 36 to 38; fix misleading claim that hermes-homeassistant adds tools (it's identical to hermes-cli) - tools-reference: bump tool count 55 -> 68; add 7 Spotify, 5 Yuanbao, 2 Discord toolsets; move browser_cdp/browser_dialog to their own browser-cdp toolset section - environment-variables: add 40+ user-facing HERMES_* vars that were undocumented (--yolo, --accept-hooks, --ignore-*, inference model override, agent/stream/checkpoint timeouts, OAuth trace, per-platform batch tuning for Telegram/Discord/Matrix/Feishu/WeCom, cron knobs, gateway restart/connect timeouts); dedupe the Cron Scheduler section; replace stale QQ_SANDBOX with QQ_PORTAL_HOST User-guide (top level): - cli.md: compression preserves last 20 turns, not 4 (protect_last_n: 20) - configuration.md: display.platforms is the canonical per-platform override key; tool_progress_overrides is deprecated and auto-migrated - profiles.md: model.default is the config key, not model.model - sessions.md: CLI/TUI session IDs use 6-char hex, gateway uses 8 - checkpoints-and-rollback.md: destructive-command list now matches _DESTRUCTIVE_PATTERNS (adds rmdir, cp, install, dd) - docker.md: the container runs as non-root hermes (UID 10000) via gosu; fix install command (uv pip); add missing --insecure on the dashboard compose example (required for non-loopback bind) - security.md: systemctl danger pattern also matches 'restart' - index.md: built-in tool count 47 -> 68 - integrations/index.md: 6 STT providers, 8 memory providers - integrations/providers.md: drop fictional dashscope/qwen aliases Features: - overview.md: 9 image models (not 8), 9 TTS providers (not 5), 8 memory providers (Supermemory was missing) - tool-gateway.md: 9 image models - tools.md: extend common-toolsets list with search / messaging / spotify / discord / debugging / safe - fallback-providers.md: add 6 real providers from PROVIDER_REGISTRY (lmstudio, kimi-coding-cn, stepfun, alibaba-coding-plan, tencent-tokenhub, azure-foundry) - plugins.md: Available Hooks table now includes on_session_finalize, on_session_reset, subagent_stop - built-in-plugins.md: add the 7 bundled plugins the page didn't mention (spotify, google_meet, three image_gen providers, two dashboard examples) - web-dashboard.md: add --insecure and --tui flags - cron.md: hermes cron create takes positional schedule/prompt, not flags Messaging: - telegram.md: TELEGRAM_WEBHOOK_SECRET is now REQUIRED when TELEGRAM_WEBHOOK_URL is set (gateway refuses to start without it per GHSA-3vpc-7q5r-276h). Biggest user-visible drift in the batch. - discord.md: HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS default is 2.0, not 0.1 - dingtalk.md: document DINGTALK_REQUIRE_MENTION / FREE_RESPONSE_CHATS / MENTION_PATTERNS / HOME_CHANNEL / ALLOW_ALL_USERS that the adapter supports - bluebubbles.md: drop fictional BLUEBUBBLES_SEND_READ_RECEIPTS env var; the setting lives in platforms.bluebubbles.extra only - qqbot.md: drop dead QQ_SANDBOX; add real QQ_PORTAL_HOST and QQ_GROUP_ALLOWED_USERS - wecom-callback.md: replace 'hermes gateway start' (service-only) with 'hermes gateway' for first-time setup Developer-guide: - architecture.md: refresh tool/toolset counts (61/52), terminal backend count (7), line counts for run_agent.py (~13.7k), cli.py (~11.5k), main.py (~10.4k), setup.py (~3.5k), gateway/run.py (~12.2k), mcp_tool.py (~3.1k); add yuanbao adapter, bump platform adapter count 18 -> 20 - agent-loop.md: run_agent.py line count 10.7k -> 13.7k - tools-runtime.md: add vercel_sandbox backend - adding-tools.md: remove stale 'Discovery import added to model_tools.py' checklist item (registry auto-discovery) - adding-platform-adapters.md: mark send_typing / get_chat_info as concrete base methods; only connect/disconnect/send are abstract - acp-internals.md: ACP sessions now persist to SessionDB (~/.hermes/state.db); acp.run_agent call uses use_unstable_protocol=True - cron-internals.md: gateway runs scheduler in a dedicated background thread via _start_cron_ticker, not on a maintenance cycle; locking is cross-process via fcntl.flock (Unix) / msvcrt.locking (Windows) - gateway-internals.md: gateway/run.py ~12k lines - provider-runtime.md: cron DOES support fallback (run_job reads fallback_providers from config) - session-storage.md: SCHEMA_VERSION = 11 (not 9); add migrations 10 and 11 (trigram FTS, inline-mode FTS5 re-index); add api_call_count column to Sessions DDL; document messages_fts_trigram and state_meta in the architecture tree - context-compression-and-caching.md: remove the obsolete 'context pressure warnings' section (warnings were removed for causing models to give up early) - context-engine-plugin.md: compress() signature now includes focus_topic param - extending-the-cli.md: _build_tui_layout_children signature now includes model_picker_widget; add to default layout Also fixed three pre-existing broken links/anchors the build warned about (docker.md -> api-server.md, yuanbao.md -> cron-jobs.md and tips#background-tasks, nix-setup.md -> #container-aware-cli). Regenerated per-skill pages via website/scripts/generate-skill-docs.py so catalog tables and sidebar are consistent with current SKILL.md frontmatter. docusaurus build: clean, no broken links or anchors.
241 lines
8.4 KiB
Markdown
241 lines
8.4 KiB
Markdown
---
|
||
sidebar_position: 2
|
||
---
|
||
|
||
# Profiles: Running Multiple Agents
|
||
|
||
Run multiple independent Hermes agents on the same machine — each with its own config, API keys, memory, sessions, skills, and gateway state.
|
||
|
||
## What are profiles?
|
||
|
||
A profile is a separate Hermes home directory. Each profile gets its own directory containing its own `config.yaml`, `.env`, `SOUL.md`, memories, sessions, skills, cron jobs, and state database. Profiles let you run separate agents for different purposes — a coding assistant, a personal bot, a research agent — without mixing up Hermes state.
|
||
|
||
When you create a profile, it automatically becomes its own command. Create a profile called `coder` and you immediately have `coder chat`, `coder setup`, `coder gateway start`, etc.
|
||
|
||
## Quick start
|
||
|
||
```bash
|
||
hermes profile create coder # creates profile + "coder" command alias
|
||
coder setup # configure API keys and model
|
||
coder chat # start chatting
|
||
```
|
||
|
||
That's it. `coder` is now its own Hermes profile with its own config, memory, and state.
|
||
|
||
## Creating a profile
|
||
|
||
### Blank profile
|
||
|
||
```bash
|
||
hermes profile create mybot
|
||
```
|
||
|
||
Creates a fresh profile with bundled skills seeded. Run `mybot setup` to configure API keys, model, and gateway tokens.
|
||
|
||
### Clone config only (`--clone`)
|
||
|
||
```bash
|
||
hermes profile create work --clone
|
||
```
|
||
|
||
Copies your current profile's `config.yaml`, `.env`, and `SOUL.md` into the new profile. Same API keys and model, but fresh sessions and memory. Edit `~/.hermes/profiles/work/.env` for different API keys, or `~/.hermes/profiles/work/SOUL.md` for a different personality.
|
||
|
||
### Clone everything (`--clone-all`)
|
||
|
||
```bash
|
||
hermes profile create backup --clone-all
|
||
```
|
||
|
||
Copies **everything** — config, API keys, personality, all memories, full session history, skills, cron jobs, plugins. A complete snapshot. Useful for backups or forking an agent that already has context.
|
||
|
||
### Clone from a specific profile
|
||
|
||
```bash
|
||
hermes profile create work --clone --clone-from coder
|
||
```
|
||
|
||
:::tip Honcho memory + profiles
|
||
When Honcho is enabled, `--clone` automatically creates a dedicated AI peer for the new profile while sharing the same user workspace. Each profile builds its own observations and identity. See [Honcho -- Multi-agent / Profiles](./features/memory-providers.md#honcho) for details.
|
||
:::
|
||
|
||
## Using profiles
|
||
|
||
### Command aliases
|
||
|
||
Every profile automatically gets a command alias at `~/.local/bin/<name>`:
|
||
|
||
```bash
|
||
coder chat # chat with the coder agent
|
||
coder setup # configure coder's settings
|
||
coder gateway start # start coder's gateway
|
||
coder doctor # check coder's health
|
||
coder skills list # list coder's skills
|
||
coder config set model.default anthropic/claude-sonnet-4
|
||
```
|
||
|
||
The alias works with every hermes subcommand — it's just `hermes -p <name>` under the hood.
|
||
|
||
### The `-p` flag
|
||
|
||
You can also target a profile explicitly with any command:
|
||
|
||
```bash
|
||
hermes -p coder chat
|
||
hermes --profile=coder doctor
|
||
hermes chat -p coder -q "hello" # works in any position
|
||
```
|
||
|
||
### Sticky default (`hermes profile use`)
|
||
|
||
```bash
|
||
hermes profile use coder
|
||
hermes chat # now targets coder
|
||
hermes tools # configures coder's tools
|
||
hermes profile use default # switch back
|
||
```
|
||
|
||
Sets a default so plain `hermes` commands target that profile. Like `kubectl config use-context`.
|
||
|
||
### Knowing where you are
|
||
|
||
The CLI always shows which profile is active:
|
||
|
||
- **Prompt**: `coder ❯` instead of `❯`
|
||
- **Banner**: Shows `Profile: coder` on startup
|
||
- **`hermes profile`**: Shows current profile name, path, model, gateway status
|
||
|
||
## Profiles vs workspaces vs sandboxing
|
||
|
||
Profiles are often confused with workspaces or sandboxes, but they are different things:
|
||
|
||
- A **profile** gives Hermes its own state directory: `config.yaml`, `.env`, `SOUL.md`, sessions, memory, logs, cron jobs, and gateway state.
|
||
- A **workspace** or **working directory** is where terminal commands start. That is controlled separately by `terminal.cwd`.
|
||
- A **sandbox** is what limits filesystem access. Profiles do **not** sandbox the agent.
|
||
|
||
On the default `local` terminal backend, the agent still has the same filesystem access as your user account. A profile does not stop it from accessing folders outside the profile directory.
|
||
|
||
If you want a profile to start in a specific project folder, set an explicit absolute `terminal.cwd` in that profile's `config.yaml`:
|
||
|
||
```yaml
|
||
terminal:
|
||
backend: local
|
||
cwd: /absolute/path/to/project
|
||
```
|
||
|
||
Using `cwd: "."` on the local backend means "the directory Hermes was launched from", not "the profile directory".
|
||
|
||
Also note:
|
||
|
||
- `SOUL.md` can guide the model, but it does not enforce a workspace boundary.
|
||
- Changes to `SOUL.md` take effect cleanly on a new session. Existing sessions may still be using the old prompt state.
|
||
- Asking the model "what directory are you in?" is not a reliable isolation test. If you need a predictable starting directory for tools, set `terminal.cwd` explicitly.
|
||
|
||
## Running gateways
|
||
|
||
Each profile runs its own gateway as a separate process with its own bot token:
|
||
|
||
```bash
|
||
coder gateway start # starts coder's gateway
|
||
assistant gateway start # starts assistant's gateway (separate process)
|
||
```
|
||
|
||
### Different bot tokens
|
||
|
||
Each profile has its own `.env` file. Configure a different Telegram/Discord/Slack bot token in each:
|
||
|
||
```bash
|
||
# Edit coder's tokens
|
||
nano ~/.hermes/profiles/coder/.env
|
||
|
||
# Edit assistant's tokens
|
||
nano ~/.hermes/profiles/assistant/.env
|
||
```
|
||
|
||
### Safety: token locks
|
||
|
||
If two profiles accidentally use the same bot token, the second gateway will be blocked with a clear error naming the conflicting profile. Supported for Telegram, Discord, Slack, WhatsApp, and Signal.
|
||
|
||
### Persistent services
|
||
|
||
```bash
|
||
coder gateway install # creates hermes-gateway-coder systemd/launchd service
|
||
assistant gateway install # creates hermes-gateway-assistant service
|
||
```
|
||
|
||
Each profile gets its own service name. They run independently.
|
||
|
||
## Configuring profiles
|
||
|
||
Each profile has its own:
|
||
|
||
- **`config.yaml`** — model, provider, toolsets, all settings
|
||
- **`.env`** — API keys, bot tokens
|
||
- **`SOUL.md`** — personality and instructions
|
||
|
||
```bash
|
||
coder config set model.default anthropic/claude-sonnet-4
|
||
echo "You are a focused coding assistant." > ~/.hermes/profiles/coder/SOUL.md
|
||
```
|
||
|
||
If you want this profile to work in a specific project by default, also set its own `terminal.cwd`:
|
||
|
||
```bash
|
||
coder config set terminal.cwd /absolute/path/to/project
|
||
```
|
||
|
||
## Updating
|
||
|
||
`hermes update` pulls code once (shared) and syncs new bundled skills to **all** profiles automatically:
|
||
|
||
```bash
|
||
hermes update
|
||
# → Code updated (12 commits)
|
||
# → Skills synced: default (up to date), coder (+2 new), assistant (+2 new)
|
||
```
|
||
|
||
User-modified skills are never overwritten.
|
||
|
||
## Managing profiles
|
||
|
||
```bash
|
||
hermes profile list # show all profiles with status
|
||
hermes profile show coder # detailed info for one profile
|
||
hermes profile rename coder dev-bot # rename (updates alias + service)
|
||
hermes profile export coder # export to coder.tar.gz
|
||
hermes profile import coder.tar.gz # import from archive
|
||
```
|
||
|
||
## Deleting a profile
|
||
|
||
```bash
|
||
hermes profile delete coder
|
||
```
|
||
|
||
This stops the gateway, removes the systemd/launchd service, removes the command alias, and deletes all profile data. You'll be asked to type the profile name to confirm.
|
||
|
||
Use `--yes` to skip confirmation: `hermes profile delete coder --yes`
|
||
|
||
:::note
|
||
You cannot delete the default profile (`~/.hermes`). To remove everything, use `hermes uninstall`.
|
||
:::
|
||
|
||
## Tab completion
|
||
|
||
```bash
|
||
# Bash
|
||
eval "$(hermes completion bash)"
|
||
|
||
# Zsh
|
||
eval "$(hermes completion zsh)"
|
||
```
|
||
|
||
Add the line to your `~/.bashrc` or `~/.zshrc` for persistent completion. Completes profile names after `-p`, profile subcommands, and top-level commands.
|
||
|
||
## How it works
|
||
|
||
Profiles use the `HERMES_HOME` environment variable. When you run `coder chat`, the wrapper script sets `HERMES_HOME=~/.hermes/profiles/coder` before launching hermes. Since 119+ files in the codebase resolve paths via `get_hermes_home()`, Hermes state automatically scopes to the profile's directory — config, sessions, memory, skills, state database, gateway PID, logs, and cron jobs.
|
||
|
||
This is separate from terminal working directory. Tool execution starts from `terminal.cwd` (or the launch directory when `cwd: "."` on the local backend), not automatically from `HERMES_HOME`.
|
||
|
||
The default profile is simply `~/.hermes` itself. No migration needed — existing installs work identically.
|