Hermes Agent profiles: several independent agents from one install

What a profile is, and what it is not

Hermes keeps everything it knows in one home directory, ~/.hermes. A profile is simply another home directory. Each one sits under ~/.hermes/profiles/ and holds its own:

• config.yaml: the model, provider, tools and every other setting;
• .env: API keys and bot tokens;
• SOUL.md: the agent’s personality and standing instructions;
• memory, sessions, skills, scheduled jobs, logs and the state database.

The install you already have is the default profile. It is ~/.hermes itself, so nothing needs migrating: existing setups carry on exactly as before. Under the hood Hermes points the HERMES_HOME environment variable at the profile’s directory before it starts. Most Hermes state follows that directory. The exception is provider keys: if a profile has none of its own for a provider, it can fall back to the keys in the default profile’s auth.json.

Be clear about the limits. A profile is a boundary for Hermes’s own state, not a security sandbox. On the default local terminal backend the agent still has the same access to your files as your user account does, whichever profile it runs under. A profile is also not the same as a working folder: the folder where terminal commands start is a separate setting, terminal.cwd, and you should set it to an absolute path in each profile that should start in a particular project.

Two related things get confused with profiles. A subagent is a short-lived helper that the agent spawns for one task with a fresh conversation; it is not a profile. And in the Hermes desktop app, Bot Mode shows selected profiles as a roster of named bots with avatars, which is a way of presenting profiles rather than a different thing. The desktop app is a separate way to use Hermes.

Create a profile, with or without a copy of an existing one

The shortest path is two commands:

hermes profile create coder
coder setup

hermes profile create makes the directory, adds the bundled skills and installs a command named after the profile in ~/.local/bin. From then on coder chat, coder setup and coder doctor all run against that profile; the command is shorthand for hermes -p coder. Names are 1 to 64 characters, start with a lowercase letter or digit, and otherwise use lowercase letters, digits, hyphens or underscores. A handful are reserved (hermes, default, test, tmp, root, sudo). Add --no-alias to skip the command, or --no-skills to install only the essential hermes-agent skill.

You have three ways to start, depending on how much you want to inherit:

• Blank (hermes profile create mybot). Starts with fresh state, but copies the model settings of the profile you run the command from. Run setup to review the model and keys.
• Clone the setup (--clone, or --clone-from coder to pick the source). Copies the config, the API keys in .env, SOUL.md, skills, the two curated memory files (memories/MEMORY.md and memories/USER.md) and any external-memory settings. It does not copy auth.json, so check the new profile’s login and memory settings before using it. Sessions, the state database and scheduled jobs start empty. Handy for a second agent that should use the same model but a different role.
• Clone everything (--clone-all). A full working copy of config, API keys, memories, skills and plugins, but not session history or scheduled jobs. Scheduled jobs stay behind on purpose: a copy would run every job twice. Sign-ins that use a single-use login (such as a ChatGPT or Claude subscription) are not copied; the clone uses the default profile’s login, or you can sign it in separately.

One more option matters if you use Hermes’s kanban board to hand work between agents: --description records what the profile is good at, and the orchestrator uses it to route tasks by role instead of by name alone. You can set it later with hermes profile describe.

New to Hermes? Start with how to install Hermes Agent, then come back here.

List, switch, rename and delete profiles

There are two ways to point a command at a profile, and you can mix them freely.

# one command, one profile (works in any position)
hermes -p coder chat
hermes chat -p coder -q "hello"

# change the default so plain commands target coder
hermes profile use coder
hermes profile use default

hermes profile use sets a sticky default, much like switching a context in other command line tools. The interactive prompt shows the active profile (coder ❯), and hermes profile on its own prints the current name, path, model and gateway status.

The management commands, all verified against the profile subcommands in the source:

hermes profile list
hermes profile show coder
hermes profile describe coder --text "Reviews pull requests"
hermes profile rename coder dev-bot
hermes profile delete dev-bot

hermes profile delete stops that profile’s gateway, removes its service and its command, and deletes its data. It asks you to type the profile name first; add --yes to skip the question. That is permanent, so export anything you want to keep (see the sharing section below). The default profile cannot be deleted, and it cannot truly be renamed, but renaming it sets a display name that appears in lists and in the apps.

When you run hermes update, the code is updated once and new bundled skills are synced into every profile. Profiles created with --no-skills only receive the essential skills, and skills you changed yourself are not overwritten.

One bot per profile: gateways and tokens

Each profile has its own .env, so each can be connected to its own messaging bot. Give your support agent one Telegram bot and your personal agent another by putting a different token in each profile, or by running hermes -p name setup inside the profile. The rule to remember is that a bot token belongs to exactly one profile. Two profiles polling the same Telegram token fight over it.

How the gateway runs has changed, and older write-ups describe the previous model. In 0.21.5 the default is a single gateway process, started from the default profile, that serves every profile on the machine. It brings up each profile’s channels with that profile’s own credentials, and each message runs under the profile it belongs to: that profile’s settings, skills, memory, personality and keys. WhatsApp is the exception: it is owned by the default profile, so set it up there. The setting behind it is gateway.multiplex_profiles, which is on unless something blocks it. In practice:

