Hermes Agent Profiles: How to Isolate Work, Personal, and Bot Agents

Hermes Agent profiles are the clean way to run separate agents without mixing memory, secrets, skills, sessions, or gateway bots. If you use Hermes for work, personal automation, a Telegram bot, and a risky test project, do not cram everything into one ~/.hermes directory. Run /profile to identify the active Hermes home and /context to inspect the active window; context pressure inside one profile is not cross-profile memory bleed. Create profiles and give each context its own boundary.

Bot-token locks are shared ownership checks, not profile memory#

A profile owns Hermes configuration and state, but bot-token locks must coordinate across profiles. The official profile guide documents that a second gateway using the same supported bot token is blocked with the conflicting profile named. A lock outside your selected profile directory does not mean its memory or sessions have moved.

Keep three identifiers in your incident notes: the selected Hermes home, the operating-system account running the service, and the profile that owns the bot credential. These are not interchangeable. Use hermes -p work config path and hermes -p work gateway status, substituting the existing bot profile, rather than asking the model which files it thinks it uses.

If Windows reports access denied in gateway-locks, inspect that directory's ACL under the normal runtime account. If the error names a live competing gateway, resolve ownership instead. Never delete a lock to let two consumers share a bot. The gateway lock-permission decision tree separates these cases and requires an actual channel reply after repair.

Profiles also do not enforce operating-system isolation: the local terminal retains the user's filesystem permissions, and inherited environment credentials can remain visible. Use separate OS accounts or a suitably restricted sandbox where access boundaries must be enforced, not merely organized.

Prove the scheduler reads the same profile#

When chat works but scheduled work reports missing credentials, compare the profile and HERMES_HOME in the cron error with the shell that passed the test. A service, container, or remote machine can read a different auth.json, .env, skill library, or scripts directory even when the visible task name matches.

Run read-only checks explicitly against the intended profile:

hermes -p work cron list
hermes -p work cron doctor

Replace work with an existing profile; these checks do not create one. Do not solve the mismatch by placing credentials in the prompt or copying all personal secrets into a bot. Repair the owning profile and use the cron preflight guide to verify the missing requirement.

Source: official Hermes scheduled-task documentation.

When you should create a profile#

Create a Hermes profile whenever the boundary matters more than convenience. Good examples:

• Work vs personal: keep company credentials, repositories, calendars, and memory separate from personal automations.
• One profile per client: prevent one client skill or AGENTS.md convention from leaking into another engagement.
• One profile per public bot: a Telegram community bot should not have the same secrets as your private assistant; use a dedicated profile with its own token and gateway. See the Telegram integration and Telegram setup guide.
• Testing dangerous tools: try new MCP servers, plugins, browser automation, or terminal backends in a disposable profile before enabling them in your main agent.
• Different model/provider budgets: keep an expensive coding profile on a frontier model while a lightweight monitoring profile uses a cheaper provider.

Do not use profiles as cosmetic labels. Use them when memory, tools, tokens, or operational risk should be isolated.

What a Hermes profile isolates#

A profile is a full Hermes home directory with its own durable state. In practice, that means:

• config.yaml for model, tool, gateway, terminal, memory, and display settings.
• .env for profile-specific API keys and platform tokens.
• skills/ for reusable procedures loaded only by that profile.
• sessions/ for transcript history and resume/continue behavior.
• memory files and provider settings for persistent memory.
• gateway state for platform adapters such as Telegram, Discord, Slack, Email, and Webhooks.

That isolation is why profiles are better than prompt instructions for secret scoping. If a token exists in one shared environment, the shared agent can use it. A profile-specific .env avoids automatically selecting another profile's configuration; it does not deny same-user filesystem access or erase inherited environment credentials.

Copy-paste setup: work and personal profiles#

Create two profiles:

hermes profile create work
hermes profile create personal

Show where each profile stores config and secrets:

