Profiles — หนึ่ง agent ต่อหนึ่งบทบาทProfiles — One Agent per Role

🤔 If you want one agent for research, another for code and a third for finance — do you have to install Hermes three times?

The previous post — #2 Local Models — connected Hermes Desktop to a model running on your own machine, and the question that follows immediately is one of housekeeping: now that you hold both a paid model and a free one, how do you settle "which work goes to which" without changing models every time you open a new chat, and how do you keep the agent that reads your accounts from carrying memories out of your coding work?

The one-line answer: Hermes calls this a profile, and its definition is very short — "A profile is a separate Hermes home directory" — a second Hermes home with its own config.yaml, .env, SOUL.md, memories, sessions, skills, cron jobs and state database, a complete set each^[1]. This post creates a profile two ways — as a Bot on screen, and with a command in a terminal — then gives it a persona, pins it to a working folder and a model, and moves the whole thing to another machine.

1. What a Profile Is — and What It Is Not

The direct answer first: a profile is a separate Hermes home directory, not a second copy of the program. A named profile lives at ~/.hermes/profiles/<name>/, while the starting profile is ~/.hermes itself, whose internal ID is always default. The docs stress that "No migration needed — existing installs work identically" — nothing you already have needs moving^[1].

The mechanism behind it is a single environment variable, HERMES_HOME. The docs explain that more than 119 files in the codebase resolve their paths through get_hermes_home(), so pointing that variable at a directory moves the whole of Hermes' state with it — config, sessions, memory, skills, the state database, the gateway PID, logs and cron jobs^[1]. And when you create a profile it becomes its own command straight away: create coder and you immediately have coder chat, coder setup and coder gateway start.

What must be separated from the start are the three words people confuse most often. The docs keep them apart in three clean lines^[1]:

• a profile = Hermes' own state directory — config.yaml, .env, SOUL.md, sessions, memory, logs, cron jobs and gateway state
• a workspace, or working directory, = where terminal commands start. It is controlled separately by terminal.cwd — not by the profile's folder
• a sandbox = what limits filesystem access, and the docs put it in bold: "Profiles do not sandbox the agent" — on the default local backend the agent still has exactly the same filesystem access as your user account

The third line is the one I most want readers to hold on to, because "separate profiles" sounds like "separate boxes" and it is not a security boundary. It separates state, not privilege. If you want a real wall you have to go down to the execution backend, which belongs to #7 Safety, Remote & Recovery. The Bot Mode machinery that lets profiles talk to each other is in Hermes #2 Agent Teams, and handing profiles out as git repositories across an organization is in Hermes #10 Desktop & Fleet — today I am staying on one machine, our own.

💡 How far a profile name can go: the command reference says it loosely — "Must be a valid directory name (alphanumeric, hyphens, underscores)"^[2] — while the source is stricter: hermes_cli/profiles.py validates against the regex ^[a-z0-9][a-z0-9_-]{0,63}$ (lower case only) and reserves six names outright — hermes, default, test, tmp, root, sudo^[9]. Names like research, coder and finance are always safe.

2. What a Profile Owns, and What It Shares

The direct answer: a profile owns everything that is Hermes state — config, keys, persona, memories, sessions, skills, cron and the database — but it does not own three things that stay shared across the machine: the OAuth login at the root, the operating system's HOME, and the Hermes code itself. This table is the full list.

The bottom three rows are the three I see misread most often, and each is misread differently. The auth.json row is a feature, deliberately designed — you sign in once and every profile is covered, with no second subscription to buy. The HOME row is a tradeoff the docs state plainly: "host profiles share normal user-level CLI state by default" — different profiles still share one ~/.ssh and one ~/.gitconfig. If you genuinely need a different git identity per profile you must turn on terminal.home_mode: profile and then initialize ~/.ssh, ~/.gitconfig and ~/.config/gh again inside that profile's own {HERMES_HOME}/home^[7]. And the code row is simply the explanation for why ten profiles do not cost ten times the disk.

3. Procedure A — Create a Bot on Screen

The direct answer: in Hermes Desktop you never have to hunt for a menu called "profile", because Bot Mode makes one Bot exactly one profile. The docs say it outright — "There is no new primitive to learn: a Bot is a Hermes profile" and "Bot Mode is a UI over that primitive"^[3]. Creating a Bot is creating a profile. These are the nine steps.

