Hermes Agent: Profiles and Multiple Configurations

Hermes Agent: Profiles and Multiple Configurations

A typical developer juggles multiple contexts: an ongoing React project, a Python automation script, a personal Telegram bot, and perhaps a dedicated research agent. Each context has its own needs in terms of AI model, APIs, configuration, and personality. Hermes Agent solves this problem with its profiles system — fully isolated configurations that coexist on the same machine, each with its own set of files, sessions, memory, and gateway.

This article dives deep into Hermes Agent's profile system: creation, configuration, concrete use cases, data isolation, multiple gateway management, and best practices for organizing your agents efficiently.

What is a Hermes profile?

A profile is a separate Hermes home directory. When you create a profile, Hermes generates a complete folder containing its own configuration, API keys, sessions, memory, skills, cron jobs, and gateway state. Each profile functions as an autonomous Hermes agent, with its own identity and context.

Concretely, a profile named coder has:

• ~/.hermes/profiles/coder/config.yaml — full configuration (model, tools, settings)
• ~/.hermes/profiles/coder/.env — API keys and bot tokens
• ~/.hermes/profiles/coder/SOUL.md — agent personality and instructions
• ~/.hermes/profiles/coder/sessions/ — conversation history
• ~/.hermes/profiles/coder/memory/ — persistent memory (MEMORY.md, USER.md)
• ~/.hermes/profiles/coder/skills/ — installed skills
• ~/.hermes/profiles/coder/state.db — state database

The default profile is simply ~/.hermes itself — no migration is needed, your existing installation continues to work identically.

HERMES_HOME and data organization

The profile system relies on the HERMES_HOME environment variable. This variable determines the root directory where Hermes stores all its configuration and data. Over 119 files in the codebase resolve paths via get_hermes_home(), ensuring that all Hermes state is automatically scoped to the active profile.

When you run coder chat, the wrapper script sets HERMES_HOME=~/.hermes/profiles/coder before launching Hermes. This approach is elegant because:

• Zero code duplication: the same Hermes binary serves all profiles
• Total isolation: config, sessions, memory, skills, logs, and cron jobs are separated
• Simplicity: a single environment variable change is all it takes

It's important to distinguish HERMES_HOME from the terminal working directory. Tool execution starts from terminal.cwd (or the launch directory), not from HERMES_HOME. A profile does not sandbox the filesystem — the agent retains the same access as your user account.

Using a specific profile: hermes -p

Three methods let you target a profile:

Command aliases

Each profile automatically creates an alias in ~/.local/bin/:

coder chat              # chat with the coder agent
coder setup             # configure coder's settings
coder gateway start     # start coder's gateway
coder doctor            # check coder's health
coder skills list       # list coder's skills
coder config set model.default anthropic/claude-sonnet-4

The alias works with every Hermes subcommand — it's hermes -p coder under the hood.

The -p flag

You can also target a profile explicitly:

hermes -p coder chat
hermes --profile=coder doctor
hermes chat -p coder -q "hello"   # works in any position

Sticky default with hermes profile use

hermes profile use coder
hermes chat          # now targets coder
hermes tools         # configures coder's tools
hermes profile use default   # switch back

The CLI always shows the active profile: coder ❯ in the prompt and Profile: coder in the startup banner.

Concrete use cases

Work vs Personal

The most common case: separate a professional agent from a personal one.

# Professional agent — premium model, enterprise Slack gateway
hermes profile create work --clone
work setup
work config set model.default anthropic/claude-sonnet-4

# Personal agent — economical model, Telegram gateway
hermes profile create personal --clone
personal setup
personal config set model.default google/gemini-2.0-flash

Each agent has its own API keys in its .env, its own personality in SOUL.md, and its own memory. Work sessions never contaminate personal conversations.

Dev vs Production

For developers deploying Hermes agents:

# Development environment
hermes profile create dev
dev config set model.default google/gemini-2.0-flash  # fast, cheap model

# Production environment
hermes profile create prod --clone --clone-from dev
prod config set model.default anthropic/claude-sonnet-4  # premium model
prod config set gateway.log_level info  # detailed logging