hermes -p work config path
hermes -p work config env-path
hermes -p personal config path
hermes -p personal config env-path

Run a one-off command in the work profile:

hermes -p work chat -q "Summarize the open PRs in this repository"

Make one profile your default:

hermes profile use personal
hermes chat -q "What profile am I using?"

List profiles when you forget what exists:

hermes profile list

The -p flag is the safest habit for automation because scripts, cron jobs, and launch services should not depend on whichever profile happened to be sticky in your shell.

Profile pattern for a Telegram or Discord bot#

A messaging bot should normally get its own profile. That is especially important for a public or semi-public bot, because the profile selects its configured secrets, tools, skills and memory; OS permissions still determine which other files it can reach.

Recommended pattern:

1. Create the profile.
2. Put only the bot token and required provider keys in that profile's .env.
3. Enable only the toolsets the bot needs. MCP servers follow the same boundary: they are configured per profile, so a server added to your default profile is not visible to the bot profile. Re-run hermes -p <profile> mcp add (or hermes -p <profile> mcp install) for every profile that should see the server, and keep each profile's MCP credentials scoped to that workflow.
4. Configure the gateway inside that profile.
5. Start or install the gateway for that profile.

Example:

hermes profile create telegrambot
hermes -p telegrambot config env-path
hermes -p telegrambot gateway setup
hermes -p telegrambot gateway run

For a team bot, add only the skills you want that bot to use. The custom skills guide explains how skills are stored and structured. If you are migrating existing instructions, the Claude Code skills migration guide shows how to convert them into Hermes-compatible procedures.

Credential priority is preference, not workload isolation#

If one subscription must be reserved for a particular project, placing it last in a shared credential pool does not enforce that requirement. Under fill_first, a lower-priority healthy credential remains eligible when earlier entries cannot serve the request. A session that already holds a credential can also retain it until rotation.

Use distinct profile credentials and explicitly invoke hermes -p <name> ... for each workload. Inspect the owning profile's hermes fallback list and hermes auth list before enabling an unattended service. Do not duplicate one OAuth refresh token across profiles and assume independent capacity. See provider fallback setup and verification for the difference between a pool, a cross-provider chain, and a real billing boundary. Profiles still do not replace OS-level permissions.

Source: official Hermes fallback and recovery documentation, checked October 1, 2026.

Profile pattern for model and provider experiments#

Profiles also make model testing less chaotic. Instead of constantly changing your main config, create an experiment profile and point it at a different provider:

hermes profile create localtest
hermes -p localtest model
hermes -p localtest chat -q "Run a small coding task and explain tool usage"

This keeps your main sessions, memory, and cost assumptions stable while you test local models, OpenRouter routing, Nous Portal OAuth, or other providers. For agent behavior comparisons, pair this with Hermes Agent vs Claude Code or the Hermes CLI reference page so the test is about workflow, not just raw model output.

How to move or clone a profile#

Use export/import for a portable profile handoff, and check the archive's scope before treating it as a complete disaster-recovery backup:

hermes profile export work
hermes profile import work.tar.gz --name restored-work

To start a new profile from a particular existing setup, use the documented source selector:

hermes profile create client-acme --clone-from work

Current documentation distinguishes a clone from a full backup. A normal clone copies configuration, skills, persona and curated memory, but starts sessions and scheduled jobs empty. Messaging channels are excluded by default; configure the new profile's own bot rather than copying a token to make it appear online. Even --clone-all excludes history and cron jobs under the current documented behavior.

Inspect provider/tool credentials and external memory settings before use: copying a configuration can retain access to an external service or memory bank. Do not assume a new folder creates a new remote account. OAuth refresh tokens are not independent credentials when copied; use the supported credential flow for a separately owned login.

Check hermes profile create --help on your installed version and the official cloning rules before migration. Older versions can differ. Verify the new profile's config path, bot identity, memory scope and one harmless task before retiring the original.

If a session appears to jump profiles#

