feat: add profiles — run multiple isolated Hermes instances (#3681)

Each profile is a fully independent HERMES_HOME with its own config, API keys, memory, sessions, skills, gateway, cron, and state.db. Core module: hermes_cli/profiles.py (~900 lines) - Profile CRUD: create, delete, list, show, rename - Three clone levels: blank, --clone (config), --clone-all (everything) - Export/import: tar.gz archive for backup and migration - Wrapper alias scripts (~/.local/bin/<name>) - Collision detection for alias names - Sticky default via ~/.hermes/active_profile - Skill seeding via subprocess (handles module-level caching) - Auto-stop gateway on delete with disable-before-stop for services - Tab completion generation for bash and zsh CLI integration (hermes_cli/main.py): - _apply_profile_override(): pre-import -p/--profile flag + sticky default - Full 'hermes profile' subcommand: list, use, create, delete, show, alias, rename, export, import - 'hermes completion bash/zsh' command - Multi-profile skill sync in hermes update Display (cli.py, banner.py, gateway/run.py): - CLI prompt: 'coder ❯' when using a non-default profile - Banner shows profile name - Gateway startup log includes profile name Gateway safety: - Token locks: Discord, Slack, WhatsApp, Signal (extends Telegram pattern) - Port conflict detection: API server, webhook adapter Diagnostics (hermes_cli/doctor.py): - Profile health section: lists profiles, checks config, .env, aliases - Orphan alias detection: warns when wrapper points to deleted profile Tests (tests/hermes_cli/test_profiles.py): - 71 automated tests covering: validation, CRUD, clone levels, rename, export/import, active profile, isolation, alias collision, completion - Full suite: 6760 passed, 0 new failures Documentation: - website/docs/user-guide/profiles.md: full user guide (12 sections) - website/docs/reference/profile-commands.md: command reference (12 commands) - website/docs/reference/faq.md: 6 profile FAQ entries - website/sidebars.ts: navigation updated
2026-05-04 02:21:47 +00:00 · 2026-03-29 10:41:20 -07:00 · 2026-03-29 10:41:20 -07:00 · f6db1b27ba
commit f6db1b27ba
parent 0df4d1278e
19 changed files with 2788 additions and 2 deletions
--- a/website/docs/developer-guide/contributing.md
+++ b/website/docs/developer-guide/contributing.md
@ -90,6 +90,7 @@ pytest tests/ -v
 - **Comments**: Only when explaining non-obvious intent, trade-offs, or API quirks
 - **Error handling**: Catch specific exceptions. Use `logger.warning()`/`logger.error()` with `exc_info=True` for unexpected errors
 - **Cross-platform**: Never assume Unix (see below)
+- **Profile-safe paths**: Never hardcode `~/.hermes` — use `get_hermes_home()` from `hermes_constants` for code paths and `display_hermes_home()` for user-facing messages. See [AGENTS.md](https://github.com/NousResearch/hermes-agent/blob/main/AGENTS.md#profiles-multi-instance-support) for full rules.

 ## Cross-Platform Compatibility

--- a/website/docs/reference/faq.md
+++ b/website/docs/reference/faq.md
@ -489,6 +489,44 @@ If an MCP server crashes mid-request, Hermes will report a timeout. Check the se

 ---

+## Profiles
+
+### How do profiles differ from just setting HERMES_HOME?
+
+Profiles are a managed layer on top of `HERMES_HOME`. You *could* manually set `HERMES_HOME=/some/path` before every command, but profiles handle all the plumbing for you: creating the directory structure, generating shell aliases (`hermes-work`), tracking the active profile in `~/.hermes/active_profile`, and syncing skill updates across all profiles automatically. They also integrate with tab completion so you don't have to remember paths.
+
+### Can two profiles share the same bot token?
+
+No. Each messaging platform (Telegram, Discord, etc.) requires exclusive access to a bot token. If two profiles try to use the same token simultaneously, the second gateway will fail to connect. Create a separate bot per profile — for Telegram, talk to [@BotFather](https://t.me/BotFather) to make additional bots.
+
+### Do profiles share memory or sessions?
+
+No. Each profile has its own memory store, session database, and skills directory. They are completely isolated. If you want to start a new profile with existing memories and sessions, use `hermes profile create newname --clone-all` to copy everything from the current profile.
+
+### What happens when I run `hermes update`?
+
+`hermes update` pulls the latest code and reinstalls dependencies **once** (not per-profile). It then syncs updated skills to all profiles automatically. You only need to run `hermes update` once — it covers every profile on the machine.
+
+### Can I move a profile to a different machine?
+
+Yes. Export the profile to a portable archive and import it on the other machine:
+
+```bash
+# On the source machine
+hermes profile export work ./work-backup.tar.gz
+
+# Copy the file to the target machine, then:
+hermes profile import ./work-backup.tar.gz work
+```
+
+The imported profile will have all config, memories, sessions, and skills from the export. You may need to update paths or re-authenticate with providers if the new machine has a different setup.
+
+### How many profiles can I run?
+
+There is no hard limit. Each profile is just a directory under `~/.hermes/profiles/`. The practical limit depends on your disk space and how many concurrent gateways your system can handle (each gateway is a lightweight Python process). Running dozens of profiles is fine; each idle profile uses no resources.
+
+---
+
 ## Still Stuck?

 If your issue isn't covered here:
--- a/website/docs/reference/profile-commands.md
+++ b/website/docs/reference/profile-commands.md
@ -0,0 +1,280 @@
+---
+sidebar_position: 7
+---
+
+# Profile Commands Reference
+
+This page covers all commands related to [Hermes profiles](../user-guide/profiles.md). For general CLI commands, see [CLI Commands Reference](./cli-commands.md).
+
+## `hermes profile`
+
+```bash
+hermes profile <subcommand>
+```
+
+Top-level command for managing profiles. Running `hermes profile` without a subcommand shows help.
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List all profiles. |
+| `use` | Set the active (default) profile. |
+| `create` | Create a new profile. |
+| `delete` | Delete a profile. |
+| `show` | Show details about a profile. |
+| `alias` | Regenerate the shell alias for a profile. |
+| `rename` | Rename a profile. |
+| `export` | Export a profile to a tar.gz archive. |
+| `import` | Import a profile from a tar.gz archive. |
+
+## `hermes profile list`
+
+```bash
+hermes profile list
+```
+
+Lists all profiles. The currently active profile is marked with `*`.
+
+**Example:**
+
+```bash
+$ hermes profile list
+  default
+* work
+  dev
+  personal
+```
+
+No options.
+
+## `hermes profile use`
+
+```bash
+hermes profile use <name>
+```
+
+Sets `<name>` as the active profile. All subsequent `hermes` commands (without `-p`) will use this profile.
+
+| Argument | Description |
+|----------|-------------|
+| `<name>` | Profile name to activate. Use `default` to return to the base profile. |
+
+**Example:**
+
+```bash
+hermes profile use work
+hermes profile use default
+```
+
+## `hermes profile create`
+
+```bash
+hermes profile create <name> [options]
+```
+
+Creates a new profile.
+
+| Argument / Option | Description |
+|-------------------|-------------|
+| `<name>` | Name for the new profile. Must be a valid directory name (alphanumeric, hyphens, underscores). |
+| `--clone` | Copy `config.yaml`, `.env`, and `SOUL.md` from the current profile. |
+| `--clone-all` | Copy everything (config, memories, skills, sessions, state) from the current profile. |
+| `--from <profile>` | Clone from a specific profile instead of the current one. Used with `--clone` or `--clone-all`. |
+
+**Examples:**
+
+```bash
+# Blank profile — needs full setup
+hermes profile create mybot
+
+# Clone config only from current profile
+hermes profile create work --clone
+
+# Clone everything from current profile
+hermes profile create backup --clone-all
+
+# Clone config from a specific profile
+hermes profile create work2 --clone --from work
+```
+
+## `hermes profile delete`
+
+```bash
+hermes profile delete <name> [options]
+```
+
+Deletes a profile and removes its shell alias.
+
+| Argument / Option | Description |
+|-------------------|-------------|
+| `<name>` | Profile to delete. |
+| `--yes`, `-y` | Skip confirmation prompt. |
+
+**Example:**
+
+```bash
+hermes profile delete mybot
+hermes profile delete mybot --yes
+```
+
+:::warning
+This permanently deletes the profile's entire directory including all config, memories, sessions, and skills. Cannot delete the currently active profile.
+:::
+
+## `hermes profile show`
+
+```bash
+hermes profile show [name]
+```
+
+Displays details about a profile including its home directory, configured model, active platforms, and disk usage.
+
+| Argument | Description |
+|----------|-------------|
+| `[name]` | Profile to inspect. Defaults to the current active profile if omitted. |
+
+**Example:**
+
+```bash
+$ hermes profile show work
+Profile:    work
+Home:       ~/.hermes/profiles/work
+Model:      anthropic/claude-sonnet-4
+Platforms:  telegram, discord
+Skills:     12 installed
+Disk:       48 MB
+```
+
+## `hermes profile alias`
+
+```bash
+hermes profile alias <name>
+```
+
+Regenerates the shell alias script at `~/.local/bin/hermes-<name>`. Useful if the alias was accidentally deleted or if you need to update it after moving your Hermes installation.
+
+| Argument | Description |
+|----------|-------------|
+| `<name>` | Profile to create/update the alias for. |
+
+**Example:**
+
+```bash
+hermes profile alias work
+# Creates/updates ~/.local/bin/hermes-work
+```
+
+## `hermes profile rename`
+
+```bash
+hermes profile rename <old-name> <new-name>
+```
+
+Renames a profile. Updates the directory and shell alias.
+
+| Argument | Description |
+|----------|-------------|
+| `<old-name>` | Current profile name. |
+| `<new-name>` | New profile name. |
+
+**Example:**
+
+```bash
+hermes profile rename mybot assistant
+# ~/.hermes/profiles/mybot → ~/.hermes/profiles/assistant
+# ~/.local/bin/hermes-mybot → ~/.local/bin/hermes-assistant
+```
+
+## `hermes profile export`
+
+```bash
+hermes profile export <name> <output-path>
+```
+
+Exports a profile as a compressed tar.gz archive.
+
+| Argument | Description |
+|----------|-------------|
+| `<name>` | Profile to export. |
+| `<output-path>` | Path for the output archive (e.g., `./work-backup.tar.gz`). |
+
+**Example:**
+
+```bash
+hermes profile export work ./work-2026-03-29.tar.gz
+```
+
+## `hermes profile import`
+
+```bash
+hermes profile import <archive-path> [name]
+```
+
+Imports a profile from a tar.gz archive.
+
+| Argument | Description |
+|----------|-------------|
+| `<archive-path>` | Path to the tar.gz archive to import. |
+| `[name]` | Name for the imported profile. Defaults to the original profile name from the archive. |
+
+**Example:**
+
+```bash
+hermes profile import ./work-2026-03-29.tar.gz work-restored
+```
+
+## `hermes -p` / `hermes --profile`
+
+```bash
+hermes -p <name> <command> [options]
+hermes --profile <name> <command> [options]
+```
+
+Global flag to run any Hermes command under a specific profile without changing the sticky default. This overrides the active profile for the duration of the command.
+
+| Option | Description |
+|--------|-------------|
+| `-p <name>`, `--profile <name>` | Profile to use for this command. |
+
+**Examples:**
+
+```bash
+hermes -p work chat -q "Check the server status"
+hermes --profile dev gateway start
+hermes -p personal skills list
+hermes -p work config edit
+```
+
+## `hermes completion`
+
+```bash
+hermes completion <shell>
+```
+
+Generates shell completion scripts. Includes completions for profile names and profile subcommands.
+
+| Argument | Description |
+|----------|-------------|
+| `<shell>` | Shell to generate completions for: `bash`, `zsh`, or `fish`. |
+
+**Examples:**
+
+```bash
+# Install completions
+hermes completion bash >> ~/.bashrc
+hermes completion zsh >> ~/.zshrc
+hermes completion fish > ~/.config/fish/completions/hermes.fish
+
+# Reload shell
+source ~/.bashrc
+```
+
+After installation, tab completion works for:
+- `hermes profile <TAB>` — subcommands (list, use, create, etc.)
+- `hermes profile use <TAB>` — profile names
+- `hermes -p <TAB>` — profile names
+
+## See also
+
+- [Profiles User Guide](../user-guide/profiles.md)
+- [CLI Commands Reference](./cli-commands.md)
+- [FAQ — Profiles section](./faq.md#profiles)
--- a/website/docs/user-guide/profiles.md
+++ b/website/docs/user-guide/profiles.md
@ -0,0 +1,244 @@
+---
+sidebar_position: 2
+---
+
+# Profiles: Running Multiple Agents
+
+Run multiple independent Hermes agents on the same machine — each with its own config, memory, sessions, and gateway.
+
+## What are profiles?
+
+A profile is a fully isolated Hermes environment. Each profile gets its own `HERMES_HOME` directory containing its own `config.yaml`, `.env`, `SOUL.md`, memories, sessions, skills, and state database. Profiles let you run separate agents for different purposes — a personal assistant, a work bot, a dev agent — without any cross-contamination.
+
+Each profile also gets a shell alias (e.g., `hermes-work`) so you can launch it directly without flags.
+
+## Quick start
+
+```bash
+# Create a profile called "work"
+hermes profile create work
+
+# Switch to it as the default
+hermes profile use work
+
+# Launch — now everything uses the "work" environment
+hermes
+```
+
+That's it. From now on, `hermes` uses the "work" profile until you switch back.
+
+## Creating a profile
+
+### Blank profile
+
+```bash
+hermes profile create mybot
+```
+
+Creates a fresh, empty profile. You'll need to run `hermes setup` (or `hermes-mybot setup`) to configure it from scratch — provider, model, gateway tokens, etc.
+
+### 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. This gives you the same provider/model setup without copying memories, sessions, or skills. Useful when you want a second agent with the same API keys but different personality or gateway tokens.
+
+### Clone everything (`--clone-all`)
+
+```bash
+hermes profile create backup --clone-all
+```
+
+Copies **everything** — config, memories, sessions, skills, state database, the lot. This is a full snapshot of your current profile. Useful for creating a backup or forking an agent that already has learned context.
+
+## Using profiles
+
+### Shell aliases
+
+Every profile gets an alias installed to `~/.local/bin/`:
+
+```bash
+hermes-work       # Runs hermes with the "work" profile
+hermes-mybot      # Runs hermes with the "mybot" profile
+hermes-backup     # Runs hermes with the "backup" profile
+```
+
+These aliases work with all subcommands:
+
+```bash
+hermes-work chat -q "Check my calendar"
+hermes-work gateway start
+hermes-work skills list
+```
+
+### Sticky default (`hermes profile use`)
+
+```bash
+hermes profile use work
+```
+
+Sets "work" as the active profile. Now plain `hermes` uses the work profile — no alias or flag needed. The active profile is stored in `~/.hermes/active_profile`.
+
+Switch back to the default profile:
+
+```bash
+hermes profile use default
+```
+
+### One-off with `-p` flag
+
+```bash
+hermes -p work chat -q "Summarize my inbox"
+hermes -p mybot gateway status
+```
+
+The `-p` / `--profile` flag overrides the sticky default for a single command without changing it.
+
+## Running gateways
+
+Each profile runs its own independent gateway. This means you can have multiple bots online simultaneously — for example, a personal Telegram bot and a team Discord bot:
+
+```bash
+hermes-personal gateway start    # Starts personal bot's gateway
+hermes-work gateway start        # Starts work bot's gateway
+```
+
+Each gateway uses the tokens and platform config from its own profile's `config.yaml` and `.env`. There are no port or token conflicts because each profile is fully isolated.
+
+:::warning
+Each bot token (Telegram, Discord, etc.) can only be used by **one** profile at a time. If two profiles try to use the same token, the second gateway will fail to connect. Use a separate bot token per profile.
+:::
+
+## Configuring profiles
+
+Each profile has its own independent configuration files:
+
+```
+~/.hermes/profiles/work/
+├── config.yaml        # Model, provider, gateway settings
+├── .env               # API keys, bot tokens
+├── SOUL.md            # Personality / system prompt
+├── skills/            # Installed skills
+├── memories/          # Agent memories
+├── state.db           # Sessions, conversation history
+└── logs/              # Gateway and agent logs
+```
+
+Edit a profile's config directly:
+
+```bash
+hermes-work config edit          # Opens work profile's config.yaml
+hermes -p work setup             # Run setup wizard for work profile
+```
+
+Or edit the files manually:
+
+```bash
+nano ~/.hermes/profiles/work/config.yaml
+nano ~/.hermes/profiles/work/.env
+nano ~/.hermes/profiles/work/SOUL.md
+```
+
+The default profile lives at `~/.hermes/` (not in the `profiles/` subdirectory).
+
+## Updating
+
+```bash
+hermes update
+```
+
+`hermes update` pulls the latest code and reinstalls dependencies once. It then syncs the updated skills to **all** profiles automatically. You don't need to run update separately for each profile — one update covers everything.
+
+## Managing profiles
+
+### List profiles
+
+```bash
+hermes profile list
+```
+
+Shows all profiles with their status. The active profile is marked with an asterisk:
+
+```
+  default
+* work
+  mybot
+  backup
+```
+
+### Show profile details
+
+```bash
+hermes profile show work
+```
+
+Displays the profile's home directory, config path, active model, configured platforms, and other details.
+
+### Rename a profile
+
+```bash
+hermes profile rename mybot assistant
+```
+
+Renames the profile directory and updates the shell alias from `hermes-mybot` to `hermes-assistant`.
+
+### Export a profile
+
+```bash
+hermes profile export work ./work-backup.tar.gz
+```
+
+Packages the entire profile into a portable archive. Useful for backups or transferring to another machine.
+
+### Import a profile
+
+```bash
+hermes profile import ./work-backup.tar.gz work-restored
+```
+
+Imports a previously exported profile archive as a new profile.
+
+## Deleting a profile
+
+```bash
+hermes profile delete mybot
+```
+
+Removes the profile directory and its shell alias. You'll be prompted to confirm. This permanently deletes all config, memories, sessions, and skills for that profile.
+
+:::warning
+Deletion is irreversible. Export the profile first if you might need it later: `hermes profile export mybot ./mybot-backup.tar.gz`
+:::
+
+You cannot delete the currently active profile. Switch to a different one first:
+
+```bash
+hermes profile use default
+hermes profile delete mybot
+```
+
+## Tab completion
+
+Enable shell completions for profile names and subcommands:
+
+```bash
+# Generate completions for your shell
+hermes completion bash >> ~/.bashrc
+hermes completion zsh >> ~/.zshrc
+hermes completion fish > ~/.config/fish/completions/hermes.fish
+
+# Reload your shell
+source ~/.bashrc   # or ~/.zshrc
+```
+
+After setup, `hermes profile <TAB>` autocompletes subcommands and `hermes -p <TAB>` autocompletes profile names.
+
+## How it works
+
+Under the hood, each profile is just a separate `HERMES_HOME` directory. When you run `hermes -p work` or `hermes-work`, Hermes sets `HERMES_HOME=~/.hermes/profiles/work` before starting. Everything — config loading, memory access, session storage, gateway operation — reads from and writes to that directory.
+
+The sticky default (`hermes profile use`) writes the profile name to `~/.hermes/active_profile`. On startup, if no `-p` flag is given, Hermes checks this file and sets `HERMES_HOME` accordingly.
+
+Profile aliases in `~/.local/bin/` are thin wrapper scripts that set `HERMES_HOME` and exec the real `hermes` binary. This means profiles work with all existing Hermes commands, flags, and features without any special handling.