Scaling Hermes Agent to Multiple Users and Partners — A Collaboration Architecture Guide

1. The Mental Model: Four Primitives

Before the feature list, the four building blocks everything else is made of. Keep these four straight and the rest falls into place.

The single most important invariant, from the profiles documentation, is this: give every agent its own profile, and never point two agent processes at the same profile. Two writers on one home "compound each other's state until it stops being anything you configured" — both write memory automatically, and each loads the other's writes into its system prompt at session start. Profiles exist exactly to prevent that. If two agents genuinely need shared memory, the documented answer is an external memory provider, not a shared profile. Everything in this report is built on that rule.

2. Profiles: The Isolation Boundary

A profile is a separate Hermes home under ~/.hermes/profiles/<name>/, containing its own config.yaml, .env, SOUL.md, memories, sessions, skills, cron jobs, and state database [Link]. The moment you create one, it becomes its own command:

Three creation modes cover the common collaboration cases [Link]:

• Blank — hermes profile create partner-a: a fresh profile with bundled skills seeded. The starting point for a partner who needs their own clean agent.
• Clone config only — hermes profile create work --clone: copies the config but not secrets or history. Good for spinning up a like-for-like agent with the same model and tools.
• Clone everything — hermes profile create backup --clone-all: a complete working snapshot (config, keys, personality, memories, skills, plugins), explicitly excluding the heavy per-profile history (sessions, state.db, checkpoints) which can reach tens of GB.

Two details matter for a multi-user operation. First, messaging channels are never cloned by default — a new profile gets no bots, so two profiles can't accidentally fight over the same Telegram handle; you opt in with --clone-channels. Second, OAuth logins are shared, not copied; to give a profile its own separate login you run hermes -p <name> auth add <provider> inside it. There's also a sticky default (hermes profile use coder, like kubectl config use-context) so a regular operator can work inside one profile without typing -p every time.

3. Level 1 — One Gateway, Many Humans

The simplest expansion: keep your single gateway, and let other people talk to it. This is the level you're at if your goal is "my partners should be able to DM the bot," not "we should have separate agents." The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice [Link]. It supports 21+ platforms — Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Matrix, Teams, and more — and the same agent core answers on all of them.

The critical piece is authorization: by default, a gateway with no allowlist configured denies everyone. The check order is layered [Link]:

1. Per-platform allow-all flag
2. DM pairing approved list
3. Platform-specific allowlist (e.g. TELEGRAM_ALLOWED_USERS)
4. Global allowlist (GATEWAY_ALLOWED_USERS)
5. Global allow-all (GATEWAY_ALLOW_ALL_USERS)
6. Default: deny

For onboarding partners you don't have IDs for yet, the DM pairing system is the clean path: an unknown user DMs the bot, gets an 8-character pairing code, and you approve it once with hermes pairing approve <platform> <code> — after which that user is permanently approved on that platform [Link]. The codes are cryptographic and drawn from an unambiguous 32-character alphabet (no 0/O/1/I). You can tune per-platform behavior for unknown DMs: pair (default — send a code), ignore (drop silently), or decline (one polite refusal, then ignore for 24h).

This level gives you multi-human access to one shared agent. It's the right shape for a small team collaborating on a single assistant. It is the wrong shape if each partner needs their own memory, their own personality, or their own set of credentials — which is where Level 2 begins.

4. Level 2 — Many Named Agents (Bot Mode)

Bot Mode is a UI over profiles — there is no new primitive. A Bot is a Hermes profile: isolated config, memory, skills, credentials, and chat history under ~/.hermes/profiles/<name>/ [Link]. The Bots pane is a roster of named agents, and everything you do there is visible from the CLI (hermes -p <bot> chat opens the same agent). No core patches, no extra daemons, no extra storage.

For a multi-partner operation, Bot Mode gives you three things:

Bot Mode also has a warm backend concept — you set how many Bots run simultaneously, so a roster of ten partners doesn't mean ten live processes hammering memory; only the ones in active use are warm. And because Bots are profiles, everything has a CLI equivalent, which means your whole Bot operation is scriptable and auditable from a terminal, not locked behind the desktop UI.

5. Level 3 — Shared Work: The Kanban Board

This is the primitive most people are actually missing when they say "we want to collaborate." Hermes Kanban is a durable task board, shared across all your profiles, that lets multiple named agents collaborate on work without fragile in-process subagent swarms [Link]. Every task is a row in ~/.hermes/kanban.db; every handoff is a row anyone can read and write; every worker is a full OS process with its own identity.

The one-sentence distinction the docs draw from the in-process delegate_task is worth memorizing:

For multi-partner collaboration, Kanban is the right layer because it's peer-coordinated and human-visible. A partner can open the board (via the dashboard, the CLI, or /kanban), see every task, comment on one, unblock a stuck worker, or create a card that a different agent role picks up — no one is a single point of failure, and the whole history is durable in SQLite. The docs catalogue workload shapes it's designed for that map directly onto a partner operation: parallel researchers + analyst + writer with a human in the loop, recurring daily briefs that build a journal, persistent named "digital twin" assistants that accumulate memory, engineering pipelines (decompose → implement in parallel worktrees → review → PR), and one specialist managing N subjects [Link]. There's even a Kanban multi-gateway deployment mode — one board shared across several per-profile gateways with a single dispatcher and profile-owned delivery — which is the exact shape for "each partner runs their own gateway, but we work one shared board."