Stop and prove ownership before writing memory or resuming work. Run /profile inside the affected chat, hermes profile show <name>, and hermes sessions stats under the intended profile. Update Hermes before reproducing a branch or compression issue, because profile-routing fixes land in the runtime rather than in memory files. Do not copy a session database between profiles as a shortcut. Preserve the task with the session handoff checklist, then resume from the profile that owns the original session.

Common mistakes#

Mistake 1: using one profile for every bot#

This is convenient until one bot can access another bot's secrets or memory. Use separate profiles for different trust levels.

Mistake 2: copying the entire default .env#

Copy only required keys. A read-only community bot probably does not need GitHub, Stripe, production database, and browser automation credentials.

Mistake 3: relying on the sticky profile in scripts#

Automation should be explicit:

hermes -p reporting cron list
hermes -p reporting chat -q "Generate today's report"

Mistake 4: treating profiles as permission sandboxes#

Profiles isolate files and configuration, but they are not a replacement for least-privilege API tokens, OS permissions, or a hardened server. For internet-facing deployments, combine profiles with Hermes security hardening. Use profiles to separate MCP configuration: put experimental or public-bot MCP servers in a separate profile and review the MCP security risks checklist before sharing secrets.

Check dashboard profile, session and workspace separately#

The Hermes Dashboard / Web UI is a machine-level admin surface. Config, API Keys, Skills, MCP, Models and Chat follow the profile switcher. An explicit ?profile=<name> in the URL selects the target; check it before changing settings.

A named-profile launch can start the shared dashboard with that profile as its fallback scope. Current official dashboard documentation says that fallback lasts for the server's lifetime. A resume link without ?profile= can therefore inherit that scope. Do not assume that omitting the parameter means the default profile. When the target matters, select it explicitly and verify the session belongs there.

Dashboard selection does not borrow the launcher's credentials#

The profile card's Set as active action changes the sticky default for future CLI/gateway runs. It does not change which profile the dashboard switcher manages. A selected dashboard profile and the next unqualified terminal command can therefore target different homes; use explicit hermes -p <name> ... commands when that distinction matters.

Current official docs also scope hub actions—skill install/update/uninstall, MCP installation and toolset setup—to the target profile's .env and configured secret sources. That rule includes actions targeting default from the machine dashboard. Do not assume a key exported in the server launcher's shell will be used by a selected profile's setup.

Before retrying a missing-credential error, confirm the sidebar selection and URL, inspect required key presence without printing its value, and verify the intended profile's config/env paths using the commands below. Change only the credential the workflow is authorized to use. Do not copy a whole secret file or treat profile isolation as an OS sandbox.

After setup, start a fresh session under that same profile and test one permitted read-only action. MCP's connection test lists tools; it does not prove every action's permissions or provider balance. The Dashboard hub setup diagnostic provides the ordered checks, while the Web UI setup guide covers launch and access. These are documented procedures, not an experiment performed against your accounts.

Source checked October 26, 2026: official Managing multiple profiles and Profiles sections. Check current docs against the running backend version before applying this behavior to an older install.

A workspace is not another profile#

Switching profiles starts a fresh terminal session using the selected profile's Hermes home. Choosing a workspace changes the starting directory for the next New chat, not the Hermes home. Resuming a conversation keeps its previous working directory, even if you selected another workspace meanwhile.

Before authorizing a file change:

1. Confirm the backend and the selected profile in the sidebar and URL.
2. Open the intended session or start a new chat in the chosen workspace.
3. Ask for the actual working directory and one non-sensitive filename without edits. Compare the tool result with the intended project, rather than trusting the conversation title.
4. Inspect the selected profile's configuration path from a trusted terminal if settings still look wrong:

hermes -p work config path
hermes -p work config env-path

Replace work with your existing profile. These commands print locations, not a reason to share the contents of a secret file. Do not paste .env into the chat to prove which profile is active.