hermes gateway install
hermes -p coder gateway stop
hermes -p coder gateway start
hermes -p coder gateway restart

The first command installs the one host gateway. After that, stop on a named profile parks just that profile’s bots while the others carry on, start brings them back, and restart reconnects them with the current configuration. Trying to install or start a separate gateway for a named profile is refused by default, with a message that points you to the host gateway. If you already ran one gateway per profile, hermes gateway migrate --multiplex folds them into one. There is a temporary opt-out, gateway.standalone: true in a profile’s own config.yaml, which the Hermes documentation describes as a stopgap rather than a design to build new setups on.

If two profiles are configured with the same token, a running gateway logs the problem and refuses the duplicate, and the check at startup or migration treats it as a blocker, so fix it before you turn multiplexing on. Cloning a profile avoids this by default: bot tokens, allowlists and the channel sections of the config are left out of every clone unless you pass --clone-channels. Channel setup is covered step by step in the Hermes Agent Telegram guide.

Inside the official Docker image, creating a profile registers a gateway service slot in a stopped state. When the container restarts, named slots stay stopped and their saved running state is passed to the main gateway, which serves the profiles. See running Hermes Agent in Docker for the container setup.

Share a profile: export files and distributions

A profile you have tuned is worth moving or handing on. Hermes has two routes, and they suit different jobs.

• Export file. hermes profile export coder creates a timestamped .tar.gz archive and prints where it saved it. The recipient runs hermes profile import /path/to/the-export.tar.gz. The export leaves out .env and auth.json and redacts recognised secrets in text files. Memory, sessions and databases can still hold private information, so inspect the archive before sending it to anyone outside your team.
• Distribution. The profile is published as a git repository with a distribution.yaml manifest. Others install it with hermes profile install github.com/you/research-bot --alias and pull new versions with hermes profile update research-bot. The repository carries the personality, config, skills, scheduled jobs and tool connections; credentials, memories and sessions stay on each person’s own machine, and an update keeps their memories and .env. It suits an agent you keep improving, or the same agent deployed on several machines.

One warning from the documentation applies to authors: the file exclusions are applied by the installer, not by git. Before the first commit, add a .gitignore that excludes .env, auth.json, memories/, sessions/ and the database files, or you can publish secrets by accident.

Business examples: one agent per role, or one per client

Profiles fit best where the work divides cleanly and you want each part to stay focused and keep its own history. Some patterns that make sense:

• One agent per role. An inbox-and-calendar assistant, a research agent that reads sources and writes summaries, and a drafting agent with a house style in its SOUL.md. Each has the skills it needs and nothing else, which keeps prompts short and behaviour predictable.
• One agent per channel. A public-facing assistant on one Telegram bot with a restricted set of tools, and an internal one on a different bot. Separate bots keep conversations apart, but if the public agent must not reach your files, run it as a separate user or in a container.
• A trial and a production copy. Clone your working profile, change a model or a skill in the clone, and compare before you touch the real one.
• One agent per client, with care. Separate memory and a separate personality per client is a reasonable use. But a profile does not isolate files, and by default the tools an agent runs share your normal user account, including its git and SSH credentials. If the clients’ data must not mix, a profile alone is the wrong boundary: use a separate user, container or machine per client. Hermes can give each profile its own tool home with terminal.home_mode: profile, but then you set up that profile’s credentials yourself.

A sensible approach is one agent per role, adding profiles only when roles start to clash.

When one agent is enough

Most people should start with one agent, and many never need a second. Stay with one when:

• one personality, one set of skills and one memory do the job;
• you only want the agent to hand off a task to a helper, which a subagent does without a profile;
• you would end up copying the same keys and settings into every profile and keeping them in step.

Add a profile when:

• two roles keep interfering, for instance one agent’s memory is full of another’s topics;
• you want a different bot, a different model or a different set of tools for different audiences;
• you want a safe place to try a new skill, prompt or model before it touches the working agent;
• you plan to share an agent with others as an export or a distribution.

Never point two running agents at the same profile. Both write memory on their own and read each other’s writes at the start of the next session, so shared homes drift into something neither of you configured. If two agents need shared knowledge, use an external memory provider instead. There is also a cost: every profile is more to configure, update and back up, and it uses its own model calls. If you are weighing running this yourself against a hosted agent, the self-hosting versus managed hosting comparison lays out the trade-offs.

Hermes Agent profiles on ReadyHermes

ReadyHermes runs a Hermes Agent for you, ready in about 10 seconds, and you work with it from the ReadyHermes workspace. That workspace does not have a screen for creating, switching, cloning or deleting profiles, so do not expect to open a profile list in the app. It does let you connect the free Hermes Desktop app to your assistant from the Channels panel.

What the workspace does give you is one assistant that stays on. The Channels panel connects it to Telegram, WhatsApp, Discord, WeChat or Lark, and changes that restart the assistant take about a minute. If you want separate specialist agents with separate bots, running Hermes yourself, on a laptop, a server or in Docker, is the route the profile commands in this guide are written for. If one dependable assistant that is always on is what you need, a hosted agent fits well; see managed Hermes Agent hosting for what is included.