ByteAtlas

Hermes Agent is an open-source terminal-native agent from Nous Research. It combines persistent memory, agent-created skills, tools, multiple model providers, and messaging gateways such as Slack. This guide builds a cautious local setup on a personal Mac mini.

Architecture

The flow is Slack message, Slack Socket Mode WebSocket, Hermes gateway, selected model, approved tool backend, then a response. Socket Mode avoids a public HTTP endpoint, but it does not make the bot safe. Tokens, allowlists, tool permissions, and the Mac account remain security boundaries.

Install on macOS

curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o install-hermes.sh
less install-hermes.sh
bash install-hermes.sh
hermes setup --portal
hermes --help

Inspect remote installers according to your policy. Start Hermes in the foreground first, confirm the provider and working directory, then configure the gateway. Use a dedicated macOS user, FileVault, automatic updates, and a separate project directory. Do not run the agent as root or give it your personal home directory.

Create the Slack app

Use Hermes’ generated Slack manifest where possible. In Slack API, create the app, enable Socket Mode, generate an app-level token with connections:write, install the app, and copy the bot token beginning with xoxb- and app token beginning with xapp-. Configure the required event subscriptions and slash commands from the current Hermes guide.

mkdir -p ~/.hermes
chmod 700 ~/.hermes
# store tokens in the Hermes environment file
chmod 600 ~/.hermes/.env

Set an allowlist of Slack member IDs and, if scheduled messages are enabled, a home channel. Test with a direct message from the allowlisted account and a read-only request before enabling tools.

Choose the execution boundary

Local execution is convenient but shares the Hermes process’ filesystem and network identity. Docker can isolate tools, but a mounted home directory, Docker socket, or host network can undo that isolation. SSH gives you a separate machine boundary, but the remote account and key become part of the agent’s perimeter. Begin with one project directory, read-only data, no destructive commands, and explicit approval for writes.

Common failures

• Slack does not connect: check Socket Mode, the xapp- token, and connections:write.
• No reply: confirm installation, channel invitation, member allowlist, and gateway status.
• Model rejected: choose a model with enough context for Hermes’ system prompt and tool schemas.
• Unexpected access: inspect mounts, environment variables, SSH keys, and tool configuration.

Security checklist

• Use a non-admin account and restrictive permissions on ~/.hermes.
• Allowlist users and channels; workspace membership is not authorization.
• Keep secrets out of prompts, logs, memory, and Slack messages.
• Require approval for deleting files, sending messages, deployments, and purchases.
• Keep the Mac behind a firewall and do not expose an unauthenticated API.

Official references: Hermes repository, Hermes Slack setup, Hermes security, and Slack Socket Mode.