Use --isolated only when you intentionally need a dedicated per-profile dashboard. It is not a replacement for OS permissions, and a workspace picker is not a filesystem sandbox. Gateway processes also stay separate; verify the owning profile and the actual message destination when testing a bot. For phone access, repeat the directory check after switching backend or resuming old work. Compare FlyHermes if you want managed access rather than maintaining these services yourself.

FAQ#

Are Hermes profiles the same as sessions?#

No. A session is one conversation history inside a Hermes home. A profile is an isolated Hermes home with its own sessions, memory, config, skills, and secrets.

Can two profiles share one skill?#

Yes, but copy it intentionally or install it separately. If a skill contains project-specific assumptions, keep it profile-specific.

Can one Telegram bot switch between profiles?#

Do not design it that way. Give each trust boundary its own bot token and profile. It is clearer operationally and safer for secrets.

Should I migrate everything from OpenClaw into one Hermes profile?#

Usually no. Start clean, then cherry-pick the secrets and skills you actually want. A blank Hermes profile is the easiest way to avoid importing old clutter.

Which profile should I use for FlyHermes?#

If you want a hosted path instead of managing profiles, gateways, and uptime yourself, FlyHermes is the natural commercial route. Use local profiles when you want direct control over a self-hosted Hermes installation.

Recent support signal: profiles are the clean boundary for messy installs#

Recent threads about copying Hermes between Linux machines, model-switch resets, memory failures, and gateway confusion all point to the same operational lesson: do not mix every project, provider, bot, and experiment into one shared profile.

Use separate profiles for production gateways, local experiments, high-risk MCP servers, and team/customer workflows. If the profile matrix starts to feel like infrastructure work, compare that self-managed path with FlyHermes, especially for always-on business workflows.

Use profiles for memory experiments#

A recurring support pattern is memory breakage after installing local memory layers or running gateway bots from the wrong environment. Separate profiles make experiments easier to inspect and roll back. Test memory providers and messaging bots with distinct external namespaces and restricted tool access before promoting them; a profile alone does not sandbox a plugin or remote memory service. The memory troubleshooting guide shows the recovery checklist.

Provider reliability is part of this workflow too. If setup fails because credits, API keys, rate limits, or model switching are unclear, use the Hermes Agent model provider costs guide to choose a primary model lane, a cheaper routine-work lane, and a local or hosted fallback before blaming the rest of the stack.

Profile drift breaks gateways#

A gateway can look broken when it is simply running a different profile than the file you edited. For Telegram and Discord incidents, use the gateway troubleshooting checklist to confirm the running profile, token location, allowed chats/channels, skills, tools, and memory boundary before rotating credentials.

Remote Desktop gateway scope is also profile-sensitive#

In Hermes Desktop, a remote gateway can apply to one named profile or to all profiles. If a newly created profile unexpectedly starts the local backend, check Settings → Gateway → Applies to before reinstalling anything. Save the remote connection for All profiles when that host should be the default, and keep named overrides only for profiles that intentionally use another backend. Then use the gateway troubleshooting runbook to prove the selected profile and real channel path.

Audit automatic memory per profile#

Memory approval, notifications, and the background-review provider are profile-scoped operating decisions. Before diagnosing cross-project contamination, run /profile, inspect pending writes, and compare the external provider namespace plus background_review usage in each profile. The memory troubleshooting guide provides the full isolation test.

Treat memory sharing as an access-control decision#

Profiles separate local memory, sessions, skills and configuration, but a shared external provider can join their data again. Before adding a shared provider, use the memory setup decision tree and five-prompt test to verify namespaces, deletion/export behavior, and that each profile retrieves only the facts it should see.

Remember that every profile has its own session database#

The default profile and each named profile keep separate state.db stores. A healthy default store does not prove a bot profile is healthy. Use the session-storage troubleshooting guide with the affected profile's resolved Hermes home, especially before recovery or backup.