Hermes Agent profiles: run several agents on one machine

Updated 8 min read

A Hermes Agent profile is a separate Hermes home directory with its own config, API keys, SOUL.md, memory, sessions, skills, cron jobs and gateway. hermes profile create coder makes one and installs a coder command to run it, so a single install can run a coding agent, a research agent and a personal bot side by side without mixing their state. This guide covers creating and running profiles, giving each one a role, and sharing context between them without merging their memories. It follows the current Nous Research docs and the hermes CLI (v0.42.5) we run on a Mac.

What is a Hermes Agent profile?

The default profile is ~/.hermes itself. Every named profile lives in ~/.hermes/profiles/<name>/ and holds its own:

  • config.yaml: model, provider, toolsets and every other setting
  • .env: API keys and bot tokens
  • SOUL.md: the agent’s identity and voice
  • memories/MEMORY.md and memories/USER.md: what the agent has learned, and what it knows about you
  • sessions, the state database, skills, cron jobs, logs and gateway state

It works through one environment variable. The coder wrapper sets HERMES_HOME=~/.hermes/profiles/coder before it launches hermes, and everything Hermes reads or writes resolves from there. The code is installed once and shared, so hermes update updates every profile at once and syncs newly bundled skills into each of them (skills you have edited are never overwritten).

A profile is the persistent home; an agent is a running process using it. One rule matters more than the rest: never point two running agents at the same profile. Both write memory automatically, and each loads the other’s writes into its system prompt at the next session start.

What does a profile not isolate?

Profiles separate Hermes state. They are not a sandbox, and three things are shared by default:

  • The filesystem. On the default local terminal backend the agent has your user account’s file access in every profile. Set an absolute terminal.cwd to choose where a profile starts; a real boundary needs a container backend.
  • Your HOME. Tool subprocesses keep your real home directory, so git, ssh and gh use the same credentials in every profile. terminal.home_mode: profile gives a profile its own HOME, where you then set up its keys and logins.
  • OAuth logins. Anthropic, OpenAI Codex and xAI logins are read from the root ~/.hermes/auth.json, not copied into clones. hermes -p <name> auth add <provider> gives a profile its own. API keys in .env are per profile.

How do I create a Hermes Agent profile?

From hermes profile create --help:

usage: hermes profile create [-h] [--clone] [--clone-all]
                             [--clone-from SOURCE] [--no-alias] [--no-skills]
                             [--description DESCRIPTION]
                             profile_name

Names are lowercase; the docs’ own examples include hyphens, such as personal-bot. The ways to start:

hermes profile create research                 # blank, seeded with bundled skills
hermes profile create research --no-skills     # blank and empty
hermes profile create work --clone             # copy the active profile's setup
hermes profile create work --clone-from coder  # copy a named profile's setup
hermes profile create spare --clone-all        # full copy, minus history

What each copy carries:

Option Copies Starts empty
(none) bundled skills everything else
--clone config.yaml, .env, SOUL.md, skills; the docs add MEMORY.md and USER.md sessions, state database, cron jobs
--clone-all config, keys, persona, all memories, skills, plugins session history, checkpoints, cron jobs

Cron jobs are never cloned, because a clone would run every job a second time. The docs also say clones leave messaging channels (bot tokens, allowlists) behind, since one bot belongs to one profile. Our v0.42.5 help does not list the --clone-channels flag the docs describe, so check the new profile’s .env before starting its gateway.

Then configure it:

research setup        # its own model, keys and gateway tokens
research chat

How do I run and switch between profiles?

Every profile gets a wrapper at ~/.local/bin/<name> that accepts any hermes subcommand. These are equivalent:

research chat
hermes -p research chat
hermes --profile=research chat

To make a profile the default for plain hermes commands, the way kubectl config use-context works:

hermes profile use research
hermes profile use default    # switch back

The prompt shows the active profile (research ❯), and so does the startup banner. hermes profile show <name> prints one profile’s details, and eval "$(hermes completion zsh)" adds tab completion for profile names after -p.

How do I run a gateway for each profile?

Each profile runs its own gateway process with its own bot token, and each gateway runs that profile’s cron jobs.

coder gateway install      # LaunchAgent ai.hermes.gateway-coder.plist on macOS
coder gateway start
research gateway install
research gateway start
hermes gateway list        # every profile and its gateway status

On Linux the service is hermes-gateway-<name>.service. If two profiles hold the same Telegram, Discord, Slack, WhatsApp or Signal token, the second gateway refuses to start and names the profile that already has it. Make one bot per profile.

The current docs also describe a single multiplexing gateway that serves every profile from one process (gateway.multiplex_profiles: true), with profile_routes to send different channels of one shared bot to different profiles. That is newer than the v0.42.5 CLI we run, so check hermes gateway --help on your version before you plan around it.

