Setting up Hermes

This walks a self-managed team through turning Hermes on your own machine into an AI employee connected to HQ. If cln.work runs your infrastructure, you do not need this page, we set Hermes up for you.

What you need

• Hermes installed for your OS. Follow the upstream install instructions at the link above.

• A model provider. Hermes does not ship one, so pick one of:

  • Zero-config: run hermes setup --portal and follow the prompts. This provisions a model through the Hermes portal with no key management on your side.
  • Bring your own key: configure any provider Hermes supports directly in ~/.hermes/config.yaml (Anthropic, OpenAI, and so on) using your own API key.

  Either way, the model must support a context window of at least 64k tokens, Hermes' memory and compaction behavior assumes it. We only ever supply the HQ MCP key, the model provider is entirely on you.

Install

Run the steps in order, each one assumes the previous step finished:

1. Install Hermes for your OS.

2. Set up a model provider as described above, then confirm it works:

   hermes doctor
   

3. Run the install script from the extracted bundle.

   bash install.sh       # Mac / Linux
   

   .\install.ps1          # Windows
   

The install script performs these steps, in this exact order, because Hermes does not hot-reload its config file, everything that writes config has to finish before anything that reads it:

1. Preflight checks that hermes is on your PATH and that a model provider is configured.
2. Writes secrets to your .env: your HQ API key, and Slack tokens if you provide them.
3. Copies SOUL.md and the skill files into $HERMES_HOME.
4. Merges config by running hermes/merge-config.py, which deep-merges the hq MCP server block and Slack platform settings into your ~/.hermes/config.yaml without touching anything else already in that file. It is idempotent, safe to re-run after every bundle re-download.
5. Runs hermes doctor to validate the now-final config.
6. Runs hermes mcp test hq to confirm the MCP connection specifically works.
7. Registers scheduled work with hermes cron.
8. Starts or restarts the Slack gateway last of all, so it always comes up against the final, fully-merged config rather than restarting again a moment later.

Slack

Hermes talks to Slack over Socket Mode, which needs a Slack app created with Socket Mode enabled and both of these tokens:

• SLACK_BOT_TOKEN, the xoxb-... bot token from the app's OAuth & Permissions page.
• SLACK_APP_TOKEN, the xapp-... app-level token, required for Socket Mode's real-time event delivery.

SLACK_ALLOWED_USERS is also required, and it is easy to miss. The Hermes gateway denies every inbound Slack message by default until you set this to a comma-separated list of the Slack user IDs allowed to message the employee. Valid bot and app tokens are not enough on their own, without this variable populated, Slack messages are simply dropped with no error shown anywhere, which makes it look like the integration is broken when it is actually just refusing all senders.

Scheduled work

Hermes has its own native scheduler, the install script registers your employee's jobs with it directly (no OS-level cron or Task Scheduler involved on Mac or Linux). Inspect what is registered at any time with:

hermes cron list

The heartbeat runs hourly by default. Any morning brief, end-of-day report, or weekly summary jobs you enabled in the wizard, plus any module-defined cron jobs your enrolled modules add, are registered the same way.

Running multiple employees on one machine

Hermes supports profiles for exactly this: give each employee its own HERMES_HOME directory (for example ~/.hermes-<employee-slug>) so their configs, memory, and credentials never collide. Set HERMES_HOME before invoking hermes for that employee, or use hermes's --profile flag if your version supports it, check hermes --help.

Windows

Hermes does not support installing the gateway as a Windows service. On Windows:

1. Run hermes gateway run directly in a terminal window and leave it open (a Windows Terminal tab you keep alive works well).
2. Scheduled work still runs independently of the gateway, the heartbeat and other cron jobs registered with hermes cron fire on schedule whether or not the gateway is running. Only real-time Slack delivery needs the foreground gateway process.

Troubleshooting

• "401 from HQ": check your API key environment variable matches the key shown on the HQ AI Employees page.
• Slack messages silently dropped: check SLACK_ALLOWED_USERS is set, Hermes denies by default.
• Config changes not taking effect: run hermes gateway restart, Hermes does not hot-reload config.yaml.
• merge-config.py fails with an ImportError: run pip install pyyaml.

Renaming your employee requires a bundle re-download

If you rename the employee in HQ, download a fresh bundle and re-run the install and merge steps. The MCP URL, the API key's environment variable name, and the skills directory are all derived from the employee's name at the moment the bundle was generated, editing them by hand instead of redownloading will drift out of sync with HQ.

Switching runtimes

If you are moving this employee off Hermes onto a different runtime:

1. Stop the gateway, then uninstall it: hermes gateway stop, followed by removing the service Hermes installed for it.
2. Remove the scheduled jobs Hermes registered for this employee: hermes cron remove for the heartbeat and any module-defined jobs (see hermes cron list for the exact names).
3. Remove the mcp_servers.hq block from ~/.hermes/config.yaml.
4. Delete the skills/hq folder from your Hermes home.
5. Remove the env lines the installer wrote from the Hermes env file: the HQ API key variable and, if you configured Slack, SLACK_BOT_TOKEN, SLACK_APP_TOKEN, and SLACK_ALLOWED_USERS. Find the file with hermes config env-path (it defaults to ~/.hermes/.env).
6. Switch the runtime in HQ's wizard and download the new bundle.

Related

• Creating an AI employee
• Setting up Codex
• Quick start