Run multiple Hermes agents with profiles

What is a Hermes profile?

A profile is a separate Hermes home directory, so each profile is an independent agent with its own settings and state. Named profiles live under ~/.hermes/profiles/<name>/, and the default profile is ~/.hermes itself. You can use profiles to keep a coding assistant, a personal bot and a research agent apart on one machine.

The docs use a few related terms that are easy to mix up:

• Profile: the persistent home for an agent's configuration and data.
• Agent: the running Hermes assistant that uses a profile.
• Messaging bot: an account on Telegram, Discord, Slack or another platform, connected through the gateway with its own bot token.
• Subagent: a short-lived child spawned by delegate_task with a fresh conversation. A separate conversation is not a separate profile.

One rule matters more than the rest: never point two agent processes at the same profile. Both would write memory automatically and load each other's writes at the next session start. If two agents need shared memory, the docs recommend an external memory provider instead.

What does each profile have its own copy of?

Each profile has its own configuration, secrets, persona, memory, skills, sessions and scheduled work. Hermes scopes all of this through the HERMES_HOME environment variable, which the profile's command sets before it starts.

Some things are shared on purpose. The code is installed once, and hermes update pulls it once and syncs new bundled skills to every profile without overwriting skills you changed. On host installs, tool subprocesses keep your real OS HOME by default, so git, ssh and gh use the same credentials in every profile. Set terminal.home_mode: profile in a profile's config.yaml if you need separate CLI identities.

How do you create, list, switch and delete profiles?

Use the hermes profile commands. Creating a profile also creates a command with the same name.

hermes profile create coder         # new profile plus a "coder" command
coder setup                         # set its model, API keys and bot tokens
coder chat                          # chat with this agent
hermes profile list                 # all profiles with their status
hermes profile show coder           # details for one profile
hermes profile use coder            # make coder the default for plain "hermes"
hermes profile use default          # switch back
hermes profile rename coder dev-bot # rename, updating the command
hermes profile delete coder         # asks you to type the name to confirm

hermes profile delete stops the profile's gateway, removes its service and command, and deletes all of its data. Add --yes to skip the confirmation. You cannot delete the default profile, because it is ~/.hermes itself. Use hermes uninstall to remove everything.

You can also target any profile with the -p flag, for example hermes -p coder doctor. The CLI shows which profile is active in the prompt (coder ❯) and in the startup banner.

If a profile will take work from the kanban board, give it a role description when you create it:

hermes profile create researcher --description "Reads source code and external docs, writes findings."

Should you clone an existing profile?

Clone when you want a new agent that starts from an existing setup. Each option copies a different amount.

No clone copies messaging channels. Bot tokens, allowlists and platform sections are left behind because a bot can belong to only one profile. Add --clone-channels only if you really want to keep them. OAuth logins for Anthropic, OpenAI Codex and xAI are shared through the root ~/.hermes/auth.json rather than copied. To give a profile its own login, run hermes -p <name> auth add <provider>.

How do profile command aliases work?

Every profile gets a wrapper script at ~/.local/bin/<name> that runs hermes -p <name>, so it works with every Hermes subcommand.

coder gateway start
coder doctor
coder skills list
coder config set model.default anthropic/claude-sonnet-4

For tab completion of profile names, add eval "$(hermes completion bash)" (or the zsh version) to your shell profile.

How do you run several messaging gateways?

Each profile runs its own gateway as a separate process with its own bot token. Put a different Telegram, Discord or Slack token in each profile's .env, usually through <name> setup.

coder gateway start          # starts coder's gateway
assistant gateway start      # a separate process for assistant
coder gateway install        # creates a hermes-gateway-coder service
assistant gateway install    # creates a hermes-gateway-assistant service

If two profiles use the same bot token by accident, the second gateway is blocked with an error that names the conflicting profile. This lock covers Telegram, Discord, Slack, WhatsApp and Signal.

The alternative is a single multiplexing gateway that serves every profile from one process. Platforms that use one credential per bot still need their own token for each profile in that mode.

How do you set a profile's working directory?

Set an absolute terminal.cwd in that profile's config. The working directory is where terminal commands start, and it is separate from the profile directory.

terminal:
  backend: local
  cwd: /absolute/path/to/project

Or from the command line:

coder config set terminal.cwd /absolute/path/to/project

On the local backend, cwd: "." means the directory you launched Hermes from, not the profile directory.

Are profiles a sandbox?

No. A profile separates Hermes state, but it does not limit what files the agent can reach. On the default local terminal backend, the agent has the same filesystem access as your user account, and SOUL.md instructions do not enforce a boundary either. If you need isolation, use a sandboxed terminal backend such as Docker or a separate machine.

How do you move or share a profile?

Export a profile to a single archive, or publish it as a git repository others can install.

hermes profile export coder                       # coder.tar.gz, API keys stripped
hermes profile import ./coder.tar.gz --name coder
hermes profile install github.com/you/research-bot --alias

A profile export leaves out credentials by design, so it is not a full backup. Use hermes backup when you want everything.

FAQ

Sources

• Profiles: Running Multiple Agents
• Running Many Gateways at Once
• Persistent Memory
• Kanban: Multi-Agent Profile Collaboration