Wiki · Features in depth
Profiles and multiple agents
A second agent for different work is not a second server — it just needs its own profile. Here is how, and where profiles get confused with permissions.
What a profile contains
A profile is a single folder in ~/.hermes/profiles/name/. Everything the
agent has lives there — which is why profiles can be backed up, moved and cloned:
| Inside the profile | What for |
|---|---|
config.yaml | Settings: model, tools, terminal backend, scheduled jobs |
.env | Keys and secrets (API keys, tokens) |
SOUL.md | How the agent talks and behaves |
memories/ | Memory — what it writes down about you and the work |
sessions + state.db | All conversations and the agent's state |
skills/, cron/, plugins/ | Learned procedures, scheduled jobs, extensions |
A folder counts as a profile only when it holds one of these files
(config.yaml, .env, SOUL.md, profile.yaml,
auth.json, state.db). An empty folder left behind by a log is ignored.
Creating a profile in three steps
Create it — a matching command appears as well:
❯ hermes profile create coderConfigure its keys and model (this runs inside the new profile, not the current one):
❯ coder setupStart talking to it. From now on
coderhas its own memory and history:❯ coder chat
To start from your current settings, add --clone (it copies config,
keys, SOUL.md, skills and memory). hermes profile create work --clone
Working with profiles
| What you want | Command |
|---|---|
| Run anything in another profile | hermes -p coder chat, hermes -p coder doctor |
| A quick question without opening the UI | hermes -p work chat -q "Check the server status" |
| List profiles | hermes profile list |
| Explain what is in a profile | hermes profile show coder |
| Copy a profile | hermes profile create work-backup --clone-from coder --clone-all |
| Export / move to another machine | hermes profile export · hermes profile import |
A profile is not a sandbox
This is the most common misunderstanding. A profile separates the agent's state, not its permissions:
| What | Controlled by | What it means |
|---|---|---|
| State (config, memory, conversations) | The profile (HERMES_HOME) | Two profiles cannot see into each other |
| Where commands start | terminal.cwd in config.yaml | The agent may well work inside your project; set that folder explicitly |
| What it may touch on disk | Your OS user's rights (plus a sandbox if you enable one) | A profile alone does not restrict anything — that is the Security page |
cwd: "." means "the folder I launched Hermes from", not the profile
folder. Asking the agent which directory it is in is not a reliable isolation test. Set it.
Several agents on one server
On a single VPS it is normal to run several profiles side by side: one for a website, one main assistant, one community bot. Each has its own state database and its own conversations.
| What to watch | Why and how |
|---|---|
| One profile = one running agent. Never two processes on the same profile | Both write memory, and each loads the other's writes at session start — the state compounds until nobody knows what you configured |
| The right profile per platform | When two profiles share one bot token (Discord, for example) they fight over the connection and the service restarts in a loop |
| One gateway per profile (or multiplexing) | Each profile can run its own gateway; or use one shared gateway with gateway.multiplex_profiles: true |
| Check memory after cloning | If the profile uses an external memory provider, verify its settings travelled — otherwise memory is silently off and the agent only looks like it remembers |
Where a profile and your machine mix
A profile is separated only for Hermes itself. The tools it uses (git, ssh, gh, npm…) take the credentials of your system account, so two profiles on one machine share your GitHub and your SSH key.
| You want | Setting |
|---|---|
| Profiles to share your account's credentials (usual and convenient) | The default — do nothing |
| A profile with its own CLI logins | terminal.home_mode: profile in that profile's config.yaml |
What we learned running this
| What we dealt with | The lesson |
|---|---|
| Three profiles and one bot on a single VPS. The gateway service kept restarting | The cause was a token conflict plus an unfinished component in the profile, not the bot. Splitting roles into profiles and restarting services together fixed it |
| After an upgrade the agent acted as if it remembered nothing | The profile had an empty memory setting (memory.provider). With external memory, always verify the setting, not just that the file exists |
| The website, the main assistant and the community bot run as three profiles | Editing one does not touch the others — and when something breaks, you know which profile it was |
| Two agents needed different projects in the same folder | terminal.cwd per profile did it. "Which folder are you in?" is not a sufficient check |
Our tips
| Tip | Why |
|---|---|
| A profile per project, not per mood | Memory and keys belong to a project — otherwise the agent mixes contexts up |
| Name profiles short and plain ASCII | The name is also a command: coder chat is easy, a name with accents is not |
| Try things in a clone | --clone gives you a copy you can safely break |
| Remember a profile is not a wall | Handle permissions separately — OS accounts, a container or command approval |