How do I give each profile a role?

A role is four settings, all per profile:

  1. SOUL.md for identity and voice. Hermes loads it only from the profile’s own home, never from the working directory, as the first block of the system prompt.
  2. A model that fits the job: coder config set model.default <model>.
  3. A working directory with terminal.cwd, so the coding profile starts in its repository.
  4. Skills for the procedures that role needs. The Hermes Agent skills guide covers installing and sharing them.

A short SOUL.md does more than a long one:

You are the research agent. You read sources, check claims against the
original, and write findings with links. You do not change code.
When a task needs code, say so and stop.

Keep facts out of SOUL.md. The docs are clear that SOUL.md and memory never feed each other: SOUL.md is who the agent is, USER.md is who you are, MEMORY.md is what it has learned. If you route work between profiles with hermes kanban (a task board for several profiles), give each one a description so the orchestrator knows its role:

hermes profile create research --description "Reads sources and docs, writes findings."
hermes profile describe coder --text "Writes and tests code in the main repo."

How do I share context between profiles without merging their memories?

Each profile’s memory is two short files loaded at session start. Merging them gives every agent the others’ notes and none of its own focus. Share context in layers instead:

  • Shared rules: one context file. Hermes loads one project context file per session from the working directory, first match wins: .hermes.md, AGENTS.override.md, AGENTS.md, CLAUDE.md, .cursorrules. Profiles that start in the same directory read the same file. The AGENTS.md guide covers what to put in it.
  • Shared procedures: one skills folder. Several profiles can read skills from a common folder; the setup is in the skills guide.
  • Shared facts about you: an external memory provider. hermes memory configures one. With Honcho, the docs say each cloned profile gets its own peer in a shared user workspace, so profiles build their own observations about the same person.
  • Shared knowledge: a wiki over MCP. Decisions, research, how systems work: too large for MEMORY.md, and not a procedure.
  • Handoffs: the kanban board. One profile finishes a task and the next picks it up.

Context engineering covers the same split for agents in general.

How we run several profiles on one Mac

We run several Hermes profiles from one install on one Mac. Each has its own SOUL.md, memory, skills and gateway, so each has its own bot and its own scheduled jobs. Two things are shared by all of them:

  • One context file that every profile loads. It holds the house rules: how to write, which tools to prefer, where shared knowledge lives. It changes rarely, and since every profile loads it in every session, we keep it short.
  • One wiki over MCP. Anything more than one profile needs goes there, written once and read by all of them.

The split we follow: who the agent is goes in its SOUL.md, what only that agent needs stays in its memory, rules for everyone go in the shared file, and knowledge for everyone goes in the wiki. Each profile’s memory then stays about its own job.

Share it with your other agents

Dexio is a hosted wiki that agents read and write over MCP, and it is the shared wiki in our setup. Every profile connects to it the same way, and so can Claude Code, Codex, Cursor and OpenClaw, so what one agent learns is there for the rest. You see what your agents know as a graph of linked pages at app.dexio.wiki. It is open source (AGPL-3.0) and free for one person.

To connect a profile, ask it to follow https://dexio.wiki/agents.md. Every profile can share one API key, and each change records the agent that made it, so a page’s history shows which profile wrote what. The per-profile steps are in the Hermes Agent memory guide, and the idea behind a wiki agents maintain is in LLM wiki.

How do I move, share or delete a profile?

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 published distribution
hermes profile update research-bot              # keeps your memories and .env
hermes profile delete coder

A distribution is a git repository carrying the SOUL.md, config, skills, cron jobs and MCP connections; credentials, memories and sessions stay on each machine. delete stops the gateway, removes its service and wrapper, and deletes the profile’s data. The default profile cannot be deleted.

FAQ

Do Hermes Agent profiles share memory? No. Each has its own MEMORY.md, USER.md and session history, and a profile never falls back to another’s memory.

Can two profiles use one Telegram bot? Not as two gateways: the token lock stops the second one. The docs’ multiplexing gateway can route chats from one bot to different profiles, on versions that have it.

Is a profile the same as a Chrome profile in Hermes? No. The hermes-plugin-chrome-profiles plugin switches Hermes’s browser tools to a named Chromium-family browser over CDP, so the agent uses that browser’s logged-in sessions. It is unrelated to Hermes profiles.

How do I set up Hermes before adding profiles? Start with the Hermes Agent setup guide. If you are deciding between Hermes and OpenClaw for several agents, see Hermes Agent vs OpenClaw.

Sources

Ask a question

Ask anything about Dexio.

About
We reply by email.