1. Open the Bots tab, which sits next to Sessions in the left sidebar — Bot Mode ships built into the app and is on already, nothing to install, and a Routines tile docks beside the conversation while that tab is active^[3]
2. Hit New Agent in the roster. The quick path is three fields — Name, Title, Description — and the Bot exists in seconds, introducing itself as the first message of its own Bot Chat^[3]
3. Write the Description as though writing for someone else, not as a note to yourself, because the teammate roster — "names and roles from each profile's title/description" — is part of every Bot Chat's system prompt, so other Bots know who does what before choosing a recipient^[3]. The same description is also what the kanban orchestrator routes on, "based on role instead of profile name alone"^[2]
4. Open the Advanced disclosure and choose between Clone from an existing profile, which starts from another Bot's config, skills, SOUL and memory, and Fresh profile, which starts clean; Create empty skips the bundled skills entirely^[3]
5. Set the Model & provider pin to give the Bot a model of its own. The docs say any provider/model pair Hermes knows about works and that different Bots can run different models side by side — "Leave it unset to inherit from the launch profile" if you would rather it followed the profile you launched from^[3]
6. Fill in the Custom SOUL.md — this Bot's persona and standing instructions (how it is actually used is section 5)
7. Tick the per-skill, per-toolset and per-MCP-server enablement down to only what this specialist really needs. Shared keys is on by default — the new Bot shares one OAuth/token pool with the main profile so that a refresh on one side cannot invalidate the other^[3]
8. Save, then click the Bot's row to land in its Bot Chat — a persistent conversation created and pinned the moment the Bot was born, so a row click always returns you to the same room^[3]
9. Confirm from a terminal with hermes profile list — the Bot you just made appears as one ordinary profile row, and hermes -p <bot> chat opens that very same agent. This is the CLI parity table the Bot Mode docs publish^[3]

One version fact worth stating precisely: Bot Mode is a bundled desktop plugin that is on by default, and the release that announced this officially is Hermes Agent v0.21.0 (tag v2026.8.31), "The Pantheon Release", which reads "Bot Mode is now a bundled, default-on part of the desktop app: every agent profile gets a name, a deterministic avatar face"^[10]. If you would rather not use it, switch it off under Settings → Plugins → Bots; the docs say the roster, the Routines pane and the composer middleware unregister live with no restart, and that "Your profiles, sessions, and cron jobs are untouched either way; Bot Mode never owns your data, it only renders it" — your profiles do not go anywhere, because Bot Mode is only the screen that draws them^[3].

4. Procedure B — The Same Thing from the Terminal

The direct answer: one command creates it, and Hermes throws in an alias that becomes a new shell command immediately. Before walking the steps, I checked the complete subcommand set against the reference page on the day of writing — there are exactly thirteen: list, use, create, describe, delete, show, alias, rename, export, import, install, update, info^[2]. These seven steps use only the first six.

1. Create it: hermes profile create research --description "Reads source code and external docs, writes findings." — you get the profile plus an alias called research. The description is persisted in <profile_dir>/profile.yaml, so it survives reboots and is shared with the gateway^[2]
2. Check that it exists: hermes profile list — every profile, with the active one marked by a *; the fuller table also carries Model, Gateway, Alias and Distribution columns^[2][4]
3. Talk to it: hermes -p research chat, or the short alias research chat. The alias is written to ~/.local/bin/research, and the docs say plainly that "it's just hermes -p <name> under the hood"^[1]. The -p flag works in any position, e.g. hermes chat -p research -q "hello"
4. Make it the sticky default: hermes profile use research sends every bare hermes command to that profile. The docs compare it to "Like kubectl config use-context", and hermes profile use default switches back^[1]
5. See where you are: the prompt becomes research ❯ instead of a bare ❯, the startup banner reads Profile: research, a bare hermes profile prints the name, path, model and gateway status, and typing /profile in a chat returns the active profile name and its home directory^[1][8]
6. Inspect one in detail: hermes profile show research prints Path, Model, Gateway, the Skills count, whether .env and SOUL.md exist, and where the Alias lives^[2]
7. Make it usable: research setup to enter API keys and pick a model — or, if you are on Nous Portal, the shortcut the docs recommend: "Quickest setup: run hermes setup --portal inside the new profile to wire up models + tools at once"^[1]

Cloning instead of starting blank

If the new profile should look like one you already have, there are three levels of copying. I checked what each flag means against the table on the command reference page, and the important one is that --no-skills refuses to combine with any of the three clone flags, because cloning would drag the skills back in regardless^[2].

# copy config.yaml, .env, SOUL.md and skills from the current profile — fresh sessions and memory
hermes profile create work --clone

