Attaching Agents to Multiple Slack Workspaces with Hermes Multi-Profile
A write-up of how to run several Hermes Agent instances on a single machine, one per profile, and connect each profile to a different Slack workspace. While attaching one particular profile (custom_profile) to a new workspace (New_Workspace, team T_NEW), I lost a good while to a “looks connected but never replies” symptom, and the cause turned out to be an invalid Slack bot token (invalid_auth). I’m recording the whole process here so I don’t get stuck in the same place the next time I create more profiles.
1. The big picture: what a profile is and why you’d use one
A Hermes profile is a fully isolated instance. Each profile has its own HERMES_HOME directory — config, API keys (.env), session DB, memory, skills, even gateway state are all kept separate.
- Default (root) instance →
~/.hermes/ - Named profile →
~/.hermes/profiles/<name>/Internally, when you passhermes -p <name> ...,_apply_profile_override()swapsHERMES_HOMEover to that profile’s folder before any module is imported. That’s whyget_hermes_home()is automatically scoped to that profile everywhere in the code.
The key effect: you can run a separate gateway per profile, and each gateway attaches to a different messenger account/workspace. On our machine, two are running at the same time right now.
| |
Having both gateways up together is normal. As long as they’re properly isolated, they don’t conflict. That “as long as they’re properly isolated” is the heart of the trap — see sections 4 and 6 below.
2. Creating a new profile (step by step)
1) Create the profile
| |
2) Configure in this profile’s context (-p <name> on every command)
| |
3) Run the gateway
| |
- Profile-related subcommands:
create,list,switch,use,delete. - Caution:
hermes profile delete <name>wipes that profile’s entireHERMES_HOME(sessions and memory included). Don’t use it carelessly.
3. The two Slack tokens — where 90% of people get stuck
Hermes’s Slack integration is based on Socket Mode and needs two kinds of token. The key point is that they play different roles and are valid or invalid independently of each other.
| .env key | Token format | Purpose | Where it’s issued |
|---|---|---|---|
| SLACK_APP_TOKEN | xapp-... | Receiving events (Socket Mode connection) | Slack app → Basic Information → App-Level Tokens (connections:write scope) |
| SLACK_BOT_TOKEN | xoxb-... | Web API calls (sending messages, listing channels, etc.) | Slack app → OAuth & Permissions → Bot User OAuth Token (issued when installed to the workspace) |
Other things you’d usually set alongside them:
SLACK_HOME_CHANNEL— default reply channel/DM ID (e.g.C0B5M...)SLACK_ALLOWED_USERS— list of allowed user IDs (e.g.U1923...) Why they’re split in twoxapp (the app-level token) is tied to the app itself. It usually survives even if you reinstall the app to the workspace. → Socket Mode keeps connecting.
xoxb (the bot token) is tied to “the instance of this app installed in this workspace.” Reinstall the app or regenerate the token and the value changes. The old value becomes invalid immediately.
As a result, it’s far too easy to end up in a mismatched state where xapp is right and only xoxb is wrong. That is exactly the symptom we hit.

4. The symptom we hit, and the diagnosis
Symptom
- The bot appears to be authenticated to the workspace. DMs/mentions come in too (the channel directory updates in real time).
- But it doesn’t reply. It felt like it “was working, then stopped and got tangled.” What was actually happening
The gateway log had this showing up every 5 minutes, more than 1,400 times:
| |
And it had been broken from the very moment of the first authentication log:
| |
| Token | Status |
|---|---|
| SLACK_APP_TOKEN (xapp) | ✅ Fine — authenticated to New_Workspace via Socket Mode → events come in |
| SLACK_BOT_TOKEN (xoxb) | ❌ invalid_auth — every reply/lookup API call fails |
In other words, a half connection that can only receive and can’t send. It was all the more confusing because it looked connected from the outside.
The decisive check — auth.test
You can tell whether a token is valid in one second with Slack’s auth.test (read-only). Don’t print the token to the screen; read it straight from .env and pass it in the header:
| |
- **If it’s valid:**JSON
| |
- **If it’s invalid:**JSON
| |
Our case: custom_profile bot token → invalid_auth, root bot token → ok: true. Done. Culprit confirmed.
The fix
New_WorkspaceSlack app → OAuth & Permissions → copy the latest Bot User OAuth Token (xoxb-) value. (If you reinstalled the app or regenerated the token, the value will have changed.)
- ⚠️ This bot token must belong to the same app as the app token (
xapp) you’re currently using. Mix tokens from different apps and you get exactly this symptom (Socket connects but the Web API returnsinvalid_auth).
- Replace
SLACK_BOT_TOKENin~/.hermes/profiles/custom_profile/.env. - Restart the gateway (section 5 below — I went around in circles twice because I skipped this).
- Re-run
auth.test→ once you seeok: true, you’re done.
5. The second trap: fix .env without restarting and nothing changes
The gateway reads .env into memory at startup. A running process doesn’t pick up any later edits to .env. Our timeline was exactly this:
| |
Even after you fix the token, the gateway is still holding on to the old one, so it keeps looking broken. → If you’ve touched .env, always restart.
| |
⚠️ gateway stop/restart --all kills the gateways of every profile. The root gateway goes down with them, so when you’re only working on one specific profile, leave out --all and pass just -p <name>.
6. The third trap: sharing tokens across profiles = lock conflict
The gateway platform adapters take a scoped lock on each unique credential (bot token). If two profiles use the same token, whichever starts later gets blocked. We ran into this early on too, because custom_profile was using the same Telegram bot token as root:
| |
- Principle: each profile gets its own separate credentials for a given platform.
- For Slack, that means a different Slack app + a different xapp/xoxb pair per workspace.
- For platforms you don’t use, remove the token from that profile’s
.envaltogether (we got rid of the lock by removing the Telegram token fromcustom_profile). Note:gateway_state.jsonis only updated on state transitions. A value from days ago can still be sitting there, stale, so always cross-check the current state against the logs.
7. Diagnostic recipe (next time you’re stuck, go in this order)
| |
When you only want to compare tokens (without exposing them), check that they’re identical using just the first 8 characters of the sha256:
| |
8. Checklist for the next profile
[ ] hermes profile create <name>
[ ] Create a new Slack app for each new workspace (no reusing an existing app).
[ ] Issue an App-Level Token (xapp, connections:write) from that app → SLACK_APP_TOKEN
[ ] Install that app to the workspace, then copy the Bot User OAuth Token (xoxb) → SLACK_BOT_TOKEN
[ ] Confirm that xapp and xoxb belong to the same app (mix them and you get invalid_auth).
[ ] Set SLACK_HOME_CHANNEL and SLACK_ALLOWED_USERS.
[ ] Don’t share tokens with other profiles. Remove tokens for unused platforms from .env.
[ ] Save .env → first confirm ok:true with auth.test → only then start the gateway.
[ ] If you edit .env later → gateway restart (never -all, just p <name>).
[ ] Check that there’s no invalid_auth / _lock in gateway.error.log.
9. Appendix
Profile directory structure
| |
Command reference
| |

One-line summary
If Socket Mode (xapp) connects but the bot doesn’t reply, nine times out of ten the xoxb bot token is invalid. Check it instantly with auth.test, and if you’ve fixed .env, don’t forget to restart the gateway. Give each profile and workspace its own pair of tokens from the same app, and never share them.