The --clone --clone-from dev command copies the dev profile's configuration as a base, then you adjust production-specific parameters.

Multi-project

One profile per active project:

hermes profile create react-app
hermes profile create python-api
hermes profile create infra-terraform

# Each profile starts in its own folder
react-app config set terminal.cwd /home/user/projects/react-app
python-api config set terminal.cwd /home/user/projects/python-api
infra-terraform config set terminal.cwd /home/user/projects/infra

With terminal.cwd configured, each agent starts directly in the right project context.

Per-profile configuration

Each profile has its own configuration files, modifiable independently.

Model and provider

coder config set model.default anthropic/claude-sonnet-4
researcher config set model.default google/gemini-2.0-flash
writer config set model.default openai/gpt-4o

Personality via SOUL.md

echo "You are a strict, concise coding assistant.
Respond only in code with minimal comments." > ~/.hermes/profiles/coder/SOUL.md

echo "You are an academic researcher.
Always cite your sources and remain objective." > ~/.hermes/profiles/researcher/SOUL.md

Tools and skills

Each profile can enable or disable specific tools via config.yaml. Skills are installed per profile:

coder skills install github-pr-review
researcher skills install web-search-deep

The hermes update command syncs new bundled skills to all profiles automatically, without overwriting user-modified skills.

Session and memory isolation

Isolation is the fundamental principle of profiles. Each profile maintains:

• Independent sessions: coder's conversation history is invisible to researcher
• Separate memory: MEMORY.md and USER.md are unique to each profile
• Distinct state: the state.db database (cron jobs, plugins, capabilities) is isolated
• Separate logs: each profile has its own log files

This isolation allows specializing each agent without risk of cross-contamination. A research agent accumulating knowledge on a topic won't interfere with the coding assistant. For more on memory, see our guide on persistent memory.

Profiles and gateways

Each profile runs its own gateway as a separate process with its own bot token:

coder gateway start       # starts coder's gateway
assistant gateway start   # starts assistant's gateway (separate process)

Different bot tokens

Each profile having its own .env file, you configure distinct tokens:

# Coder bot token (Telegram)
echo "TELEGRAM_BOT_TOKEN=123456:ABC-coder" > ~/.hermes/profiles/coder/.env

# Assistant bot token (Discord)
echo "DISCORD_BOT_TOKEN=xyz-789-assistant" > ~/.hermes/profiles/assistant/.env

Token locks

If two profiles accidentally use the same bot token, the second gateway is blocked with a clear error message identifying the conflicting profile. This safety mechanism works for Telegram, Discord, Slack, WhatsApp, and Signal.

Persistent services

coder gateway install       # creates hermes-gateway-coder systemd service
assistant gateway install   # creates hermes-gateway-assistant service

Each profile gets its own systemd/launchd service. They run independently and can be managed separately. For more on gateway configuration, see our article on the multi-platform gateway.

Advanced tips

Sharing skills between profiles via external_dirs

If you develop a custom skill you want to use across multiple profiles, use external_dirs in config.yaml:

# In ~/.hermes/profiles/coder/config.yaml
skills:
  external_dirs:
    - /home/user/shared-skills/common
    - /home/user/shared-skills/code-review

Multiple profiles can then access the same custom skills without duplication. For a deep dive into the skills system, see our Skills system guide.

Profiles and Honcho (multi-agent)

When Honcho is enabled, --clone automatically creates a dedicated AI peer for the new profile while sharing the same user workspace. Each profile builds its own observations and identity.

Export and import profiles

hermes profile export coder          # export to coder.tar.gz
hermes profile import coder.tar.gz   # import from archive

Ideal for backups or transferring a configured agent between machines.

Best practices for profile organization

1. Name clearly

Use short but descriptive names: work, personal, react-app, research-agent. Avoid generic names like test1 or bot2.

2. Profiles vs workspaces vs sandboxing

Understand the difference:

• Profile: Hermes state directory (config, memory, sessions)
• Workspace: terminal command working directory (terminal.cwd)
• Sandbox: filesystem access limitation (profiles do not sandbox)

If you want a profile to start in a specific folder, configure terminal.cwd explicitly.

3. Document each profile

Add a descriptive header in each profile's SOUL.md to remind yourself of its purpose:

# Profile: Coder Agent
## Usage: React/TypeScript development
## Model: anthropic/claude-sonnet-4
## Gateway: Slack (#dev-bot)
## Last updated: 2025-01-15

4. Update regularly

hermes update updates the code (shared) and syncs skills to all profiles. Do this regularly to benefit from improvements.

5. Clean up unused profiles

hermes profile list     # view all profiles
hermes profile delete old-project  # remove an obsolete profile

Concrete multi-profile setup examples

Full-stack developer setup

# Main profile for frontend development
hermes profile create frontend --clone
frontend config set model.default anthropic/claude-sonnet-4
frontend config set terminal.cwd /home/dev/projects/frontend
echo "React/TypeScript expert. Focus on UI/UX and performance." > ~/.hermes/profiles/frontend/SOUL.md

# Backend profile
hermes profile create backend --clone
backend config set model.default google/gemini-2.0-flash
backend config set terminal.cwd /home/dev/projects/backend

# DevOps profile
hermes profile create devops --clone
devops config set terminal.cwd /home/dev/infrastructure
devops gateway start  # dedicated monitoring gateway

Researcher/writer setup

# Research agent with powerful model
hermes profile create researcher
researcher setup
researcher config set model.default anthropic/claude-sonnet-4
researcher skills install web-search-deep arxiv-reader
echo "Rigorous academic researcher. Always cite sources." > ~/.hermes/profiles/researcher/SOUL.md

# Writing agent with creative personality
hermes profile create writer
writer setup
writer config set model.default openai/gpt-4o
echo "Creative and engaging writer. Adapt tone to target audience." > ~/.hermes/profiles/writer/SOUL.md

Migrating between profiles

Copying data between profiles

# Copy memory from one profile to another
cp ~/.hermes/profiles/coder/memory/MEMORY.md ~/.hermes/profiles/new-coder/memory/

# Copy specific sessions
cp ~/.hermes/profiles/coder/sessions/2025-01-15*.json ~/.hermes/profiles/new-coder/sessions/

Clone with adjustment

# Clone config but start fresh on memory
hermes profile create new-project --clone --clone-from coder

The --clone option copies config.yaml, .env, and SOUL.md but gives blank sessions and memory. The --clone-all option copies absolutely everything — useful for backups or forking an agent that already has context.

Advanced profile management

hermes profile list              # list all profiles with status
hermes profile show coder        # detailed info for one profile
hermes profile rename coder dev-bot   # rename (updates alias + service)
hermes profile export coder      # export to archive
hermes profile import coder.tar.gz    # import from archive
hermes profile delete coder      # delete a profile (confirmation required)

Note that the default profile (~/.hermes) cannot be deleted — to remove everything, use hermes uninstall.

Command completion

For Bash or Zsh users, enable auto-completion:

# Bash
eval "$(hermes completion bash)"

# Zsh
eval "$(hermes completion zsh)"

Add the appropriate line to your ~/.bashrc or ~/.zshrc for persistent completion. Completion works for profile names after -p, profile subcommands, and all top-level commands.

Conclusion

Hermes Agent's profile system transforms a single CLI tool into a complete multi-agent platform. In just a few commands, you can create specialized agents — each with its own model, personality, memory, and gateway — that coexist on your machine without interfering with each other.

Key takeaways:

• A profile = an isolated directory: config, memory, sessions, skills — everything is separated
• Three targeting methods: command alias, -p flag, or profile use for the default
• Varied use cases: work/personal, dev/prod, multi-project, research/writing
• Independent gateways: each profile has its own process and bot token
• Isolation without sandboxing: profiles separate Hermes state but not filesystem access

To go further, check out our articles on model configuration, sessions and context, persistent memory, the Skills system, and mastering the CLI.