# copy everything except per-profile history (sessions, state.db, backups, state-snapshots, checkpoints)
hermes profile create backup --clone-all

# name the source explicitly instead of using the current profile
hermes profile create work --clone-from coder
hermes profile create work-backup --clone-from coder --clone-all

# an empty profile with no bundled skills — writes a .no-bundled-skills marker so updates don't re-seed
hermes profile create orchestrator --no-skills --description "Coordinates the board; does not implement."

5. Persona, Folder and Model

The direct answer: the three things that make a profile genuinely a role live in three different places — the persona in a SOUL.md at the profile root, the working folder in the terminal.cwd key of config.yaml, and the model in the model.default key, settable both from the command line and from the screen.

SOUL.md — the persona

The Personality page describes SOUL.md as the agent's primary identity, occupying the first slot of the system prompt — "It occupies slot #1 in the system prompt, replacing the hardcoded default identity". Hermes loads this file only from HERMES_HOME and does not look in the working directory you launched from, which is exactly why the persona belongs to the profile rather than to the project^[6]. Two things follow. First, the content goes into the prompt word for word, but only after a scan — "that content is injected verbatim after security scanning and truncation" — and the docs state that the file "is scanned like other context-bearing files for prompt injection patterns before inclusion", so write persona and voice into it rather than strange meta-instructions^[6]. Second, the Profiles page warns that edits to SOUL.md "take effect cleanly on a new session" — a session left open may still be running on the old prompt^[1].

# persona: SOUL.md at the profile root
echo "You are a focused coding assistant." > ~/.hermes/profiles/coder/SOUL.md

# working folder: terminal.cwd must be an absolute path
coder config set terminal.cwd /absolute/path/to/project

# model: this profile's default
coder config set model.default anthropic/claude-sonnet-4

Working folder and model

The working folder matters more than people expect, because the docs warn that cwd: "." on the local backend means "the directory Hermes was launched from", not the profile's directory^[1]. If you want a profile to start in one project every time, write the absolute path in. And there is one more line I am fond of: "Asking the model 'what directory are you in?' is not a reliable isolation test" — do not ask the agent where it is, set terminal.cwd explicitly instead.

# ~/.hermes/profiles/coder/config.yaml — the same three settings as YAML
terminal:
  backend: local
  cwd: /absolute/path/to/project
  home_mode: auto     # auto | real | profile — the subprocess HOME policy

For the model, if you prefer the screen, Hermes Desktop has a more direct route: the docs say Settings → Model is the only place that writes the real default — "That 'main' model is your per-profile global default — it's what new chats, crons, subagents, and auxiliary tasks start from, and it's the only place that writes it" — and repeat that "Each profile keeps its own default"^[5]. What to watch out for is that the model picker in the composer is not the default — the docs write that "The composer picker is sticky UI state and never touches your default"; it is remembered per device and never written into the profile. And once you have two or more profiles, the config-backed settings pages — Model, Workspace, Safety, Memory & Context, Voice, Chat, Advanced and Tools & Keys — grow an Applies to chip row at the top that selects which profile your edits target. The default selection follows the active profile, and the row is hidden entirely when there are fewer than two profiles^[5].

💡 /personality is neither a profile nor a SOUL: the docs separate them in a single line — "SOUL.md = baseline voice" against "/personality = temporary mode switch". It is a session-level overlay that temporarily supplements that conversation's system prompt; it does not change the profile's durable identity^[6]. Reach for the wrong one and you will wonder why the persona vanished when you opened a new chat.

6. Move a Profile to Another Machine

The direct answer: hermes profile export packs a whole profile into a single .tar.gz with auth.json and .env always excluded, and hermes profile import at the other end installs it as a new profile — it refuses to overwrite an existing one, and it will not import as the name default^[2].

# from the CLI — auth.json and .env are always excluded
hermes profile export research
hermes profile export research -o ./research.tar.gz
hermes profile import ./research.tar.gz --name research

# the same two commands in chat (CLI, TUI, Desktop)
/export research -o ~/Desktop/research.tar.gz
/import ~/Downloads/research.tar.gz --name research-2

# always read the archive before you send it to someone
tar -tzf research.tar.gz | less

That last line is not a ritual. The Profile Distributions page raises a caution box saying an export is "a snapshot of your profile, not a curated release" and that, unlike a distribution, it can carry memories/, sessions/ and USER.md along with it, because "Credentials are filtered by filename; content is not" — the filter reads names, not contents. And for a named profile, "A named profile copies the whole directory minus auth.json / .env", so state.db, logs and caches ride along too and the file can get big^[4]. On the Desktop there are three doors onto the same thing: ⌘K → Export profile…, a right-click on a profile square in the rail → Export profile…, or the import button beside the rail's +. A desktop export adds a desktop.json carrying your skin, light/dark mode, custom themes, the profile's rail color and your window layout^[4][5].

