mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-25 00:51:20 +00:00
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
This commit is contained in:
Teknium
GitHub
parent
0df4d1278e
commit
f6db1b27ba
19 changed files with 2788 additions and 2 deletions
244
website/docs/user-guide/profiles.md
Normal file
244
website/docs/user-guide/profiles.md
Normal file
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue