hermes-agent/website/docs/user-guide/profiles.md

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

# 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

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)

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)

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/:

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:

hermes-work chat -q "Check my calendar"
hermes-work gateway start
hermes-work skills list

Sticky default (hermes profile use)

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:

hermes profile use default

One-off with -p flag

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:

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:

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:

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

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

hermes profile list

Shows all profiles with their status. The active profile is marked with an asterisk:

  default
* work
  mybot
  backup

Show profile details

hermes profile show work

Displays the profile's home directory, config path, active model, configured platforms, and other details.

Rename a profile

hermes profile rename mybot assistant

Renames the profile directory and updates the shell alias from hermes-mybot to hermes-assistant.

Export a profile

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

hermes profile import ./work-backup.tar.gz work-restored

Imports a previously exported profile archive as a new profile.

Deleting a profile

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:

hermes profile use default
hermes profile delete mybot

Tab completion

Enable shell completions for profile names and subcommands:

# 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.