Why you might want more than one agent
A profile is a complete, separate Hermes home directory. Each one has its own config.yaml, .env with API keys, SOUL.md personality, memories, sessions, skills, cron jobs, logs and state database. That makes it easy to keep a coding assistant, a personal Telegram bot and a research agent apart, each with its own model, tools and memory, instead of one agent whose memory is a muddle of three jobs.
The default profile is ~/.hermes itself. Named profiles live under ~/.hermes/profiles/<;name>/.
Creating profiles
hermes profile create <name> makes a blank profile with the bundled skills. Two flags save setup time:
- --clone copies config, .env,
SOUL.md, skills and memory files, but starts with empty sessions and no cron jobs. - --clone-all makes a fuller copy, still excluding session history and cron.
- --clone-from <source> picks which profile to copy from, and --description "<role>" records what the profile is for.
Switching between them
Each profile gets its own command alias in ~/.local/bin, so after creating a profile called coder you can simply run coder chat, which is the same as hermes -p coder chat. The -p <name> flag works in any position on any command.
If you mostly use one profile, make it sticky with hermes profile use <name>; plain hermes commands then target it until you run hermes profile use default. hermes profile list and hermes profile show <name> tell you what exists.
What is not isolated
This is the part people get wrong. Profiles separate state; they are not security sandboxes.
- On the local terminal backend, every profile has the same file access as your user account. Use a container backend if you need isolation.
- The working directory is set separately by terminal.cwd; set an absolute path if each profile should start in its own folder.
- On host installs, external CLIs share your real HOME and their credentials unless you set terminal.home_mode: profile.
- OAuth logins for providers such as Anthropic, OpenAI Codex and xAI are shared through the root
auth.jsonby default, because their refresh tokens are single-use. Give a profile its own login withhermes -p<name> auth add <provider>.
Running a bot per profile
Each profile runs its own gateway as a separate process with its own bot token in its own .env. coder gateway start and assistant gateway start run independently, and coder gateway install creates a per-profile service. One bot token belongs to one profile: if two gateways try to use the same token, the second is blocked by a token lock. That is also why cloning does not copy bot tokens, allowlists or platform sections unless you pass --clone-channels.
Sharing, retiring and one firm rule
hermes profile export <name> produces a shareable .tar.gz with API keys stripped, and hermes profile import <file> installs one as a new profile. hermes profile delete <name> stops its gateway, removes the service and alias and deletes its data; the default profile can't be deleted this way.
The firm rule from the docs: never point two agent processes at the same profile. Two writers on one home will mix their memory writes into shared state. If two agents genuinely need to share what they learn, use an external memory provider rather than a shared home. Also note that hermes update syncs bundled skills into every profile, and a profile with a broken config.yaml can make that step fail for the whole install, so keep unused profiles tidy or delete them.
Related guides
- Hermes Agent messaging gateway explained
- How Hermes Agent memory works (and where it stops)
- Hermes Agent terminal backends: local, Docker, SSH, cloud
- Where Hermes Agent runs: host vs work environment
Primary sources
Spotted something wrong or out of date? Tell us on X at @HermesWatcher (opens in a new tab) and we will fix it.
New Hermes Agent updates every day on X. Follow @HermesWatcher