6. Level 4 — Partners Across Machines

So far everything has been one machine. Real partner operations usually span several. Hermes has two complementary multi-machine pages, and they answer different questions [Link] [Link]:

Running Many Gateways at Once

This is about hosting several gateways on one machine — one per partner profile, each with its own process, its own platform credentials, and its own isolated config. The multiplexing model keeps a strict per-profile isolation: each profile's terminal sandbox, credential-file mounts, browser flags, secrets, and media-delivery credentials are read from that profile's own config.yaml/.env, never bridged from the launch profile or the default profile. A profile whose config can't be parsed gets terminal execution refused rather than run under another profile's sandbox policy. That "fail closed on a different profile's policy" behavior is exactly the property you want when partner A's misconfigured profile must not inherit partner B's credentials.

Connecting the Desktop to Many Instances

This is the other direction: one desktop app talking to several machines. You register every Hermes backend you own — the local runtime, remote gateways on your LAN or a VPS, SSH hosts, and Hermes Cloud instances — in one app and work with the agents on all of them side by side [Link]. Each registered connection has a kind, an auth method, and its own reachability:

Connections are persistent: each registered gateway dials its own backends and WebSockets on demand, and background agents keep streaming while you look at another gateway. Every connection needs a unique device name, one is always the Primary (the registry fallback for calls that don't name a gateway), and a "Test" probe checks the connection's own HTTP and WebSocket legs so a pass means chat will actually work — not just that the host pinged. This is the shape where each partner runs Hermes on their own machine (or a VPS), and your desktop is the single pane of glass across all of them — with bot-to-bot DMs and group rooms flowing across the connections through the Desktop relay automatically.

Git Worktrees for Shared Repos

When multiple agents (yours and a partner's) edit the same codebase, Hermes ships a documented pattern: run them on git worktrees — isolated checkouts of the same repository, so parallel agents don't clobber each other's working trees [Link]. The -w flag spawns an agent in worktree mode for exactly this reason. It's the answer to the "two partners on the same repo" problem that profiles (state isolation) and containers (filesystem isolation) don't cover — code isolation.

7. Level 5 — Handing Your Setup to a Partner

Sometimes "collaborate" means "give this partner a copy of my working agent." Hermes has two shipping mechanisms, and they're deliberately different [Link] [Link]:

Profile export / import (one-off handoff)

An export is a one-shot file — hand it over, they run import. Good for "here's my setup, install it on your machine right now," or for backing up and moving a profile. Exports deliberately strip credentials and user data.

Profile distributions (versioned, ongoing)

A profile distribution packages a complete agent — personality, skills, cron jobs, MCP connections, config — as a git repository [Link]. The partner does hermes profile install, and later hermes profile update pulls changes like a fetch. The reasoning for git is the same as for any serious software: tags/branches/commits are already the versioning system, updates are a fetch not a re-download, and it's transparent — partners can browse the repo, read diffs between versions, open issues, and fork to customize.

Critically for a partner relationship, the distribution is never a leak of your secrets or user data. The installer excludes auth.json and .env (each partner brings their own credentials), and never ships memories, sessions, or conversation history — those are user data, not distribution content. What is shared: the agent's SOUL, config, skills, cron, MCP, plugins, and (if you include it) your desktop theme and layout. That's precisely the boundary you want: hand a partner your capabilities and playbook without handing them your keys, your memory, or your private conversations.

8. The Access-Control Model That Makes It Safe

Multi-user only works if the security model holds up under more than one human. Hermes is built as a defense-in-depth stack with eight layers [Link], and four of them matter most for a partner operation:

Three security facts are worth internalizing before you open the gate. First, the default is deny — a gateway with no allowlists configured refuses all users and logs a warning at startup, so the failure mode is safe, not open. Second, the hardline blocklist is an always-on floor: catastrophic commands (filesystem wipes, fork bombs, block-device writes, piping untrusted URLs to sh) are refused before the approval layer even sees them, and no setting — not --yolo, not approvals.mode: off, not a user clicking "allow always" — can bypass it [Link]. Third, there's a user-editable approvals.deny list of glob patterns that block specific commands unconditionally, for running "yolo-with-exceptions" — e.g. git push --force* never, whatever anyone asks for. For a partner deployment, the production checklist in the docs — gateway deployment, securing API keys, network isolation — is the concrete runbook to follow before pointing a partner at a gateway [Link].

9. Choosing Your Topology

Pick the level that matches the collaboration you actually need. The levels stack — you start at 1 and add 2, 3, 4, 5 as the operation grows — so "which do I pick" is really "where am I today and what's the next constraint?"

The honest framing: most "let's have partners collaborate" requests are really Levels 1 + 3. You add a partner to the gateway (Level 1), and you add a shared board (Level 3) so the work is visible and durable. Levels 2, 4, and 5 are there when the operation grows past that — into named specialists, into machines you don't control, and into handing the whole playbook to a partner.