A .tar.gz suits a one-time handoff or a move between your own machines. But for an agent you intend to keep shipping new versions of to a team or a whole organization, Hermes has the other path: a profile distribution, which packages the profile as a git repository with a distribution.yaml, so recipients run hermes profile install and later hermes profile update to pull only what the distribution owns, without touching their own memories/, sessions/ or .env^[4]. I wrote that up from the organization's side in Hermes #10 Desktop & Fleet — including the distribution-owned versus user-owned line and why that repo belongs under branch protection — so I will not teach it twice.

7. Rules That Save You Pain

The direct answer: these five are all stated clearly in the docs, and people usually meet them only after something has already broken. I have gathered them in one place so they can be read beforehand rather than afterwards.

• OAuth logins are shared, not copied — Anthropic (Claude Pro/Max), OpenAI Codex and xAI use "single-use refresh tokens", and the docs explain that a copy is not a second credential but the same credential with two owners, where the first profile to refresh it revokes it for every other copy. --clone-all therefore drops those OAuth rows from the clone; the new profile keeps reading the login from the root ~/.hermes/auth.json as normal, while static API keys are copied as usual. To give a profile a login genuinely of its own, run hermes -p <name> auth add <provider> inside it^[1]
• hermes update syncs skills to every profile and never overwrites what you edited — the docs show the sample output "Skills synced: default (up to date), coder (+2 new), assistant (+2 new)" and close with "User-modified skills are never overwritten"^[1]. And if you deliberately made an empty profile with --no-skills, it writes a .no-bundled-skills marker so later updates do not re-seed it; toggle that afterwards with hermes skills opt-out / hermes skills opt-in^[2]
• Routines are ordinary cron jobs — what the screen calls a Bot's Routine is "plain Hermes cron jobs namespaced [bot:<name>] <routine>". They show up in hermes cron list and on the core Cron page too, and each run lands in that Bot's own chat history^[3]. Which means you can always inspect and fix them from a terminal — a thread #6 Automation & Agents picks up
• default can be neither deleted nor imported over — the docs say "You cannot delete the default profile (~/.hermes). To remove everything, use hermes uninstall"^[1], and the import side refuses as well: "You cannot import as default — that name is the built-in root profile", so pass --name with something else^[4]. The only thing you can do to default is give it a display name with hermes profile rename default <Name>, stored as the display_name key in ~/.hermes/profile.yaml, while the canonical ID stays default everywhere^[1]
• Each profile runs its own gateway with its own tokens — coder gateway start and assistant gateway start are separate processes reading separate .env files, and coder gateway install creates a hermes-gateway-coder systemd/launchd service for you^[1]. The safety net that matters is the token lock: the docs say that if two profiles accidentally use the same bot token, "the second gateway will be blocked with a clear error naming the conflicting profile", supported for Telegram, Discord, Slack, WhatsApp and Signal^[1]

The one I would underline is the first, because it changes how you think about cost: ten profiles do not mean ten subscriptions — they all read the same login from the root. But it also means they share the same quota. If you truly need separate bills, separate at the credential level, not at the profile level.

8. Summary

We started from a definition one sentence long — a profile is a separate Hermes home directory — and grew it into a way of organising a whole machine: a table of what belongs to whom and what stays shared, creating a Bot on screen and creating a profile in a terminal and finding they produce the same object, giving it a persona with SOUL.md, a folder with terminal.cwd and a model with model.default, and moving the whole thing between machines with export and import. The next post, #4 The Council, goes one step further — making answers get checked before they reach us.

Let me close with practice from a real user. In Greg Isenberg's walkthrough with Alex Finn (6 June 2026), Finn organises his profiles by model rather than by task — a top-tier model for strategy, another for coding, and a model on his own machine for research that costs nothing — and then picks the profile whose strengths match the job in front of him. He also gives the shortest rule I have seen for choosing between profiles and subagents: "Sub-agents handle one skill across many parallel tasks; profiles handle work where each step needs a distinct skill set" — different skill sets mean separate profiles; one skill run many times in parallel means subagents^[11]. This is community practice, not advice from the official docs, but I find it matches what the docs say without saying it: a profile separates state, a subagent separates labour.