# HermesWatcher: Hermes Agent reference (full text) > All HermesWatcher guides, troubleshooting, FAQ, glossary and CLI cheat sheet for Hermes Agent in one file. HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Site map for agents: https://hermeswatcher.com/llms.txt. Directories not included here: https://hermeswatcher.com/tools.md, https://hermeswatcher.com/skills.md, https://hermeswatcher.com/plugins.md, https://hermeswatcher.com/workflows.md. # What is Hermes Agent? URL: https://hermeswatcher.com/hermes-agent Hermes Agent is an open-source agent built by Nous Research and published at github.com/NousResearch/hermes-agent. You install it on your own machine or server, point it at a model provider, and talk to it through a terminal CLI or TUI, the Hermes Desktop app for macOS and Windows, or a messaging bot. The agent itself costs nothing. Model providers and optional hosted services such as the Nous Portal charge separately. Its main selling point is a built-in learning loop. When Hermes works out a multi-step workflow, recovers from errors, or gets corrected, it can save that approach as a reusable skill and patch the skill later. It also keeps two small curated memory files (agent notes and a user profile), records every session in a searchable SQLite database, and supports external memory providers for deeper user modeling. Skills follow the open agentskills.io format, and every installed skill becomes its own slash command. Hermes is built to run wherever you need it. It runs on Linux, macOS, WSL2, native Windows and Android (Termux), and the README says it can live anywhere from a $5 VPS to a GPU cluster. Its terminal tool can execute commands locally or inside Docker, SSH, Modal, Daytona, Vercel Sandbox or Singularity backends. A single gateway process connects the same agent and memory to Telegram, Discord, Slack, WhatsApp, Signal, email and many more platforms. That gateway also runs scheduled jobs and sends their results to whichever chat you pick. ### What it can do - **Self-improving skills**: The agent writes and patches its own SKILL.md files with the skill_manage tool. You can also install skills from hubs such as the official repo, skills.sh, GitHub taps and well-known endpoints. - **Persistent memory**: MEMORY.md (agent notes) and USER.md (your profile) are loaded into every session. Both are size-limited, so the agent has to keep them concise. An optional write-approval gate lets you review changes first. - **Session search**: Every CLI, TUI and gateway session is stored in ~/.hermes/state.db. The session_search tool can search that history with FTS5 full-text search. - **Messaging gateway**: One gateway process exposes the agent on more than 25 chat platforms. Access is deny-by-default and controlled with allowlists or DM pairing codes. - **Scheduled tasks**: A built-in cron scheduler accepts natural-language or cron-syntax schedules and delivers results to a chat or local files. You can create jobs from the CLI, with /cron, or just by asking. - **Subagent delegation**: The delegate_task tool starts isolated child agents with restricted toolsets for parallel work. The execute_code tool runs Python scripts that call Hermes tools. - **Sandboxed terminal backends**: Commands can run locally or in docker, ssh, modal, daytona, vercel_sandbox or singularity backends. You select one with terminal.backend. - **MCP client and server**: Hermes connects to MCP servers over stdio or HTTP, configured under mcp_servers or added with hermes mcp. With hermes mcp serve it can also act as an MCP server itself. - **Web, browser and media tools**: Toolsets cover web search and extraction, browser automation, vision, image generation and text-to-speech. Voice mode works in the CLI and in messaging apps. - **Profiles**: Profiles are fully isolated Hermes instances, each with its own config, keys, memory, skills, sessions and cron jobs. Each profile also gets its own command alias. - **Editor and API integration**: hermes acp brings Hermes into editors such as VS Code, Zed and JetBrains. An API server mode exposes it as an OpenAI-compatible endpoint for frontends like Open WebUI. - **Checkpoints and rollback**: Opt-in filesystem checkpoints (off by default) snapshot the working directory before file changes, and /rollback restores an earlier state. ### Where it runs Linux (terminal install via install.sh), macOS (terminal install, or the Hermes Desktop app; the installation docs say the desktop app is Apple Silicon only), Windows 10/11, native via PowerShell installer or Hermes Desktop app, Windows via WSL2 (WSL1 is not reliable), Android / Termux (aarch64, APT package), Docker (image nousresearch/hermes-agent) ### Model providers Nous Portal, OpenAI Codex, GitHub Copilot, GitHub Copilot ACP, Anthropic, OpenRouter, Ramp Router, Fireworks AI, NovitaAI, AI Gateway, z.ai / GLM, Kimi / Moonshot, Kimi / Moonshot (China), Arcee AI, GMI Cloud, Nebius Token Factory, Actual Computer, MiniMax, MiniMax China, xAI (Grok), xAI Grok OAuth (SuperGrok), Qwen Cloud (Alibaba DashScope), Alibaba Cloud (Coding Plan), Alibaba Cloud (Token Plan), Kilo Code, Xiaomi MiMo, Tencent TokenHub, Tencent TokenPlan, OpenCode Zen, CommandCode, OpenCode Go, DeepSeek, Hugging Face, Google / Gemini, Google Vertex AI, OpenAI API (direct), Azure AI Foundry, AWS Bedrock, NVIDIA Build, Ollama Cloud, Qwen OAuth, MiniMax OAuth, StepFun, LM Studio, Local servers: Ollama, vLLM, SGLang, llama.cpp, Custom OpenAI-compatible endpoint ### Messaging platforms Telegram, Discord, Slack, Google Chat, WhatsApp, WhatsApp Cloud API, Signal, SMS (Twilio), Email, Home Assistant (plugin), Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, WeCom Callback, Weixin (WeChat), BlueBubbles (iMessage), Photon (iMessage), QQ (QQBot), Yuanbao, Microsoft Teams, LINE, ntfy, Raft, IRC, Buzz, SimpleX Chat ### License and cost Hermes Agent is MIT-licensed open source from Nous Research. The agent itself is free; model providers and optional hosted services charge separately. Note: Reflects the official Hermes Agent docs and GitHub README as read on 2026-10-20. The latest stable release at that time was v0.22.2 (Oct 15, 2026), with nightly canary builds on top. Commands and flags change quickly between releases, so check with hermes --help. ### Sources - [Hermes Agent homepage](https://hermes-agent.nousresearch.com/) - [NousResearch/hermes-agent on GitHub](https://github.com/NousResearch/hermes-agent) - [Features overview](https://hermes-agent.nousresearch.com/docs/user-guide/features/overview) - [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) - [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) - [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) - [AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers) - [Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation/) - [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) # Quickstart URL: https://hermeswatcher.com/start ### 1. Install (Linux, macOS, WSL2) Run the official install script, then reload your shell so the hermes command is on your PATH. The script clones the source, bootstraps its own pinned toolchain, and installs the latest stable release. Prefer a GUI? macOS and Windows users can download the Hermes Desktop installer from the Hermes website instead. ```bash curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash source ~/.bashrc # or: source ~/.zshrc ``` ### 2. Install (native Windows) In PowerShell, run the Windows installer. Native Hermes runs shell commands through Git Bash, and the installer can fetch a pinned Git for Windows if Git is missing. ```powershell iex (irm https://hermes-agent.nousresearch.com/install.ps1) ``` ### 3. Or use WSL2 on Windows Choose WSL2 if you want a full Linux environment, or if you need the dashboard's embedded terminal. Install WSL2 from an admin PowerShell, reboot, and check that your distro reports VERSION 2. Hermes does not run reliably on WSL1. Then run the Linux installer inside WSL. Keep your projects in the WSL home directory, not under /mnt/c. ```bash wsl --install wsl --list --verbose curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash source ~/.bashrc ``` ### 4. Choose a model provider Run the model picker to choose a provider and model. If you have a Nous Portal subscription, the fastest route is the Portal setup, which signs you in and enables the Tool Gateway (web search, image generation, TTS, cloud browser). You can also store API keys directly. Secrets go to ~/.hermes/.env and other settings to ~/.hermes/config.yaml. The model you pick needs a context window of at least 64K tokens. ```bash hermes model hermes setup --portal hermes config set OPENROUTER_API_KEY sk-or-... # replace sk-or-... with your own key, or skip this line ``` ### 5. Start your first chat Launch the classic CLI with hermes, or the newer TUI (recommended in the docs) with hermes --tui. Start with a concrete prompt you can check, such as asking it to summarize the repo you are in. Type / to see slash commands, and press Ctrl+C or send a new message to interrupt. ```bash hermes hermes --tui ``` ### 6. Resume and one-shot tasks Pick up your most recent session, or run a single query without opening the interactive UI. hermes -z prints only the final reply, which makes it handy in scripts. ```bash hermes --continue hermes chat --oneshot -q "Summarize this repo in 5 bullets and tell me what the main entrypoint is" hermes -z "What changed in the last commit?" ``` ### 7. Add tools and skills Choose which toolsets are enabled on each platform, and browse the skills hub. Installed skills show up as slash commands. ```bash hermes tools hermes skills browse hermes skills install ``` ### 8. Optional: connect a messaging app Run the interactive gateway setup for Telegram, Discord, Slack or another platform, then start the gateway. Installing it as a service keeps the bot and scheduled jobs running in the background. Unknown users are refused until you allowlist them or approve their pairing code. ```bash hermes gateway setup hermes gateway install hermes gateway start hermes gateway status hermes pairing list ``` ### 9. If something breaks The docs suggest this recovery order: run diagnostics, recheck the model and auth, rerun setup, then check sessions and gateway status. ```bash hermes doctor hermes model hermes setup hermes sessions list hermes gateway status ``` ### Sources - [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) - [Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation/) - [Windows (WSL2) Quickstart](https://hermes-agent.nousresearch.com/docs/user-guide/windows-wsl-quickstart) - [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) - [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) # Messaging platforms # Hermes Agent messaging: Telegram, Slack, WhatsApp, iMessage, more > 28 platforms in the official comparison table, plus 11 other ways in. Canonical: https://hermeswatcher.com/messaging ## Which one should you use? Start with the app and account you already have. These picks are editorial suggestions based on the documented setup requirements. Not sure? [Get a setup plan in five questions](https://hermeswatcher.com/planner). - **Only you, on your phone:** [Telegram](https://hermeswatcher.com/learn/hermes-agent-telegram-setup.md). Use Create with QR in the dashboard or Desktop (Messaging → Telegram), or create the bot manually with your numeric user ID. - **Your team already uses a chat app:** [Slack](https://hermeswatcher.com/learn/hermes-agent-slack-setup.md) / [Discord](https://hermeswatcher.com/learn/hermes-agent-discord-setup.md) / [Microsoft Teams](https://hermeswatcher.com/learn/hermes-agent-microsoft-teams-setup.md) / [Google Chat](https://hermeswatcher.com/learn/hermes-agent-google-chat-setup.md). Use the app your team already uses. Check app installation rights first. - **Privacy first:** [Signal](https://hermeswatcher.com/learn/hermes-agent-signal-setup.md) / [SimpleX Chat](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/simplex) / [Matrix](https://hermeswatcher.com/learn/hermes-agent-matrix-setup.md). Signal is end-to-end encrypted between devices. signal-cli on your computer decrypts messages so Hermes can read them. Your Hermes host, model provider and tools see what you send. Alternatives include SimpleX (no persistent user IDs) and Matrix with encryption enabled. - **iPhone and iMessage:** [Photon (iMessage)](https://hermeswatcher.com/learn/hermes-agent-imessage-photon-setup.md) / [BlueBubbles (iMessage)](https://hermeswatcher.com/learn/hermes-agent-imessage-bluebubbles-setup.md). Photon is a third-party managed iMessage service, with no Mac needed. Messages pass through its service. Its free shared-line pool can show different sending numbers to different recipients; a dedicated number is a paid tier. BlueBubbles uses your own Mac, which must stay on and signed into Messages. - **WhatsApp for a business:** [WhatsApp Business Cloud API](https://hermeswatcher.com/learn/hermes-agent-whatsapp-business-cloud-api-setup.md). Meta's official route needs a business account and a public HTTPS address. Hermes handles direct chats only and can reply freely only within 24 hours of the sender's last message. The guide starts with a private bot for you and named staff; review tool access before letting customers use it. - **Personal WhatsApp:** [WhatsApp (Baileys bridge)](https://hermeswatcher.com/learn/hermes-agent-whatsapp-setup.md). The unofficial Baileys bridge has account restriction risk. The docs recommend a dedicated number. - **Self-hosted chat:** [Matrix](https://hermeswatcher.com/learn/hermes-agent-matrix-setup.md) / [Mattermost](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/mattermost). Connect a bot to your homeserver or team server. Matrix needs a Linux or WSL2 adapter, or the documented Linux-container Proxy Mode for a native macOS or Windows agent. - **A browser chat window:** [Hermes Webapp (browser and phone)](https://hermes-agent.nousresearch.com/docs/user-guide/desktop#use-the-desktop-workspace-from-a-browser) / [Dashboard Chat tab](https://hermes-agent.nousresearch.com/docs/user-guide/features/web-dashboard#chat) / [Open WebUI + API server](https://hermeswatcher.com/learn/hermes-agent-open-webui-setup.md). Hermes Webapp and Dashboard Chat are first-party browser routes. Open WebUI is a third-party interface to the API server. Tools run on the Hermes host. - **Your team uses regional apps:** [Feishu / Lark](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/feishu) / [DingTalk](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/dingtalk) / [WeCom (Enterprise WeChat)](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/wecom) / [LINE](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/line). Each needs an organization or developer account on that platform; compare the requirements before choosing. - **Texting without another app:** [SMS (Twilio)](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/sms). SMS through Twilio needs a public callback URL and has provider charges. - **Just alerts:** [ntfy](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/ntfy). Subscribe to a topic for push replies. It can also accept prompts; protect topic access. - **Scripts and other tools:** [Webhooks](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/webhooks) / [Open WebUI + API server](https://hermeswatcher.com/learn/hermes-agent-open-webui-setup.md) / [A2A (Agent-to-Agent)](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/a2a). Webhooks receive signed events, the API server accepts client requests, and A2A exchanges tasks with other agents. ## Before you pick - **One gateway can connect several platforms.** Configure one app first, then add others to the same gateway. Conversations have their own sessions. - **The computer must stay on.** Replies need an awake, networked host and any required gateway, bridge or daemon. The bot is silent while the host sleeps. Desktop has Settings → Advanced → Keep computer awake for long runs, but closing the lid or choosing Sleep still sleeps the machine. An always-on host is another option. - **Choose who can use it.** An allowlist is a list of approved user or chat IDs. Pairing is another option: an unknown person gets a one-time code, and you approve it on your computer. A code alone grants nothing. Some platforms suppress codes when an allowlist is set; WhatsApp's bridge can still send them by default. Access rules do not limit the agent's tools; configure tools and approvals separately. - **Decide where scheduled results go.** A job you create in a chat normally reports back there. A job you create in the terminal saves its result on the computer. Use `/sethome` in a supported chat to make it the default for a platform-only delivery target. Check delivery separately from task completion. - **Start with `hermes gateway setup`.** The official setup command walks through platform selection. Keep bot tokens secret and configure access before inviting other people. [How the messaging gateway works](https://hermeswatcher.com/learn/messaging-gateway-explained.md) · [Run Hermes Agent 24/7](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md) ## All platforms Difficulty is our estimate of setup effort. Features follow the official comparison table. Yes: the table lists support. Not listed: it does not mark support (the guide may say more). Voice: voice notes or spoken replies, not live calls. Streaming: the reply fills in as it is written. Feature notes under each platform explain the differences. ### Personal chat #### Telegram built-in · easy (our estimate) · Needs: bot token, numeric user ID Chat with Hermes through a Telegram bot, with text, attachments and voice notes. The overview lists: voice, images, files, threads, typing, streaming. Feature note: The official overview table doesn't mark reactions, but the Telegram page describes them. [Telegram feature source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/telegram.md#L1343-L1371) [Telegram setup guide](https://hermeswatcher.com/learn/hermes-agent-telegram-setup.md) [Telegram official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram) #### WhatsApp (Baileys bridge) unofficial bridge · medium (our estimate) · Needs: phone number, Node.js 18+, QR pairing An unofficial linked WhatsApp Web session through a managed Node bridge. The overview lists: images, files, typing, streaming. Feature note: The official overview table doesn't mark voice, but the WhatsApp page describes voice transcription and spoken replies sent as attachments. [WhatsApp (Baileys bridge) feature source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/whatsapp.md#L233-L238) Feature note: The Cloud API comparison says the bridge has no read receipts or typing indicators. The bridge page describes optional read receipts, and the overview lists typing indicators. Check the individual feature instructions for your setup. [WhatsApp (Baileys bridge) feature source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/whatsapp-cloud.md#L393-L410) [WhatsApp (Baileys bridge) setup guide](https://hermeswatcher.com/learn/hermes-agent-whatsapp-setup.md) [WhatsApp (Baileys bridge) official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp) #### WhatsApp Business Cloud API built-in · hard (our estimate) · Needs: business phone number, Meta Business account, public HTTPS URL Meta official WhatsApp Business messaging via signed inbound webhooks and Graph API outbound. The overview lists: voice, images, files, typing. [WhatsApp Business Cloud API setup guide](https://hermeswatcher.com/learn/hermes-agent-whatsapp-business-cloud-api-setup.md) [WhatsApp Business Cloud API official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp-cloud) #### Signal built-in · medium (our estimate) · Needs: Signal account, external signal-cli daemon (Hermes docs: Java 17+; check signal-cli's current release notes), computer that stays on Chat through an external signal-cli daemon, which passes messages to Hermes. The overview lists: images, files, typing. Feature note: The official overview table doesn't mark voice or reactions, but the Signal page describes audio messages and reactions. [Signal feature source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/signal.md#L148-L182) [Signal setup guide](https://hermeswatcher.com/learn/hermes-agent-signal-setup.md) [Signal official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/signal) #### SMS (Twilio) built-in · medium (our estimate) · Needs: Twilio account and number, public endpoint, vendor usage charges Standard SMS conversations backed by Twilio webhooks and outbound REST sends. The overview does not list these media and interaction features. See the platform docs for text and event handling. [SMS (Twilio) official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/sms) #### Email built-in · medium (our estimate) · Needs: dedicated IMAP/SMTP account, provider authentication, trusted mail authentication Send tasks to a dedicated inbox and receive threaded email replies. The overview lists: images, files, threads. [Email setup guide](https://hermeswatcher.com/learn/hermes-agent-email-setup.md) [Email official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/email) ### Team and work chat #### Discord built-in · easy (our estimate) · Needs: bot token, Manage Server permission, Message Content Intent A Discord bot for DMs, server channels, threads and voice. The overview lists: voice, images, files, threads, reactions, typing, streaming. [Discord setup guide](https://hermeswatcher.com/learn/hermes-agent-discord-setup.md) [Discord official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord) #### Slack built-in · medium (our estimate) · Needs: workspace app permission, bot and app tokens Chat through a Slack bot using an outbound connection, without a public callback URL. The overview lists: voice, images, files, threads, reactions, typing, streaming. [Slack setup guide](https://hermeswatcher.com/learn/hermes-agent-slack-setup.md) [Slack official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/slack) #### Google Chat built-in · hard (our estimate) · Needs: Google Workspace, app publishing rights, Cloud project, service account Chat through a Google Workspace app using a Cloud Pub/Sub pull subscription. The overview lists: images, files, threads, typing. Feature note: The overview lists images and files. Native file uploads need each user to complete `/setup-files` OAuth, which grants the required Google account permission. Without it, Hermes uses inline links and download cards. [Google Chat feature source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/google_chat.md#L260-L335) [Google Chat setup guide](https://hermeswatcher.com/learn/hermes-agent-google-chat-setup.md) [Google Chat official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/google_chat) #### Microsoft Teams built-in · hard (our estimate) · Needs: Microsoft tenant, bot registration rights, public HTTPS URL A Teams bot receiving Bot Framework webhook messages and replying in Teams. The overview lists: images, threads, typing. [Microsoft Teams setup guide](https://hermeswatcher.com/learn/hermes-agent-microsoft-teams-setup.md) [Microsoft Teams official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/teams) #### Raft built-in · medium (our estimate) · Needs: Raft workspace, External Agent permission, authenticated CLI Receive Raft wake notifications, then let Hermes read and reply through the Raft CLI. The overview does not list these media and interaction features. See the platform docs for text and event handling. [Raft official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/raft) #### Buzz built-in · medium (our estimate) · Needs: Buzz CLI, relay URL, member private key Chat through Buzz community channels or direct messages, using its CLI and a Nostr relay. The overview lists: images, threads. Feature note: The official overview table doesn't mark files, but the Buzz page describes incoming images, audio, video and documents. That description does not establish support for sending arbitrary files. [Buzz feature source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/buzz.md#L5-L9) [Buzz official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/buzz) ### iPhone and iMessage #### BlueBubbles (iMessage) built-in · hard (our estimate) · Needs: a Mac that stays on, Messages login, BlueBubbles Server An always-on Mac Messages account bridged to Hermes by BlueBubbles webhooks and REST. The overview lists: images, files, reactions, typing. Feature note: The official overview table doesn't mark voice, but the BlueBubbles page describes voice attachments. Reactions and typing indicators need the Private API helper. [BlueBubbles (iMessage) feature source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/bluebubbles.md#L129-L131) Feature note: Reactions, typing indicators, read receipts and new chats by address need the Private API helper. Basic sending can also need it when the Mac user is logged out or running in the background. [BlueBubbles (iMessage) feature source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/bluebubbles.md#L177-L199) [BlueBubbles (iMessage) setup guide](https://hermeswatcher.com/learn/hermes-agent-imessage-bluebubbles-setup.md) [BlueBubbles (iMessage) official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/bluebubbles) #### Photon (iMessage) built-in · medium (our estimate) · Needs: Photon account, iMessage-capable number, Node.js, a few terminal commands, messages route through Photon's service Use a managed iMessage line through Photon, without a local Mac relay. The overview lists: voice, images, files, reactions, typing. Feature note: The overview lists images, files and voice. Incoming attachments provide metadata, such as file details, rather than file contents. Hermes can send outgoing attachments. [Photon (iMessage) feature source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/photon.md#L199-L209) [Photon (iMessage) setup guide](https://hermeswatcher.com/learn/hermes-agent-imessage-photon-setup.md) [Photon (iMessage) official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/photon) ### Self-hosted and open #### Mattermost built-in · medium (our estimate) · Needs: Mattermost server, bot token, admin for bot enablement Chat with a bot in Mattermost direct messages or team channels. The overview lists: voice, images, files, threads, typing, streaming. [Mattermost official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/mattermost) #### Matrix built-in · medium; hard with encryption (our estimate) · Needs: Linux or WSL2 adapter, or Linux container Proxy Mode, Matrix account, matrix extra, libolm for encryption Chat through a Matrix bot, with media, threads and configurable room encryption. The overview lists: voice, images, files, threads, reactions, typing, streaming. [Matrix setup guide](https://hermeswatcher.com/learn/hermes-agent-matrix-setup.md) [Matrix official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/matrix) #### SimpleX Chat built-in · medium (our estimate) · Needs: SimpleX CLI daemon, contacts Chat through a local SimpleX daemon and its established contacts. The overview lists: voice, images, files, typing. Feature note: The overview lists typing indicators, while the adapter's platform hint says they are unavailable. Check the behavior of your installed version before relying on them. [SimpleX Chat feature source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/plugins/platforms/simplex/adapter.py#L699-L719) [SimpleX Chat official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/simplex) #### IRC built-in · easy (our estimate) · Needs: IRC server, bot nickname Plain-text Hermes conversations on IRC channels or DMs. The overview does not list these media and interaction features. See the platform docs for text and event handling. [IRC official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/irc) ### Regional (China, Japan) #### DingTalk built-in · medium (our estimate) · Needs: organization account, app credentials, DingTalk extra Chat through a DingTalk robot using an outbound Stream Mode connection. The overview lists: images, files, reactions, streaming. [DingTalk official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/dingtalk) #### Feishu / Lark built-in · medium (our estimate) · Needs: workspace app permissions, app credentials A Feishu/Lark bot with outbound WebSocket or inbound webhook transport. The overview lists: voice, images, files, threads, reactions, typing, streaming. [Feishu / Lark official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/feishu) #### WeCom (Enterprise WeChat) built-in · medium (our estimate) · Needs: WeCom organization, AI Bot credentials Chat through a WeCom AI Bot using an outbound WebSocket connection. The overview lists: voice, images, files. Feature note: The official overview table doesn't mark typing or streaming, but the WeCom page describes streamed messages and a thinking indicator when `streaming.enabled` is on. [WeCom (Enterprise WeChat) feature source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/wecom.md#L102-L110) [WeCom (Enterprise WeChat) official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/wecom) #### WeCom Callback (self-built application) built-in · hard (our estimate) · Needs: enterprise admin, app credentials, public HTTPS URL Reach a self-built WeCom enterprise app through encrypted message callbacks. The overview does not list these media and interaction features. See the platform docs for text and event handling. [WeCom Callback (self-built application) official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/wecom-callback) #### Weixin / WeChat built-in · medium (our estimate) · Needs: WeChat account, QR login Chat through a personal WeChat bot identity, with QR login and long polling. The overview lists: voice, images, files, typing. Feature note: QR login creates a separate iLink bot identity. It usually cannot join ordinary WeChat groups. [Weixin / WeChat feature source](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/weixin) [Weixin / WeChat official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/weixin) #### QQ Bot built-in · medium (our estimate) · Needs: QQ bot application, app credentials, message intents Chat through the official QQ Bot API in direct, group-mention and guild conversations. The overview lists: voice, images, files, typing. [QQ Bot official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/qqbot) #### Yuanbao built-in · medium (our estimate) · Needs: Yuanbao account, bot creation permission Chat with a Yuanbao bot in direct or group conversations. The overview lists: voice, images, files, typing, streaming. [Yuanbao official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/yuanbao) #### LINE built-in · medium (our estimate) · Needs: LINE Messaging API channel, channel credentials, public HTTPS URL Chat through a LINE Messaging API bot with signed incoming message callbacks. The overview lists: images, files, typing. Feature note: The official overview table doesn't mark voice, but the LINE page describes incoming audio and outgoing voice links. Typing and loading indicators are limited to DMs. LINE has no message-editing API. [LINE feature source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/line.md#L196-L201) [LINE official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/line) ### Notifications and automation #### Home Assistant catalog plugin · medium (our estimate) · Needs: Home Assistant instance, long-lived token, catalog plugin An event/notification and device-control plugin, not an ordinary two-way human messenger. The overview does not list these media and interaction features. See the platform docs for text and event handling. [Home Assistant official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/homeassistant) #### ntfy built-in · easy (our estimate) · Needs: topic, subscribed client, topic access controls Text pub/sub topics that let a phone, script or browser send prompts and receive push replies. The overview does not list these media and interaction features. See the platform docs for text and event handling. [ntfy official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/ntfy) #### Webhooks built-in · medium (our estimate) · Needs: event source, receiver URL, signing secret Receive signed events from external services, then run a task or deliver a message. No row in the overview feature table. See the official docs for capabilities. [Webhooks official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/webhooks) #### Microsoft Teams Meetings workflow built-in · hard (our estimate) · Needs: tenant admin consent, Graph permissions, public HTTPS URL, pipeline plugin Summarize Microsoft Teams meeting transcripts through a Microsoft Graph workflow. No row in the overview feature table. See the official docs for capabilities. [Microsoft Teams Meetings workflow official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/teams-meetings) #### Microsoft Graph webhook listener built-in · hard (our estimate) · Needs: Graph subscription privileges, public HTTPS URL, clientState secret Receive Microsoft Graph change notifications for downstream meeting and event workflows. No row in the overview feature table. See the official docs for capabilities. [Microsoft Graph webhook listener official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/msgraph-webhook) #### Google Meet built-in · medium (our estimate) · Needs: built-in google_meet plugin, documented meeting setup Join and transcribe Meet calls, with optional spoken replies. This is a meeting tool, not a chat gateway. No row in the overview feature table. See the official docs for capabilities. Feature note: The Built-in Plugins table says 'optional realtime duplex audio', but the google_meet section says realtime mode is speak-only, with input from live captions. Follow the narrower description. [Google Meet feature source](https://hermes-agent.nousresearch.com/docs/user-guide/features/built-in-plugins#google_meet) [Google Meet official docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/built-in-plugins#google_meet) ### Hermes's own apps #### Hermes Webapp (browser and phone) built-in · medium (our estimate) · Needs: Webapp enabled, for other devices, Settings → Web Access (Nous account sign-in) or the dashboard sign-in gate, HTTPS or a tunnel recommended (plain HTTP turns off mic and notifications; use only a trusted network) Use the Desktop workspace in a browser, including from your phone. No row in the overview feature table. See the official docs for capabilities. [Hermes Webapp (browser and phone) official docs](https://hermes-agent.nousresearch.com/docs/user-guide/desktop#use-the-desktop-workspace-from-a-browser) #### Hermes Desktop connected to a remote Hermes built-in · medium (our estimate) · Needs: Hermes running on another machine, reached through a remote gateway, SSH or Hermes Cloud, documented authentication Chat from Desktop with Hermes running on another machine. No row in the overview feature table. See the official docs for capabilities. [Hermes Desktop connected to a remote Hermes official docs](https://hermes-agent.nousresearch.com/docs/user-guide/desktop#connecting-to-a-remote-backend) #### Dashboard Chat tab built-in · medium (our estimate) · Needs: running web dashboard, protected access, Node.js, Linux, macOS or WSL2 (the Chat tab needs a terminal session, so native Windows is not supported) Use the Hermes terminal interface from the dashboard in your browser. No row in the overview feature table. See the official docs for capabilities. [Dashboard Chat tab official docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/web-dashboard#chat) #### ACP in code editors built-in · medium (our estimate) · Needs: an editor that supports ACP, Hermes ACP extra installed (`hermes acp`) ACP (Agent Client Protocol) is a standard way for code editors to talk to agents. Use Hermes inside an editor that supports ACP. No row in the overview feature table. See the official docs for capabilities. [ACP in code editors official docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/acp) ### Browser and API clients #### Open WebUI + API server built-in · medium (our estimate) · Needs: Hermes model, API key of 16+ characters, compatible client Use a browser chat frontend or script with the Hermes OpenAI-compatible API server. No row in the overview feature table. See the official docs for capabilities. [Open WebUI + API server setup guide](https://hermeswatcher.com/learn/hermes-agent-open-webui-setup.md) [Open WebUI + API server official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/open-webui) #### A2A (Agent-to-Agent) built-in · hard (our estimate) · Needs: reachable HTTP endpoint for inbound, peer credentials Exchange tasks with other independent agents through the Agent-to-Agent protocol. No row in the overview feature table. See the official docs for capabilities. [A2A (Agent-to-Agent) official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/a2a) ### Experimental #### Hermes Relay (experimental) experimental · hard (our estimate) · Needs: provisioned connector, tenant route, enrollment token An experimental connector route for real chat platforms. Features are negotiated with the connector. [Hermes Relay (experimental) official docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/relay) ## Other ways in For other routes, see [Hermes's own apps](https://hermeswatcher.com/messaging#group-hermes-s-own-apps), [Notifications and automation](https://hermeswatcher.com/messaging#group-notifications-and-automation), [Browser and API clients](https://hermeswatcher.com/messaging#group-browser-and-api-clients) and [Experimental](https://hermeswatcher.com/messaging#group-experimental). The [official Plugin Catalog](https://hermes-agent.nousresearch.com/docs/plugins) also lists community-maintained platform plugins on its Platforms shelf. Check each entry's maintainer and disclosure. ## Questions ### Can you use several platforms at once? Yes. One gateway process can connect several configured platforms. Start with one, then add the others and their access settings. ### Does your computer need to stay on? Yes. The host needs to be awake and online, with any required gateway and bridge components running. An always-on host can keep answering while your personal laptop is off. ### Which WhatsApp route should you use? The personal Baileys bridge is unofficial and carries account restriction risk. The docs recommend a dedicated number. Cloud API is Meta's official business route. Hermes supports direct chats and free-form replies within 24 hours of the sender's last message, with no template sending outside that window. Protect credentials and limit agent access on either route. ### Do you need a public URL? It depends on the route. Telegram polling, Slack Socket Mode and Google Chat's Pub/Sub pull route do not need a public callback. Teams, WhatsApp Cloud API, LINE, SMS (Twilio), WeCom Callback and the Microsoft Graph listener need a provider-reachable public address. Webhooks and A2A inbound need an address their callers can reach; local callers can use a local endpoint. Telegram can optionally use webhook mode on cloud hosts. A public HTTPS URL is an encrypted web address the provider can reach. A tunnel can forward it to a local receiver; authenticate and secure that receiver. ### Who can talk to your bot? For human chat, configure explicit grants such as an allowlist or approved pairing. Unknown users cannot execute work without a grant. They may be ignored or receive a pairing code, depending on the platform and policy. WhatsApp's bridge sends codes by default even with an allowlist; its guide shows the private-number ignore policy. On Photon, an unknown sender may still get a pairing code. A code does nothing until you approve it, so approve only people you recognize. Email ignores unknown senders by default. API clients and service events have their own authentication boundaries. Reviewed Oct 29, 2026 against the official Hermes docs. --- HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt # Guides ## How to install Hermes Agent on Windows (native or WSL2) > Hermes Agent runs natively on Windows 10 and 11. Pick the desktop app or the PowerShell installer, or use WSL2 if you need a Linux setup. URL: https://hermeswatcher.com/learn/install-hermes-agent-windows Last reviewed: Oct 28, 2026 ### Short answer Yes, Windows is officially supported. The official docs list Windows 10 and 11 (x86_64 and ARM64) as Tier 1, which means the team aims never to break installs and updates there. They also say Hermes runs natively on Windows, with no WSL, Cygwin or Docker needed. You have two native options and one alternative: - Desktop app: the easiest route. It bundles the agent, Python, dependencies and the interfaces. It needs Windows 11 22H2 or later. - Command line installer (PowerShell): works on Windows 10 and 11. Choose this if you are on Windows 10 or only want the terminal. - WSL2: run the Linux installer inside WSL2. Choose this if you do POSIX-heavy development work or want the same setup as Linux. Native and WSL2 installs can live side by side on the same PC. If you are unsure, start native. ### What you need - Windows 10 or 11 for the PowerShell installer. Windows 11 22H2 or later for the desktop app package. - No admin rights for a native install. - No Python or Node.js. The installer provides Python 3.14, Node.js, npm, ripgrep and FFmpeg. If Git is missing, it sets up its own pinned copy of Git for Windows. - For WSL2: Windows 10 22H2 or later, or Windows 11. The docs test against Ubuntu LTS. Debian also works. WSL1 is not reliable. - Windows Terminal is recommended. Legacy `cmd.exe` has Unicode problems. ### Install Desktop app: download the `.appinstaller` file from hermes-agent.nousresearch.com and open it with Windows App Installer. A Microsoft Store version also exists. Command line (native): open PowerShell and run the first command below. No admin window is needed. WSL2 instead: install WSL from an Admin PowerShell window, then run the Linux installer inside your WSL distro. PowerShell (native): ``` iex (irm https://hermes-agent.nousresearch.com/install.ps1) ``` Admin PowerShell (WSL2 only): ``` wsl --install ``` Inside WSL: ``` curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash source ~/.bashrc hermes ``` The native installer adds Hermes to your user PATH. Existing terminals do not see that change, so close PowerShell and open a new window before you continue. In WSL2, keep your projects on the Linux side, not under `/mnt/c`. The WSL2 guide says files under `/mnt/c` are 10 to 100 times slower. ### First run and setup In a new PowerShell window, type `hermes` to start chatting. Before that, connect a model. The official docs list these commands: PowerShell: ``` hermes model # Choose your LLM provider and model hermes tools # Configure which tools are enabled hermes gateway setup # Set up messaging platforms hermes config set # Set individual config values hermes config get # Inspect individual config values hermes setup # Or run the full setup wizard to configure everything at once ``` The setup wizard offers three modes on a fresh install. Quick Setup uses a Nous Portal login, so there are no API keys to manage. Full Setup lets you bring your own keys. Blank Slate turns on only your provider and model, plus the File Operations and Terminal toolsets. If you only want to pick a provider and model, run `hermes model` instead of the full wizard. The official docs say Hermes needs a model with at least 64,000 tokens of context. Smaller models are rejected at startup. Using the Nous Portal? `hermes setup --portal` logs you in, sets Nous as your provider and turns on the Tool Gateway in one step. Run `hermes doctor` any time to check the install. ### Where your settings live and how to update - Native: everything is under `%LOCALAPPDATA%\hermes\`. Secrets are in `%LOCALAPPDATA%\hermes\.env`, launchers in `%LOCALAPPDATA%\hermes\bin\` and the code in `%LOCALAPPDATA%\hermes\hermes-agent\`. - WSL2: settings are in `~/.hermes/` inside the Linux side, as on Linux. - Update a command line or WSL2 install with `hermes update`. - Update a sideloaded desktop app with its in-app Update control and Windows App Installer. The Store version updates through the Microsoft Store. For backups and rollback before a big update, see /learn/updating-hermes-safely. ### Common problems - `hermes` is not found right after install: open a new PowerShell window. The PATH change only reaches new terminals. - Antivirus flags `uv.exe`: the README calls this a false positive for `%LOCALAPPDATA%\hermes\bin\uv.exe`. It gives verification steps and this exclusion, run from an Admin PowerShell: `Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\hermes\bin"`. - The `[scriptblock]::Create` form of the installer fails: use the plain `irm` and `iex` one-liner above instead. - On Windows ARM64, some optional extras are not available, such as Faster-Whisper speech-to-text. - In WSL2, OAuth logins fail after the PC sleeps: the clock has drifted. Run `sudo hwclock -s` inside WSL. - In WSL2, scripts break with odd errors: check for Windows CRLF line endings. More fixes are in /troubleshoot/windows-specific-problems and /troubleshoot/install-or-update-failed. ### Next step Next: follow /learn/first-24-hours-default-setup to get a safe default setup. When the CLI chat works, connect a chat app with the messaging gateway: /learn/messaging-gateway-explained. ### Related tools - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Desktop: manage conversations and inspect artifacts visually](https://hermeswatcher.com/tools/desktop.md) - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) ### Sources - [Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation) - [Platform Support](https://hermes-agent.nousresearch.com/docs/getting-started/platform-support) - [Windows (Native) Guide](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native) - [Windows (WSL2) Guide](https://hermes-agent.nousresearch.com/docs/user-guide/windows-wsl-quickstart) - [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) - [Updating & Uninstalling](https://hermes-agent.nousresearch.com/docs/getting-started/updating) - [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) - [Hermes Agent README](https://github.com/NousResearch/hermes-agent) ## How to install Hermes Agent on Mac > Hermes Agent officially supports Apple Silicon Macs. Install the desktop app or run the one-line terminal installer, then pick a model to start. URL: https://hermeswatcher.com/learn/install-hermes-agent-mac Last reviewed: Oct 28, 2026 ### Short answer Yes, Macs with Apple Silicon (M1 and later) are officially supported. The official docs list macOS on Apple Silicon as Tier 1, which means the team aims never to break installs and updates there. Intel Macs are not officially supported. The Installation page says the macOS installer is Apple Silicon only, and the desktop bootstrap installer reports that it is not supported on an Intel Mac. There are two ways to install: - Desktop app: the route the Quickstart recommends. It bundles the agent, Python, dependencies and the interfaces. - Command line installer: one command in Terminal. Choose this if you only want the terminal or plan to run Hermes as a background service. ### What you need - A Mac with Apple Silicon. - For the command line installer: Git, curl, tar and SHA-256 utilities. - No Python or Node.js. The installer provides Python 3.14, Node.js, npm, ripgrep and FFmpeg. - Do not use Homebrew (`brew install hermes-agent`) or pip. The Platform Support page lists both as unsupported install methods. ### Install Desktop app: download it from hermes-agent.nousresearch.com, open the DMG, then copy `Hermes.app` to Applications. Command line: open Terminal and run the official one-liner. Terminal: ``` curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` The installer clones the source, sets up its own Python 3.14 and tools, and by default also adds a pinned Chromium for the browser tool. New installs follow the stable channel, which is the latest published release. Started with the command line and want the app too? Run `hermes desktop`. ### First run and setup Reload your shell so it can find the `hermes` command, then start chatting. Terminal: ``` source ~/.zshrc hermes ``` Terminal: ``` hermes model # Choose your LLM provider and model hermes tools # Configure which tools are enabled hermes gateway setup # Set up messaging platforms hermes config set # Set individual config values hermes config get # Inspect individual config values hermes setup # Or run the full setup wizard to configure everything at once ``` The setup wizard offers three modes on a fresh install. Quick Setup uses a Nous Portal login, so there are no API keys to manage. Full Setup lets you bring your own keys. Blank Slate turns on only your provider and model, plus the File Operations and Terminal toolsets. If you only want to pick a provider and model, run `hermes model` instead of the full wizard. The official docs say Hermes needs a model with at least 64,000 tokens of context. Smaller models are rejected at startup. Using the Nous Portal? `hermes setup --portal` logs you in, sets Nous as your provider and turns on the Tool Gateway in one step. `hermes doctor` checks the install. Want a local model instead of an API? The docs' Run Local LLMs on Mac guide targets Apple Silicon and says its 9B starter model fits comfortably in 8 GB or more of unified memory. ### Where your settings live and how to update - Secrets such as API keys: `~/.hermes/.env`. - Other settings: `~/.hermes/config.yaml`. - The agent's identity file is `~/.hermes/SOUL.md`. Memories are in `~/.hermes/memories/`. - The command is `~/.local/bin/hermes` and the code is in `~/.hermes/hermes-agent/`. - Update the desktop app with its in-app Update control. - Update a command line install with `hermes update`. Before a big update, read /learn/updating-hermes-safely. ### Common problems - `hermes: command not found`: reload your shell with `source ~/.zshrc`, or open a new Terminal window. - Permission denied on `source ~/.zshrc`: the file permissions are wrong. The FAQ fix is `chmod 644 ~/.zshrc`. - Running the gateway as a background service and it cannot find Node or ffmpeg: launchd uses a minimal PATH. Run `hermes gateway install` again after installing new tools so it captures the updated PATH. - Do not use sudo with the installer. The FAQ says it installs to `~/.local/bin`. Still stuck? See /troubleshoot/install-or-update-failed. ### Next step Next: follow /learn/first-24-hours-default-setup. To reach your agent from your phone, connect a chat app with the messaging gateway: /learn/messaging-gateway-explained. On a Mac, `hermes gateway install` sets it up as a launchd agent so it starts when you log in. ### Related tools - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Desktop: manage conversations and inspect artifacts visually](https://hermeswatcher.com/tools/desktop.md) - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) ### Sources - [Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation) - [Platform Support](https://hermes-agent.nousresearch.com/docs/getting-started/platform-support) - [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) - [Updating & Uninstalling](https://hermes-agent.nousresearch.com/docs/getting-started/updating) - [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) - [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) - [Which File Does What](https://hermes-agent.nousresearch.com/docs/user-guide/which-file-does-what) - [Run Local LLMs on Mac](https://hermes-agent.nousresearch.com/docs/guides/local-llm-on-mac) ## How to install Hermes Agent on Linux > Hermes Agent officially supports 64-bit Linux on x86_64 and ARM. Run the one-line installer as your normal user, then set up a model to start. URL: https://hermeswatcher.com/learn/install-hermes-agent-linux Last reviewed: Oct 28, 2026 ### Short answer Yes, Linux is officially supported. The official docs list Linux on x86_64 and aarch64 (64-bit ARM) as Tier 1, which means the team aims never to break installs and updates there. The docs say they test on the latest Ubuntu and WSL2. They add that a distro with glibc, systemd and a standard filesystem layout is likely to work well. On Linux, the main route is the command line installer. If you prefer containers, see /learn/install-hermes-agent-docker. ### What you need - A 64-bit Linux system: x86_64 or aarch64. - Git, curl, tar and SHA-256 utilities. - No Python or Node.js. The installer provides Python 3.14, Node.js, npm, ripgrep and FFmpeg. - Minimal Debian or Ubuntu images lack `libatomic.so.1`. The installer installs `libatomic1` for you, and asks for your sudo password once if needed. - Some source builds need a compiler and dev libraries. The browser tool's Chromium needs system libraries from your distro. Raspberry Pi: the official docs do not mention it by name. What they support is 64-bit ARM Linux (aarch64), and a Pi running a 64-bit OS falls under that category. 32-bit ARM is not supported. The installer only accepts arm64/aarch64 and x86_64/amd64. On a 32-bit OS it stops with a message that Hermes does not support this host. ### Install Run the official one-liner as your normal user. Do not add sudo. bash: ``` curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` The installer clones the source, sets up its own Python 3.14 and tools, and by default adds a pinned Chromium for the browser tool. New installs follow the stable channel, which is the latest published release. ### First run and setup Reload your shell, then start chatting. bash: ``` source ~/.bashrc # or: source ~/.zshrc hermes # Start chatting! ``` bash: ``` hermes model # Choose your LLM provider and model hermes tools # Configure which tools are enabled hermes gateway setup # Set up messaging platforms hermes config set # Set individual config values hermes config get # Inspect individual config values hermes setup # Or run the full setup wizard to configure everything at once ``` The setup wizard offers three modes on a fresh install. Quick Setup uses a Nous Portal login, so there are no API keys to manage. Full Setup lets you bring your own keys. Blank Slate turns on only your provider and model, plus the File Operations and Terminal toolsets. If you only want to pick a provider and model, run `hermes model` instead of the full wizard. The official docs say Hermes needs a model with at least 64,000 tokens of context. Smaller models are rejected at startup. `hermes --tui` opens the newer terminal interface, which the docs recommend. `hermes doctor` checks the install, and `hermes --continue` resumes your last session. ### Where your settings live and how to update - Secrets: `~/.hermes/.env`. Other settings: `~/.hermes/config.yaml`. - Identity file: `~/.hermes/SOUL.md`. Memories: `~/.hermes/memories/`. - The command is `~/.local/bin/hermes` and the code is in `~/.hermes/hermes-agent/`. - Update with `hermes update`. Preview first with `hermes update --check`. - Switch channels with `hermes update --set-channel main` or `hermes update --set-channel stable`. For backups and rollback, see /learn/updating-hermes-safely. ### Common problems - You ran the installer with sudo: the FAQ says not to, because it installs to `~/.local/bin`. Running as root puts everything in root's home. - `hermes: command not found`: reload your shell with `source ~/.bashrc`. - Tools you set up in `~/.bashrc`, such as nvm or pyenv, are invisible to Hermes: list those files under `terminal.shell_init_files` in `config.yaml`. - Installing for a separate service user: run the installer as that user, add `~/.local/bin` to its PATH, and run `sudo loginctl enable-linger SERVICE_USER`. - Alpine and other musl distros need the system `libstdc++`. More fixes: /troubleshoot/install-or-update-failed. ### Next step Next: follow /learn/first-24-hours-default-setup. To keep Hermes running after you log out, see /learn/run-hermes-agent-24-7. To chat from your phone, read /learn/messaging-gateway-explained. ### Related tools - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Terminal backends: choose where the agent's commands run](https://hermeswatcher.com/tools/terminal-backends.md) - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) ### Sources - [Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation) - [Platform Support](https://hermes-agent.nousresearch.com/docs/getting-started/platform-support) - [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) - [Updating & Uninstalling](https://hermes-agent.nousresearch.com/docs/getting-started/updating) - [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) - [Which File Does What](https://hermes-agent.nousresearch.com/docs/user-guide/which-file-does-what) - [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) - [Hermes Agent README](https://github.com/NousResearch/hermes-agent) ## How to run Hermes Agent in Docker > Hermes Agent has an official Docker image for amd64 and arm64. Run the setup wizard, then start the gateway with your data on a mounted volume. URL: https://hermeswatcher.com/learn/install-hermes-agent-docker Last reviewed: Oct 28, 2026 ### Short answer Yes, Docker is officially supported. The official docs list the Docker container on x86_64 and aarch64 as Tier 1, and publish the image `nousresearch/hermes-agent`. Docker suits servers and anyone who wants Hermes isolated from the rest of the machine. The image has no desktop app. If you want the app on your own computer, use the Windows, Mac or Linux install guides instead. One thing to know: Docker installs do not support `hermes update`. You update by pulling a new image. ### What you need Docker installed on the host. The official docs give these resource figures: - Memory: 1 GB minimum, 2 to 4 GB recommended. - CPU: 1 core minimum, 2 cores recommended. - Disk (data volume): 500 MB minimum, 2 GB or more recommended. The docs say 1 GB is enough if you do not need browser tools. With browser tools active, allocate at least 2 GB. Image tags: `latest` or `stable` for the stable release, `main` for development builds, or `X.Y.Z` to pin a version. ### First run: the setup wizard Create a data folder on the host, then run the wizard. It saves your settings into that folder. sh: ``` mkdir -p ~/.hermes docker run -it --rm \ -v ~/.hermes:/opt/data \ nousresearch/hermes-agent setup ``` The wizard is the same one native installs use. It asks for your model provider and keys. The official docs say Hermes needs a model with at least 64,000 tokens of context. ### Chat or run the gateway For an interactive chat in the terminal: sh: ``` docker run -it --rm \ -v ~/.hermes:/opt/data \ nousresearch/hermes-agent ``` sh (persistent gateway): ``` docker run -d \ --name hermes \ --restart unless-stopped \ -v ~/.hermes:/opt/data \ -p 8642:8642 \ nousresearch/hermes-agent gateway run ``` The second command runs the messaging gateway in the background and restarts it unless you stop it. Port 8642 is the OpenAI-compatible API server and health endpoint. The docs say it is optional if you only use chat apps, so leave out `-p 8642:8642` if you do not need it. The docs also include a Docker Compose example on the same page. ### Where your settings live and how to update Everything lives in the mounted folder: `~/.hermes` on the host, `/opt/data` in the container. That includes `.env`, `config.yaml`, `SOUL.md`, `sessions/`, `memories/`, `skills/` and `logs/`. Back up this folder and you have backed up the agent. To update, pull the new image and recreate the container: sh: ``` docker pull nousresearch/hermes-agent:latest docker rm -f hermes docker run -d \ --name hermes \ --restart unless-stopped \ -v ~/.hermes:/opt/data \ nousresearch/hermes-agent gateway run ``` With Compose, run `docker compose pull` then `docker compose up -d`. See /learn/updating-hermes-safely before big upgrades. ### Common problems - Two gateways on one data folder: never run two gateway containers on the same data directory. - Browser tools crash: add `--shm-size=1g` to the run command. - Permission errors on the data folder: the container runs as UID 10000, which may not match the folder owner. Set `PUID` and `PGID` (or `HERMES_UID` and `HERMES_GID`) to match. - Database errors with Docker Desktop on Mac or Windows: bind mounts there can corrupt SQLite databases. Use a named volume, or set `database.journal_mode: delete`. - Pasted commands fail on a VPS: browser-based consoles mangle characters like `:` and `@`. Connect over SSH instead. - Opening ports: the docs warn that opening any port on an internet-facing machine is a security risk. The dashboard requires an auth provider on any non-local address. ### Not the same as the Docker terminal backend Running Hermes in Docker is different from the Docker terminal backend. With the backend, Hermes runs on your machine and sends its shell commands into a sandbox container (`hermes config set terminal.backend docker`). Compare the options in /learn/choosing-a-terminal-backend. Next: connect a chat app with /learn/messaging-gateway-explained, or keep it running around the clock with /learn/run-hermes-agent-24-7. ### Related tools - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Terminal backends: choose where the agent's commands run](https://hermeswatcher.com/tools/terminal-backends.md) - [API server: use Hermes from any OpenAI-compatible client](https://hermeswatcher.com/tools/api-server.md) ### Sources - [Hermes Docker Setup](https://hermes-agent.nousresearch.com/docs/user-guide/docker) - [Platform Support](https://hermes-agent.nousresearch.com/docs/getting-started/platform-support) - [Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation) - [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) - [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) ## How to run Hermes Agent 24/7 on a VPS or home server > Keep Hermes Agent online around the clock: install the gateway as a service, enable linger or a system service, and lock it down before going public. URL: https://hermeswatcher.com/learn/run-hermes-agent-24-7 Last reviewed: Oct 28, 2026 ### Short answer Yes. The part of Hermes that stays online is the messaging gateway: one background process that connects your chat apps to the agent. To run it 24/7, install it as a service on a machine that stays on. The README says you can run Hermes on a $5 VPS. The docs' Team Telegram tutorial agrees that a $5 a month VPS is plenty for the gateway, because the model calls happen remotely. It also says to use a server, not your laptop, since the bot needs to stay running. - Linux VPS or home server: the most direct route. Install Hermes with the Linux installer, then install the gateway as a service. - Docker: run the gateway container with a restart policy. - Mac or Windows PC: the gateway can start at login, but it only runs while the computer is on and you are logged in. ### What you need - Hermes installed and working in the CLI first. See /learn/install-hermes-agent-linux or /learn/install-hermes-agent-docker. - At least one chat app set up with `hermes gateway setup`. See /learn/messaging-gateway-explained. - For sizing, the only documented figures are Docker's: 1 GB of memory minimum, at least 2 GB with browser tools. - SSH access to the server. The docs warn that browser-based VPS consoles mangle characters like `:` and `@` when you paste commands. ### Linux: install the gateway as a service These commands are from the official Messaging Gateway page: bash: ``` hermes gateway install # Install as user service hermes gateway start # Start the service hermes gateway stop # Stop the service hermes gateway status # Check status journalctl --user -u hermes-gateway -f # View logs ## Enable lingering (keeps running after logout) sudo loginctl enable-linger $USER ## Or install a boot-time system service that still runs as your user sudo hermes gateway install --system sudo hermes gateway start --system sudo hermes gateway status --system journalctl -u hermes-gateway -f ``` Which one? The docs say to use the user service on laptops and dev boxes, and the system service on a VPS or headless host that should come back at boot without relying on linger. There is a trade-off. A system service needs root for every restart, including the automatic restart after `hermes update`. For a headless machine you never log into, the docs say a user service plus `sudo loginctl enable-linger $USER` also starts at boot and lets updates restart the gateway with no root at all. Do not add a custom `ExecStopPost` kill rule to the systemd unit. The docs say it causes an endless restart loop. ### Docker: use a restart policy Run the gateway as the container's main process, with a restart policy. The official command: sh: ``` docker run -d \ --name hermes \ --restart unless-stopped \ -v ~/.hermes:/opt/data \ -p 8642:8642 \ nousresearch/hermes-agent gateway run ``` Inside the image, the gateway is also supervised. If it crashes, it restarts within a couple of seconds without losing the container. Leave out `-p 8642:8642` if you only use chat apps. Never run two gateway containers on the same data folder. ### Mac and Windows PCs - Mac: `hermes gateway install` creates a launchd agent that starts the gateway when you log in. Logs are in `~/.hermes/logs/gateway.log`. - Windows: `hermes gateway install` registers a Scheduled Task called `Hermes_Gateway` that runs at login, with no admin needed. If the gateway is killed from outside, it stays down until you run `hermes gateway start`. - WSL2: the WSL VM shuts down when idle. The docs suggest keeping WSL alive with a Task Scheduler entry, or running `hermes gateway run` inside tmux. They also say WSL's systemd support is unreliable. The official docs do not give power or sleep settings. The gateway only answers while the machine is awake and you are logged in, so a VPS is the simpler choice for true 24/7. ### Updates and security - `hermes update` pauses and restarts running gateways for you. You can also send `/update` from a supported chat app. The docs say the bot goes offline for about 5 to 15 seconds during the restart. - By default the gateway ignores anyone who is not on an allowlist or paired by DM. Keep it that way. - Do not open ports without auth. The docs warn that opening any port on an internet-facing machine is a security risk, and the dashboard requires an auth provider on any non-local address. - Use SSH, not a browser console. OAuth logins that redirect to `127.0.0.1` need an SSH tunnel when Hermes runs on a remote server. Read /learn/security-model-approvals-and-sandboxing and /learn/keeping-costs-under-control before you leave an agent running unattended. ### Next step Next: give your always-on agent a job, such as the daily research briefing workflow. If the bot goes quiet, start with /troubleshoot/gateway-bot-not-responding. ### Related tools - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Telegram: reach Hermes from a private bot conversation](https://hermeswatcher.com/tools/telegram.md) - [Scheduled tasks: automate a proven run](https://hermeswatcher.com/tools/scheduling.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) ### Sources - [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) - [Hermes Docker Setup](https://hermes-agent.nousresearch.com/docs/user-guide/docker) - [Updating & Uninstalling](https://hermes-agent.nousresearch.com/docs/getting-started/updating) - [Tutorial: Team Telegram Assistant](https://hermes-agent.nousresearch.com/docs/guides/team-telegram-assistant) - [Windows (Native) Guide](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native) - [Windows (WSL2) Guide](https://hermes-agent.nousresearch.com/docs/user-guide/windows-wsl-quickstart) - [OAuth over SSH / Remote Hosts](https://hermes-agent.nousresearch.com/docs/guides/oauth-over-ssh) - [Hermes Agent README](https://github.com/NousResearch/hermes-agent) ## Hermes Agent memory vs context files vs project notes > Choose where a fact belongs so a future session can recover it without carrying your entire project in every prompt. URL: https://hermeswatcher.com/learn/memory-context-and-project-records Last reviewed: Oct 19, 2026 ### Three places to keep knowledge Hermes has persistent memory for compact facts and preferences, project context files for instructions, and session search for retrieving past conversations. A durable project folder can hold the detailed evidence those small orientation layers point toward. These serve different purposes; placing a document in one does not automatically make it available everywhere. Our recommended arrangement is to keep the project location and a few lasting conventions in memory, operating instructions in the project context, and decisions, sources and outputs in ordinary files. For a research project, memory might identify the project folder while a decision record explains why a source was accepted. That keeps the evidence inspectable when a summary becomes stale. ### Design a recovery check Choose one fact that matters next week: the accepted output location, the owner of a decision, or the latest approved brief. Ask a fresh session to find it and cite its record. A successful answer should explain where the fact came from and distinguish accepted decisions from proposals. If it cannot, improve the record or its discoverability before adding more material. Keep dates and supersession notes with changing decisions. A saved statement that a service was healthy yesterday should lead to a fresh check today; it should not become permanent proof of health. Avoid storing raw logs or credentials in an orientation note. ### Scope and limits The current documentation describes profile-specific memory and a snapshot loaded at session start. Verify the active profile when comparing sessions. This guide explains an information-management pattern; it does not establish that your installation has written, loaded or recovered a particular memory successfully. ### Related tools - [Carry project knowledge into the next session](https://hermeswatcher.com/workflows/project-knowledge.md) - [Persistent memory: retain compact working knowledge](https://hermeswatcher.com/tools/memory.md) - [Context files: give a project durable instructions](https://hermeswatcher.com/tools/context-files.md) ### Sources - [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) - [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) ## Hermes Agent skills vs plugins vs MCP: which to use > Match the extension to the missing capability instead of installing three different things to solve one problem. URL: https://hermeswatcher.com/learn/skills-plugins-and-mcp Last reviewed: Oct 19, 2026 ### Identify what is actually missing A skill supplies reusable procedural knowledge. A plugin extends Hermes through code, including tools or hooks. An MCP connection makes a server's capabilities available through a standard interface. A workflow can use all three, but they are not interchangeable: instructions describing a mailbox do not grant mailbox access. Start with the desired operation. If Hermes already has the necessary tools but repeats a complicated procedure badly, a skill may be the useful addition. If a service exposes an appropriate MCP server, evaluate that connection. A custom plugin becomes relevant when you need behavior or an integration that existing capabilities cannot supply. ### Evaluate the complete dependency chain For each candidate, write down its source, installation scope, required executable or service, credentials, permitted actions and update owner. Then choose a small read-only operation that demonstrates the connection. For a document service, listing a known folder and opening one accessible document is more informative than a successful installation notice. Keep the procedure portable by explaining inputs and expected outputs separately from account-specific settings. Do not put tokens in a shared skill. When documenting a workflow, name the underlying capability as well as the extension: readers need to know whether a different supported connection can accomplish the same task. ### Scope and limits These distinctions follow the current official extension guides. Availability still depends on the installed Hermes version, active profile and extension configuration. A catalog listing is a discovery lead rather than proof of compatibility, access or quality. This page does not endorse a third-party server or imply that any extension has been executed by this library. ### Related tools - [Turn a crowded inbox into a review queue](https://hermeswatcher.com/workflows/inbox-triage.md) - [Build a useful GitHub issue review](https://hermeswatcher.com/workflows/github-issue-review.md) - [Skills: reusable procedures for repeated work](https://hermeswatcher.com/tools/skills.md) - [Plugins: add tools and lifecycle behavior](https://hermeswatcher.com/tools/plugins.md) - [MCP: connect external tool servers](https://hermeswatcher.com/tools/mcp.md) ### Sources - [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) - [Plugins](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins) - [MCP Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) ## How to choose a model for Hermes Agent > Separate model selection, provider access and tool configuration, then compare them using a representative task. URL: https://hermeswatcher.com/learn/models-and-effective-configuration Last reviewed: Oct 19, 2026 ### A model name is only one setting The selected model reasons about the task; its provider supplies access; enabled tools perform operations outside the conversation. An otherwise capable model cannot fetch an inbox merely because its provider authentication succeeds. Treat these as separate parts of the configuration and check which part a failure belongs to. The official configuration guide documents resolved-value inspection through hermes config get and validation through hermes config check. Use those diagnostics before changing several settings at once. An invocation override, another profile or a running service with old settings can make a saved file an incomplete description of what actually executed. ### Compare completed work Use one bounded task with a known answer or inspectable artifact. A useful model trial might retrieve five issues, identify duplicates and cite each conclusion. Record whether it used the required tools, handled missing data, followed the output format and finished without repair. Measure total effort across retries, not just the first response time. Keep the source window and permissions stable between trials. For research, inspect whether a model separates collection dates from publication dates. For automation, test a no-change case and an unavailable-source case. Choose the least expensive configuration that reliably meets the actual requirements; there is no universal best model for every workflow. ### Scope and limits This is a comparison method, not a current model ranking or a price estimate. Provider offerings, quotas and supported identifiers change. Consult the relevant provider's current terms before selecting a paid option. Redact credentials when retaining diagnostic output, and record the effective provider and model with the test result so a future comparison remains meaningful. ### Related tools - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Build a useful GitHub issue review](https://hermeswatcher.com/workflows/github-issue-review.md) - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) ### Sources - [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) - [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) ## How to schedule recurring tasks in Hermes Agent > Define success as an attempt, a usable artifact and a confirmed destination before trusting an unattended schedule. URL: https://hermeswatcher.com/learn/scheduling-with-evidence Last reviewed: Oct 19, 2026 ### Schedule an outcome Hermes documents scheduled jobs, gateway-driven execution, run history and delivery behavior. Those mechanisms tell you how work is launched and recorded. Our recommended operating contract adds a separate definition of what the reader should actually receive: a dated file, a source-linked summary or a verified change notice. Before enabling recurrence, complete one manual run with the intended profile and destination. Define what counts as fresh, how much missing source coverage is acceptable, and what to do when nothing changed. A quiet no-change run and an inaccessible-source run should leave distinguishable records, even if neither produces a notification. ### Keep a small run receipt Save the job identity, scheduled time with timezone, start and finish times, input window, output location and delivery result. Use a stable task identifier when maintaining a job so a repair does not create duplicate schedules. Keep the most recent valid artifact available while a failed attempt is investigated. Test failure deliberately with a harmless unavailable input before relying on an important routine. The result should name the unavailable source and preserve previous output rather than present yesterday's material as new. Bound retries and specify when a failure becomes actionable for a person. Monitoring should make exceptions visible without generating routine noise. ### Scope and limits Current scheduler diagnostics include hermes cron status and hermes cron list. Their exact output depends on the installed release and scheduler arrangement. A healthy timer is useful evidence of scheduling infrastructure, not proof of an accurate report or a delivered message. This library has not verified an unattended run on your host merely by describing the documented mechanism. ### Related tools - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Scheduled tasks: automate a proven run](https://hermeswatcher.com/tools/scheduling.md) ### Sources - [Scheduled Tasks](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) ## Hermes Agent permissions for real workflows > Define access by account, operation and destination so useful autonomy does not depend on ambiguous instructions. URL: https://hermeswatcher.com/learn/permissions-for-real-workflows Last reviewed: Oct 19, 2026 ### Describe allowed actions concretely Hermes documents several protection layers, including user authorization, command approvals, file-write restrictions and container isolation. These controls answer different questions. An authorized chat participant may still encounter a blocked command; an isolated terminal does not decide whether a message should be sent to a customer. Write a short action contract for the workflow. An inbox review might read one account, inspect a bounded date range and prepare a local queue. Drafting replies, changing labels and sending messages should be described separately. This makes the task easier to automate because agents can distinguish routine authorized work from a decision that belongs to the owner. ### Use evidence to reduce interruptions Choose an output location and a reviewable intermediate result. If the next step changes an external system, prepare the exact proposed change first. A person can then approve a concrete result rather than interpret a vague request to proceed. For a recurring read-only check, define the conditions that justify a notification and let the ordinary pass remain quiet. Retain the account identity and action result with the task record, without saving secrets. When a workflow fails at a permission boundary, record the denied operation and required access instead of broadening all permissions. Restore only what that operation needs, then repeat a bounded check. ### Scope and limits These are workflow-design recommendations grounded in documented protection layers. They do not guarantee that a custom tool enforces every instruction. Unattended approval behavior varies by execution surface and configuration. Verify the relevant setting on the actual installation before relying on a headless task, and treat a refusal as evidence to diagnose rather than a reason to disable protections globally. ### Related tools - [Turn a crowded inbox into a review queue](https://hermeswatcher.com/workflows/inbox-triage.md) - [Build a useful GitHub issue review](https://hermeswatcher.com/workflows/github-issue-review.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Telegram: reach Hermes from a private bot conversation](https://hermeswatcher.com/tools/telegram.md) - [Discord: keep agent conversation scoped to the right people](https://hermeswatcher.com/tools/discord.md) ### Sources - [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ## Where Hermes Agent runs: host vs work environment > Decide where the agent, its tools and its lasting files live before moving a workflow to a server. URL: https://hermeswatcher.com/learn/where-hermes-runs Last reviewed: Oct 19, 2026 ### Draw the boundaries first Hermes supports several host platforms and terminal backends. The machine running the agent and the environment executing its terminal commands can be different. A remote execution backend does not by itself move every configuration file, memory entry or scheduled service off your laptop. Sketch four locations: the Hermes process, the command environment, the source data and the final artifact. Add the network paths and accounts connecting them. This exposes assumptions such as a server task needing a file that exists only in your Downloads folder. It also makes storage planning much more realistic than estimating the size of application code alone. ### Choose using operating needs A personal machine is convenient for development and access to local files. An always-available host can suit recurring work, provided its processes, credentials and persistent storage are managed. Container or remote execution can provide a separate command environment, but requires explicit decisions about mounts, networking and retained data. Before migration, run a small task that writes a disposable artifact, reconnect and read it back. Check which settings and secrets the service actually receives. Define backup scope, retention and recovery before growing a large collection of logs or media. Test one restart and confirm the expected work can resume without relying on an interactive terminal left open. ### Scope and limits The current platform matrix includes native Windows as well as Linux, WSL2 and macOS, with distribution-specific restrictions. Consult that matrix for the chosen architecture and installation method. This guide does not estimate hosting costs or certify a deployment. A supported platform still needs task-specific validation, and a cloud workspace may have separate persistence and billing rules. ### Related tools - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Carry project knowledge into the next session](https://hermeswatcher.com/workflows/project-knowledge.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) ### Sources - [Platform Support](https://hermes-agent.nousresearch.com/docs/getting-started/platform-support) - [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) ## Turn a Hermes Agent use case into a repeatable workflow > Use community examples as discovery material, then expose the dependencies and evidence needed to reproduce the result. URL: https://hermeswatcher.com/learn/from-story-to-workflow Last reviewed: Oct 19, 2026 ### Start with the reported outcome The official user-story collection links to many accounts of Hermes in practical use. A reported outcome is a useful lead, but usually leaves out some implementation detail. Preserve the original source and its date, describe what the author reports, and keep that separate from any implementation you propose. Extract the goal, input, transformation and output. For a ticket-summary example, identify which tickets were read, how they were grouped and where the summary appeared. Then list what is missing: permissions, integration, selection rules, model, schedule or a way to verify completeness. Unknowns are useful research tasks rather than details to fill with plausible guesses. ### Create the smallest reproducible version Choose a sample with inspectable input and a harmless destination. Write a starter prompt in your own words, state prerequisites and define the result check. For a research brief, inspect source links and coverage before scheduling anything. A complete recipe explains recovery when an input is missing, not just the happy path. After a successful trial, record the environment and observed output. Save the repeatable procedure as a skill when that is useful; the official skills system supports reusable procedural material. Keep account credentials and changing datasets outside the procedure. If another reader cannot reproduce the result, improve the missing step instead of treating the source's success as universal proof. ### Scope and limits This is our editorial method for developing examples, informed by the official collections and skills guidance. A community report remains community-reported until a separate reproduction provides evidence. Documentation support verifies the described mechanism, not the story's business results, cost savings or suitability for every account. ### Related tools - [Collect content ideas without losing the evidence](https://hermeswatcher.com/workflows/content-research-queue.md) - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Skills: reusable procedures for repeated work](https://hermeswatcher.com/tools/skills.md) ### Sources - [User Stories & Use Cases](https://hermes-agent.nousresearch.com/docs/user-stories) - [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) ## Hermes Agent for research that keeps its sources > Separate discovery, factual extraction and editorial judgment so a useful summary remains traceable. URL: https://hermeswatcher.com/learn/research-that-keeps-its-sources Last reviewed: Oct 19, 2026 ### Give every finding a source record Hermes provides web retrieval and other tools that can support research. Tool availability is a starting point; the research procedure must still decide what qualifies as evidence. Our recommended queue records the original URL, author or publisher, publication date when available, collection date and the exact claim being investigated. Treat a roundup as a discovery route. Follow a lead to the original announcement, repository, demonstration or documentation whenever possible. If the original cannot be read, preserve that limitation rather than presenting the secondary account as an independently checked result. Several pages repeating one announcement are several links, not several independent confirmations. ### Separate facts from useful interpretation Use distinct fields for the reported event, the supporting evidence, your reader's question and the proposed angle. This lets an agent update a changed fact without losing the editorial reason the item was collected. Group duplicates by underlying event or workflow, while retaining meaningful disagreements between sources. For each proposed guide, ask what the reader needs beyond the original post: prerequisites, a worked example, a comparison or a failure path. Add that contribution in original prose. A short unsupported claim may remain a research lead indefinitely; it does not need to become a polished tutorial merely because the queue needs more entries. ### Scope and limits This page proposes a source-management method; it does not claim that Hermes automatically implements every field or review step. Retrieval may be partial because of authentication, pagination or extraction failures. Date the collection, disclose gaps and use a bounded source set so readers can understand what the queue covers and what it cannot establish. ### Related tools - [Collect content ideas without losing the evidence](https://hermeswatcher.com/workflows/content-research-queue.md) - [Build a useful GitHub issue review](https://hermeswatcher.com/workflows/github-issue-review.md) - [Browser tools: interact with pages when retrieval is insufficient](https://hermeswatcher.com/tools/browser-tools.md) ### Sources - [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) - [User Stories & Use Cases](https://hermes-agent.nousresearch.com/docs/user-stories) ## How Hermes Agent memory works (and where it stops) > A plain-English tour of Hermes's two built-in memory files, the frozen snapshot they load into, their hard size limits, and when an external memory provider or session search is the better tool. URL: https://hermeswatcher.com/learn/how-hermes-memory-works Last reviewed: Oct 20, 2026 ### Two small files, not a database Hermes's built-in memory is deliberately small. It is two markdown files in ~/.hermes/memories/: MEMORY.md holds the agent's own notes (facts about your environment, conventions, lessons it learned the hard way) and USER.md holds what it knows about you (preferences, communication style, expectations). If you use a named profile, the files live under that profile's own memories folder instead, so each profile remembers separately. The limits are strict and worth knowing by heart: MEMORY.md is capped at 2,200 characters (roughly 800 tokens) and USER.md at 1,375 characters (roughly 500 tokens). That is a few dozen short facts, not a notebook. The design choice is intentional: because both files are injected into every session, keeping them small keeps every message cheaper. ### The frozen snapshot: why a new fact doesn't show up straight away At the start of a session Hermes reads both files and renders them into the system prompt as a frozen snapshot. That snapshot does not change for the rest of the session, even if the agent writes something new. The write is saved to disk immediately, but you will only see it reflected in the prompt from the next session onward. This trips people up: you say "remember that I prefer metric units", the agent confirms, and nothing seems different. It is working as designed. The reason is prompt caching: a stable system prompt lets your provider reuse the cached prefix, which is faster and cheaper. If you need the new fact active now, start a fresh session with /new. ### How the agent edits memory The agent manages memory with a single memory tool. Every call names a target, either "memory" or "user", and uses one of three actions. There is no read action, because the contents are already in the prompt. - add: appends a new entry. Exact duplicates are rejected with a 'no duplicate added' note. - patch: replaces one span inside an existing entry and keeps the rest. The matching text has to identify exactly one entry. - remove: deletes the entry that matches a substring. Again, the substring must match only one entry. - The older replace action now returns an error pointing to patch. ### What happens when memory is full Memory does not compact itself. When a write would exceed the limit, the tool returns an error listing the current entries and usage, and the agent has to free space and add the new entry in one batch. The docs suggest consolidating once usage passes about 80%. In practice the easiest fix is to ask Hermes directly: "consolidate your memory and drop anything outdated." Every entry is also scanned before it is saved. Content that looks like prompt injection, credential exfiltration, SSH backdoors or hidden Unicode is blocked. If you want to see every write before it lands, set memory.write_approval: true in config.yaml and review staged writes with /memory pending, /memory approve and /memory reject. ### What belongs in memory and what doesn't Good memory entries are short, durable and genuinely useful in most future sessions. The docs list what to keep out: - Trivial or vague notes, and facts that are easy to look up again. - Raw dumps such as large code blocks, logs or data tables. - Session-specific details like one-off paths or debugging context. - Anything already covered by context files such as AGENTS.md or SOUL.md. - Credentials: those belong in ~/.hermes/.env, not memory. - Step-by-step procedures you repeat: write a skill instead. The docs summarise it as memory for facts, skills for procedures. ### Beyond the two files: session search and external providers Two other mechanisms cover what the small files cannot. First, every CLI and messaging conversation is stored in a SQLite database (~/.hermes/state.db) with full-text search, and the agent can query it with the session_search tool. That search is unlimited, runs only when needed and makes no extra LLM calls, so it is the right place for "what did we decide last month?" rather than stuffing memory. Second, you can add one external memory provider at a time. The docs list Honcho, OpenViking, Mem0, Hindsight, Holographic (local SQLite, no external service), RetainDB, ByteRover, Supermemory and Memori. Run hermes memory setup to pick and configure one, hermes memory status to see what is active and hermes memory off to disable it. A provider is additive: MEMORY.md and USER.md keep working, while the provider prefetches relevant memories each turn, syncs turns after responses and adds its own search tools. Content sent to a provider is scrubbed for recognisable secrets first, but credentials without a recognisable shape are not caught, so don't rely on scrubbing alone. ### Related guides - [Hermes Agent memory vs context files vs project notes](https://hermeswatcher.com/learn/memory-context-and-project-records.md) - [Hermes Agent memory not carrying over between sessions](https://hermeswatcher.com/troubleshoot/memory-did-not-persist.md) - [Hermes Agent sessions: search and resume past work](https://hermeswatcher.com/learn/sessions-and-session-search.md) - [How to write your first Hermes Agent skill](https://hermeswatcher.com/learn/writing-your-first-skill.md) ### Related tools - [Carry project knowledge into the next session](https://hermeswatcher.com/workflows/project-knowledge.md) - [Persistent memory: retain compact working knowledge](https://hermeswatcher.com/tools/memory.md) - [Context files: give a project durable instructions](https://hermeswatcher.com/tools/context-files.md) ### Sources - [Persistent Memory (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) - [Memory Providers (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers) - [Tips and Best Practices (official guide)](https://hermes-agent.nousresearch.com/docs/guides/tips) ## Hermes Agent sessions: search and resume past work > How Hermes stores every conversation, how to name, resume, export and prune sessions, and how the agent searches its own history. URL: https://hermeswatcher.com/learn/sessions-and-session-search Last reviewed: Oct 20, 2026 ### Every conversation is a session Whether you chat in the terminal, through Telegram, from a cron job or via the API server, Hermes records the conversation as a session in a SQLite database at ~/.hermes/state.db. Each session keeps its ID, the platform it came from, the model used, a snapshot of the system prompt, the full message history, token counts, timestamps and a parent session ID. That last field matters later, because it is how Hermes links a conversation to its continuation after compression. The source tag tells you where a session came from: cli, telegram, discord, slack, cron, api-server and many more. A few internal kinds (oneshot, kanban and tool) are hidden from the TUI, desktop and dashboard pickers so they don't clutter your list. ### Naming and resuming Sessions are easier to find again if you name them. Use /title inside a chat, or hermes sessions rename from the shell. When you exit, Hermes prints a resume command containing the session ID. - hermes -c (or hermes --continue): pick up your most recent CLI session with its full history. - hermes --resume <id|title|latest> (short form -r): resume a specific session by ID or title. - --in <dir>: limit the 'latest session' lookup to one workspace directory. - /resume and /sessions inside a chat let you switch without leaving. - /new or /reset: start fresh. The docs recommend doing this at natural task or topic boundaries. ### Housekeeping from the command line The hermes sessions command covers the routine maintenance most people eventually need: - hermes sessions list, with --source <platform>, --limit N or --workspace <needle> to narrow it. - hermes sessions export <file> writes jsonl by default; --format also accepts md, html and others, and --redact strips sensitive content. - hermes sessions delete <id> removes one session. - hermes sessions prune removes ended sessions older than 90 days by default; add --dry-run first to see what would go. - hermes sessions archive hides matching sessions without deleting them, and hermes sessions pin keeps important ones safe from auto-archiving. - hermes sessions stats and hermes sessions optimize report on and tidy the database. ### How the agent searches its own history The session_search tool lets Hermes look things up across all stored conversations. It returns the raw stored messages rather than an LLM-written summary, and once it finds a relevant session it can scroll forwards and backwards around a specific message. Queries use standard SQLite full-text syntax: keywords are combined with AND by default, and quoted phrases, OR, NOT and prefix wildcards (deploy*) all work. Because search runs only on demand and uses no extra model calls, it complements memory nicely. Memory is always in context but tiny; session search is unlimited but has to be asked for. A useful habit is to prompt explicitly: "search our past sessions for the decision about the staging database." ### Compression creates linked sessions When a conversation gets long, Hermes compresses it (automatically, or when you run /compress). Compression starts a continuation session that points back to the original through its parent ID. Titled sessions get numbered continuations such as #2 and #3, and resuming by name picks the newest one in that chain. Pruning keeps older segments as long as a later segment survives, so you don't lose the beginning of a long-running thread. ### Messaging sessions don't time out On Telegram, Discord and other gateway platforms, conversations no longer reset after inactivity or at a daily boundary. They continue until someone sends /new or /reset, with compression handling length. If you relied on older session_reset settings, note that they are now ignored; the docs point to an optional hermes-session-reset-policy plugin if you want timed resets back. In group chats, each user gets their own session by default (group_sessions_per_user: true). ### Related guides - [How Hermes Agent memory works (and where it stops)](https://hermeswatcher.com/learn/how-hermes-memory-works.md) - [Hermes Agent forgets things mid-conversation](https://hermeswatcher.com/troubleshoot/forgets-mid-conversation.md) - [Hermes Agent memory not carrying over between sessions](https://hermeswatcher.com/troubleshoot/memory-did-not-persist.md) ### Related tools - [Carry project knowledge into the next session](https://hermeswatcher.com/workflows/project-knowledge.md) - [Persistent memory: retain compact working knowledge](https://hermeswatcher.com/tools/memory.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) ### Sources - [Sessions (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/sessions) - [CLI Interface (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/cli) - [Persistent Memory (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) - [Tips and Best Practices (official guide)](https://hermes-agent.nousresearch.com/docs/guides/tips) ## How to write your first Hermes Agent skill > A step-by-step walkthrough of creating a SKILL.md, where to put it, how Hermes discovers and loads it, and how to keep agent-written skills under review. URL: https://hermeswatcher.com/learn/writing-your-first-skill Last reviewed: Oct 20, 2026 ### What a skill is for A skill is a markdown document that teaches Hermes how to do a particular job: your release checklist, the way you like research briefs formatted, the steps for triaging a support inbox. The docs sum up the split neatly: memory stores facts, skills store procedures. If you notice yourself explaining the same multi-step process for the third time, that is a skill waiting to be written. Skills follow the open agentskills.io format and use progressive disclosure, which keeps them cheap. At session start Hermes only sees a compact index of skill names and descriptions (around 3k tokens for the whole list). It loads a skill's full text only when it decides the skill is relevant, and loads supporting files only if the skill points to them. ### Step 1: create the folder and file Personal skills live in ~/.hermes/skills/, one folder per skill, optionally grouped by category. The official guide's example path is ~/.hermes/skills/my-category/my-skill/SKILL.md. The only required file is SKILL.md; you can add references/, templates/, scripts/, examples/ or assets/ folders next to it for supporting material. The file starts with YAML frontmatter. The documented example looks like this: name: my-skill, description: Brief description of what this skill does, version: 1.0.0, and a metadata.hermes block with tags and a category. Optional fields include platforms (limit the skill to macos, linux or windows) and required_environment_variables for secrets the skill needs. ### Step 2: write a description that earns the load The description is the most important line you will write, because it is nearly all the agent sees before deciding whether to open the skill. Say plainly what the skill does and when it applies, using the words you would naturally use when asking for that task. "Formats weekly research briefs with sources, confidence notes and a three-bullet summary" will be picked up far more reliably than "Brief helper". For the body, the official template suggests four sections: When to Use, Procedure, Pitfalls and Verification. This is a recommendation, not a required schema, but it is a good shape. Keep the main file focused and move long reference material into references/, then point to it from the procedure so Hermes fetches it only when needed. ### Step 3: use it Every installed skill automatically becomes a slash command. Typing /my-skill followed by a task runs it with that skill loaded; typing the name alone loads the skill without a task. You can also just ask in plain language ("use my release-checklist skill"), which makes the agent call skill_view. You can chain up to five skill commands at the start of one message. One timing detail: skills added during a session are announced on your next message, but the system prompt itself stays fixed to protect prompt caching. Hub-installed skills take effect in new sessions; /reset, or --now on install, applies them immediately at the cost of more tokens on the next turn. ### Letting Hermes write skills for you Hermes can create and update skills itself through the skill_manage tool, which supports create, patch, delete, write_file and remove_file. After a complex task it may offer to save the approach as a skill, and there is also a /learn command that drafts a skill from a directory, URL, workflow or document. An advisory linter warns about oversized bodies or too many reference files but never blocks a write. If you would rather approve those changes, set skills.write_approval: true. Writes are then staged under ~/.hermes/pending/skills/ and you review them with /skills pending, /skills diff <id>, /skills approve and /skills reject. ### Sharing and installing The Skills Hub lets you browse and install community skills with hermes skills browse, search, inspect and install (for example hermes skills install official/security/1password), or install straight from a URL. Every hub install passes a built-in security scanner, and a skill rated dangerous cannot be forced through. Project-local skills in a repo's .hermes/skills/ or .agents/skills/ folders load only after you run hermes skills trust for that repo. ### Related guides - [Hermes Agent skills vs plugins vs MCP: which to use](https://hermeswatcher.com/learn/skills-plugins-and-mcp.md) - [Hermes Agent not using your skill](https://hermeswatcher.com/troubleshoot/skill-not-being-used.md) - [How Hermes Agent memory works (and where it stops)](https://hermeswatcher.com/learn/how-hermes-memory-works.md) ### Related tools - [Collect content ideas without losing the evidence](https://hermeswatcher.com/workflows/content-research-queue.md) - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Skills: reusable procedures for repeated work](https://hermeswatcher.com/tools/skills.md) - [Plugins: add tools and lifecycle behavior](https://hermeswatcher.com/tools/plugins.md) ### Sources - [Skills System (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) - [Working with Skills (official guide)](https://hermes-agent.nousresearch.com/docs/guides/work-with-skills) - [Tips and Best Practices (official guide)](https://hermes-agent.nousresearch.com/docs/guides/tips) ## Hermes Agent messaging gateway explained > What the Hermes gateway process does, how to set it up and keep it running, who is allowed to talk to your bot, and how chat sessions behave. URL: https://hermeswatcher.com/learn/messaging-gateway-explained Last reviewed: Oct 29, 2026 ### One background process for messaging and automation The gateway is a long-running Hermes process that connects your agent to chat apps and other inbound routes. It handles incoming messages, keeps conversation sessions, runs scheduled jobs and delivers replies. Media support depends on the adapter and speech configuration. If you only use Hermes interactively in the terminal, you do not need the gateway. Agent-driven scheduled jobs need a running gateway even when output stays local. Script-only (`no_agent`) jobs run by `hermes cron tick` are the documented exception. Compare the chat apps and other documented routes at [messaging platforms](https://hermeswatcher.com/messaging.md). They have different media support, account requirements and access controls. - Use the hub's grouped directory for personal, team, iMessage, self-hosted and regional apps, notifications, browser clients and Hermes's own apps. - The [WhatsApp Business Cloud API guide](https://hermeswatcher.com/learn/hermes-agent-whatsapp-business-cloud-api-setup.md) explains its public callback, direct-chat support and 24-hour reply window. ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. Start in the foreground and send one harmless message from an allowed account before installing a service. Keep credentials in the active profile's .env and out of Git, screenshots and chat transcripts. A saved token does not prove that incoming messages or replies reach the right conversation. A service can keep running after a terminal closes. See [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md) for hosting choices. - `hermes gateway setup`: an interactive wizard for configuring platforms and their tokens. - `hermes gateway`: run in the foreground, useful for a first test where you can watch the output. - `hermes gateway install`: install it as a user service (systemd on Linux, launchd on macOS, a Scheduled Task called Hermes_Gateway on Windows). `sudo hermes gateway install --system` creates a boot-time service on Linux. - `hermes gateway start`, `hermes gateway stop`, `hermes gateway status`: manage the installed service. - `hermes gateway restart`: prefer this over a raw systemctl restart, because it lets replies in progress finish first. ### Who is allowed to talk to your bot Human messages need an explicit execution grant. Supported grants include platform allow-all, operator-approved pairing, user/group/chat allowlists, Discord roles and supported local policy grants. An allowlist lists who may use the agent. A terminal-capable bot exposes the host's tools, so keep allow-all disabled on a private bot. `GATEWAY_ALLOW_ALL_USERS` is a fallback only when no relevant allowlists are set, rather than an unconditional final override. Authenticated webhooks, service events and Relay ingress use separate trust boundaries. Unknown chat DMs can use operator-approved pairing. When a code is issued, approve it on the host with `hermes pairing approve <platform> <code>`. Codes expire after one hour, pending requests are capped at three per platform, and five failed approval attempts cause a one-hour lockout. Explicit allowlists and restrictive policies can suppress new prompts. Email ignores unknown senders by default; pairing is opt-in and still requires an authenticated From header. `hermes pairing list` shows pairing state. To remove access, revoke the pairing with `hermes pairing revoke <platform> <user-id>` and remove other grants such as an allowlist entry. You can also split admins from regular users so that only admins run sensitive slash commands, using allow_admin_from and user_allowed_commands. ### How conversations behave Chat sessions persist until someone sends `/new` or `/reset`; they no longer reset on inactivity or at a fixed time, and compression keeps long threads manageable. In groups, each user gets a separate session by default. If the gateway crashes after producing a reply, its delivery ledger in `state.db` supports up to three resend attempts within 24 hours. This covers outgoing replies only. Incoming messages are separate; check your platform's documented backlog behavior. Inspect the destination and ledger when delivery is uncertain; recovery does not establish that a recipient received a reply. If you send a message while Hermes is busy, the default is to redirect the current turn. display.busy_input_mode can switch that to queue (run it next) or steer (inject it after the next tool call). For long jobs, /bg <prompt> runs the task in a separate session and posts the result back to the same chat when it finishes, so your main conversation stays free. One gateway can serve several profiles in one host process when its safety checks permit it. Use `hermes -p <name> gateway setup` for profile-scoped credentials, then inspect `hermes gateway status` and the served profile set. Starting a named profile can attach to the existing host instead of creating another process. Read the multi-profile gateway docs before installing another service; older separate-process recipes are not the current default. ### Useful in-chat commands - `/status` shows session info; `/whoami` shows your slash-command access tier (admin, user or unrestricted) in this chat. - /model: switch model; choices survive restarts, --global writes the change to config and --once applies it to a single turn. - /stop, /retry and /undo: cancel, re-run or roll back the last turn. - /approve and /deny: answer approval prompts from your phone. - `/sethome` chooses the home destination on supported chats. Chat-created jobs default to `deliver=origin`; CLI-created jobs default to local output. A bare platform target uses its home channel, while an explicit chat/topic target selects that destination. See [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md). - /platform list|pause|resume: manage individual platform adapters. ### Where to look when something is off Gateway logs are in the active profile's `~/.hermes/logs/gateway.log`; Linux users can also follow `journalctl --user -u hermes-gateway -f`. A stalled event loop can exit with code 75 for a supervisor to recover. On Windows, Task Scheduler watches a short-lived launcher, not the long-running gateway, so an externally killed or crashed gateway may stay down until `hermes gateway start`. Check actual runtime and platform state. If a platform keeps failing, Hermes pauses it (a circuit breaker). Investigate the failures, then `/platform resume <name>`. ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes messaging gateway docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) - [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md) - [Hermes Agent profiles: separate agents for separate jobs](https://hermeswatcher.com/learn/profiles-separate-agents.md) - [Hermes Agent security: approvals, allowlists, sandboxing](https://hermeswatcher.com/learn/security-model-approvals-and-sandboxing.md) - [How to set up Hermes Agent on Telegram](https://hermeswatcher.com/learn/hermes-agent-telegram-setup.md) - [How to set up Hermes Agent on Discord](https://hermeswatcher.com/learn/hermes-agent-discord-setup.md) - [How to set up Hermes Agent on WhatsApp with the Baileys bridge](https://hermeswatcher.com/learn/hermes-agent-whatsapp-setup.md) - [How to set up Hermes Agent on WhatsApp with the Business Cloud API](https://hermeswatcher.com/learn/hermes-agent-whatsapp-business-cloud-api-setup.md) - [How to set up Hermes Agent with Open WebUI and the API server](https://hermeswatcher.com/learn/hermes-agent-open-webui-setup.md) ### Related tools - [Turn a crowded inbox into a review queue](https://hermeswatcher.com/workflows/inbox-triage.md) - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Telegram: reach Hermes from a private bot conversation](https://hermeswatcher.com/tools/telegram.md) - [Discord: keep agent conversation scoped to the right people](https://hermeswatcher.com/tools/discord.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) ### Sources - [Messaging Gateway (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) - [Security (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/security) - [Telegram setup (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram) - [FAQ and Troubleshooting (official docs)](https://hermes-agent.nousresearch.com/docs/reference/faq) - [Gateway authorization and pairing policy (pinned source)](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L653-L773) - [Scheduled delivery defaults](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) - [Multi-profile gateway operation](https://hermes-agent.nousresearch.com/docs/user-guide/multi-profile-gateways) - [Email sender authentication](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/email) - [Open WebUI and API runtime](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/open-webui) - [WhatsApp Business Cloud API](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp-cloud) - [Home Assistant catalog integration](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/homeassistant) - [Experimental Hermes Relay](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/relay) ## Hermes Agent terminal backends: local, Docker, SSH, cloud > What each of Hermes's seven terminal backends does, what it isolates, what persists between sessions, and how to pick one for your situation. URL: https://hermeswatcher.com/learn/choosing-a-terminal-backend Last reviewed: Oct 20, 2026 ### What a terminal backend decides When Hermes runs a shell command, the terminal backend decides where that command actually executes. The agent itself (its reasoning, memory and config) stays wherever you installed Hermes; only the commands move. You choose with terminal.backend in ~/.hermes/config.yaml, and the documented options are local, docker, ssh, modal, daytona, vercel_sandbox and singularity. The default is local, and commands time out after terminal.timeout seconds (180 by default). This choice matters more than it looks, because it changes both your safety boundary and how approval prompts behave. ### The options at a glance - local: commands run directly on your machine as your user. No isolation, but full access to your real files and tools. Dangerous-command approval checks are active. - docker: commands run inside a long-lived container (by default one container shared across sessions). The container drops Linux capabilities, sets no-new-privileges and limits processes. Approval checks are skipped because the container is treated as the boundary. - ssh: commands run on a remote machine. Connection details come from environment variables (TERMINAL_SSH_HOST and TERMINAL_SSH_USER are required; TERMINAL_SSH_PORT and TERMINAL_SSH_KEY are optional). Approval checks stay on. - modal and daytona: hosted cloud sandboxes, needing MODAL_TOKEN_ID/MODAL_TOKEN_SECRET or DAYTONA_API_KEY respectively. - vercel_sandbox: Vercel's sandbox, needing VERCEL_TOKEN, VERCEL_PROJECT_ID and VERCEL_TEAM_ID. - singularity: Apptainer/Singularity containers, common on shared research clusters; requires apptainer or singularity on your PATH. ### What persists and what doesn't For container and cloud backends, persistence is about files, not running processes. Docker reuses one container by default (container_persistent: true). Modal snapshots and restores the filesystem; Daytona stops and resumes sandboxes rather than deleting them. The docs are explicit that persistence "does not promise that the same live sandbox, PID space, or background processes will still be running later." If your workflow depends on a long-running server inside the sandbox, plan to restart it. Checkpoints, Hermes's optional pre-edit snapshots, are not available on container backends at all, so /rollback cannot help you there. ### How to choose A simple rule of thumb from the docs' security guidance: if you are working on your own projects at your own desk, local is the most convenient and the approval prompts are your safety net. If you are running untrusted code, letting a bot accept messages from other people, or running unattended jobs, move commands into a container. The official tips go as far as recommending docker for untrusted code so that destructive commands stay inside the container, and the production checklist lists terminal.backend: docker alongside resource limits and a fixed terminal.cwd. Pick ssh when the work has to happen on a specific remote server, such as a build box or a home server, and you want Hermes's own state to stay on your laptop. Pick a cloud sandbox when you don't want to maintain Docker yourself, or need disposable environments. ### Two things that are easy to confuse Running Hermes in Docker is different from using Docker as a terminal backend. The official hermes-agent image runs the whole agent in a container with your data mounted at /opt/data; the docker backend keeps Hermes on the host and sends only commands into a sandbox container. You can combine them, but configure them separately. Profiles are not sandboxes either. A separate profile gives you separate config and memory, but on the local backend the agent still has your user account's file access. If isolation is the goal, the backend is what provides it. ### Common setup snags - Docker backend not connecting: run docker info, add your user to the docker group (sudo usermod -aG docker $USER, then newgrp docker) and test with docker run hello-world. - Tools such as node missing on the local backend: Hermes takes its environment from a login shell; list extra init files such as ~/.nvm/nvm.sh under terminal.shell_init_files. - Secrets: variables whose names contain KEY, TOKEN, SECRET or PASSWORD are stripped from child processes. Pass specific ones through with terminal.env_passthrough. ### Related guides - [Where Hermes Agent runs: host vs work environment](https://hermeswatcher.com/learn/where-hermes-runs.md) - [Hermes Agent security: approvals, allowlists, sandboxing](https://hermeswatcher.com/learn/security-model-approvals-and-sandboxing.md) - [Hermes Agent terminal can't find files or programs](https://hermeswatcher.com/troubleshoot/terminal-cannot-find-files-or-programs.md) - [Hermes Agent permissions for real workflows](https://hermeswatcher.com/learn/permissions-for-real-workflows.md) ### Related tools - [Build a useful GitHub issue review](https://hermeswatcher.com/workflows/github-issue-review.md) - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) ### Sources - [Configuration (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) - [Security (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/security) - [Docker (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/docker) - [FAQ and Troubleshooting (official docs)](https://hermes-agent.nousresearch.com/docs/reference/faq) ## Hermes Agent profiles: separate agents for separate jobs > How Hermes profiles give you independent agents on one machine, what they isolate (and what they don't), and the commands for creating, switching, sharing and running them. URL: https://hermeswatcher.com/learn/profiles-separate-agents Last reviewed: Oct 20, 2026 ### Why you might want more than one agent A profile is a complete, separate Hermes home directory. Each one has its own config.yaml, .env with API keys, SOUL.md personality, memories, sessions, skills, cron jobs, logs and state database. That makes it easy to keep a coding assistant, a personal Telegram bot and a research agent apart, each with its own model, tools and memory, instead of one agent whose memory is a muddle of three jobs. The default profile is ~/.hermes itself. Named profiles live under ~/.hermes/profiles/<name>/. ### Creating profiles hermes profile create <name> makes a blank profile with the bundled skills. Two flags save setup time: - --clone copies config, .env, SOUL.md, skills and memory files, but starts with empty sessions and no cron jobs. - --clone-all makes a fuller copy, still excluding session history and cron. - --clone-from <source> picks which profile to copy from, and --description "<role>" records what the profile is for. ### Switching between them Each profile gets its own command alias in ~/.local/bin, so after creating a profile called coder you can simply run coder chat, which is the same as hermes -p coder chat. The -p <name> flag works in any position on any command. If you mostly use one profile, make it sticky with hermes profile use <name>; plain hermes commands then target it until you run hermes profile use default. hermes profile list and hermes profile show <name> tell you what exists. ### What is not isolated This is the part people get wrong. Profiles separate state; they are not security sandboxes. - On the local terminal backend, every profile has the same file access as your user account. Use a container backend if you need isolation. - The working directory is set separately by terminal.cwd; set an absolute path if each profile should start in its own folder. - On host installs, external CLIs share your real HOME and their credentials unless you set terminal.home_mode: profile. - OAuth logins for providers such as Anthropic, OpenAI Codex and xAI are shared through the root auth.json by default, because their refresh tokens are single-use. Give a profile its own login with hermes -p <name> auth add <provider>. ### Running a bot per profile Each profile runs its own gateway as a separate process with its own bot token in its own .env. coder gateway start and assistant gateway start run independently, and coder gateway install creates a per-profile service. One bot token belongs to one profile: if two gateways try to use the same token, the second is blocked by a token lock. That is also why cloning does not copy bot tokens, allowlists or platform sections unless you pass --clone-channels. ### Sharing, retiring and one firm rule hermes profile export <name> produces a shareable .tar.gz with API keys stripped, and hermes profile import <file> installs one as a new profile. hermes profile delete <name> stops its gateway, removes the service and alias and deletes its data; the default profile can't be deleted this way. The firm rule from the docs: never point two agent processes at the same profile. Two writers on one home will mix their memory writes into shared state. If two agents genuinely need to share what they learn, use an external memory provider rather than a shared home. Also note that hermes update syncs bundled skills into every profile, and a profile with a broken config.yaml can make that step fail for the whole install, so keep unused profiles tidy or delete them. ### Related guides - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [How Hermes Agent memory works (and where it stops)](https://hermeswatcher.com/learn/how-hermes-memory-works.md) - [Hermes Agent terminal backends: local, Docker, SSH, cloud](https://hermeswatcher.com/learn/choosing-a-terminal-backend.md) - [Where Hermes Agent runs: host vs work environment](https://hermeswatcher.com/learn/where-hermes-runs.md) ### Related tools - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Turn a crowded inbox into a review queue](https://hermeswatcher.com/workflows/inbox-triage.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Telegram: reach Hermes from a private bot conversation](https://hermeswatcher.com/tools/telegram.md) - [Persistent memory: retain compact working knowledge](https://hermeswatcher.com/tools/memory.md) ### Sources - [Profiles (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/profiles) - [Persistent Memory (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) - [Messaging Gateway (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) ## Hermes Agent subagents and delegation explained > How Hermes's delegate_task tool spawns isolated child agents, what they can and can't do, the settings that cap concurrency and depth, and how to keep the cost sensible. URL: https://hermeswatcher.com/learn/subagents-and-delegation Last reviewed: Oct 20, 2026 ### What delegation is Delegation lets Hermes hand part of a job to a child agent through the delegate_task tool. A child starts with a fresh conversation: it receives only the goal and context the parent writes for it, plus the project's context files such as AGENTS.md (but not SOUL.md). It works through the task with its own tool calls and returns a result. Only that result comes back to your main conversation, which is why the official tips recommend delegation for parallel subtasks: the parent's context stays clean. You can give one task, or a batch of tasks that run in parallel and come back as one consolidated message. Each batched task can carry its own goal, context, up to eight images and an optional output_schema, a JSON Schema the child's final answer must match. That last option is handy when you want structured results you can compare side by side. ### What children can't do Children inherit the parent's enabled toolsets, but a few tools are always blocked for them: clarify, memory, send_message and cronjob. In plain terms, a child cannot stop to ask you a question, cannot write to shared persistent memory, cannot message people and cannot schedule jobs. Write the goal and context as if briefing a contractor who can't call you back: include the file paths, constraints and what a good answer looks like. By default children are leaf agents and cannot delegate further. delegation.max_spawn_depth is 1, so delegation is flat unless you raise it. ### The settings that matter All of these live under delegation: in config.yaml. - max_concurrent_children: how many children run in parallel per batch (default 10). A batch larger than this returns an error rather than being silently truncated. - max_spawn_depth: default 1. Raising it allows orchestrator children that spawn their own workers. - max_iterations: tool-call budget per child (default 250). A child that hits it returns exit_reason: max_iterations and truncated: true. - child_timeout_seconds: default 0, meaning no wall-clock cap; a positive value caps inactivity, not total runtime. - model / provider: an optional cheaper or different model for every child in the batch. - worktree_isolation: when true, each child working in a git repo gets its own worktree and branch, so parallel edits don't collide. ### Keeping costs predictable Parallel work multiplies tokens. The docs note that parallel batches typically account for most of a run's tokens, and warn that depth multiplies too: a depth of 3 with concurrency 3 can reach 27 concurrent leaf agents. Two practical levers: set delegation.model to a cheaper worker model while the main model handles planning, and keep max_spawn_depth at 1 unless you have a clear reason. Because delegate_task has no per-task model parameter, the delegation model applies to every child in a batch. In one-shot runs (hermes chat -q with --oneshot), delegation.oneshot_max_children caps total spawns at 2 by default. ### Watching and stopping children Top-level delegations run in the background by default and return a handle immediately, and each task writes a live transcript you can follow. The parent can list, steer or stop its own children, though steering is queued rather than guaranteed. Ordinary follow-up messages do not cancel background children. /stop, a Stop button, or closing or resetting the owning session does, and stopped children return status interrupted with their partial output. Note that a Hermes restart does not resume running children; their attempts are recorded as unknown, so rerun anything important. ### When not to delegate Delegation shines for independent, well-specified chunks: researching five vendors, reviewing several files, drafting variants. It is a poor fit for work that needs your input midway, work that must update memory, or tightly sequential steps where each depends on the last. For those, keep the work in the main session, or use /bg to run a single long task in a separate session without blocking your chat. ### Related guides - [How to keep Hermes Agent costs down](https://hermeswatcher.com/learn/keeping-costs-under-control.md) - [Hermes Agent stuck in a tool loop](https://hermeswatcher.com/troubleshoot/tool-loop-or-stuck-task.md) - [Turn a Hermes Agent use case into a repeatable workflow](https://hermeswatcher.com/learn/from-story-to-workflow.md) ### Related tools - [Collect content ideas without losing the evidence](https://hermeswatcher.com/workflows/content-research-queue.md) - [Build a useful GitHub issue review](https://hermeswatcher.com/workflows/github-issue-review.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) ### Sources - [Subagent Delegation (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/delegation) - [Tips and Best Practices (official guide)](https://hermes-agent.nousresearch.com/docs/guides/tips) ## How to keep Hermes Agent costs down > Where Hermes spends tokens, how to measure it, and the documented settings and habits that keep your provider bill predictable. URL: https://hermeswatcher.com/learn/keeping-costs-under-control Last reviewed: Oct 20, 2026 ### Where the money goes Hermes itself is free and MIT-licensed; what you pay for is model usage with your provider (local models cost nothing per token). Every message carries a fixed overhead: the system prompt, your context files, the skills index, both memory files and the schemas for every enabled tool. On top of that comes the conversation history, tool output and any subagent work. Most cost surprises come from one of three places: a bloated fixed prompt, long sessions that keep re-reading history, or parallel delegation. ### Measure before you change anything - hermes prompt-size: works offline and shows a byte breakdown of the system prompt and tool schemas, i.e. your per-message baseline. - /usage: token consumption for the current session. - /insights or hermes insights: token, cost and activity analytics; the tips page describes /insights as covering the last 30 days. - /context and /status in the CLI: how full the context window is, and which model and provider you are on. ### Shrink the fixed overhead Because the fixed prompt is resent with every message, small reductions pay off quickly. - Keep context files short; the docs point out they are injected into every message. - Disable toolsets you don't use with hermes tools, per platform. Each enabled tool adds schema text. For a single session, hermes chat --toolsets "web,terminal" loads only what you list. - Hide skills you don't need on a given platform with hermes skills. - Keep memory consolidated rather than full of stale entries. ### Protect the prompt cache Providers that support prompt caching charge less to re-read an unchanged prefix. Hermes is built around that: memory and the skill index are frozen at session start precisely so the prefix stays stable. You undo that benefit when the prefix changes. The tips and FAQ name the culprits: switching models with /model, automatic provider fallback and credential rotation all invalidate the cache, so the next message re-reads the whole conversation at full input price. An occasional switch is fine. On a long session, though, starting a fresh session on the other model can be cheaper than switching mid-stream, and delegating a subtask to a cheaper model avoids touching the main session's cache at all. The same logic applies to fallback: each switch costs a cache rebuild, so a flaky primary provider can quietly raise your bill. ### Use cheaper models where quality matters less Several background jobs can run on a cheaper model than your main one. Context compression uses auxiliary.compression.model (empty means the main model); the docs warn its context window must be at least as large as the main model's, or middle turns are dropped without a summary. Memory background review can also use a cheaper model under auxiliary.background_review. For delegation, delegation.model sets one worker model for every child, and the docs note parallel batches usually dominate a run's tokens. For day-to-day work the tips suggest matching model to task: frontier models for complex reasoning and architecture, faster ones for formatting and boilerplate. ### Put guardrails on runaway work - Cap tool-calling loops per turn with agent.max_turns in config or --max-turns <N> on the command line. - Leave delegation.max_spawn_depth at 1 and keep max_concurrent_children modest; depth and concurrency multiply. - Use /compress on long sessions, and /new at natural topic boundaries instead of one endless thread. - Ask the agent to write a script for batch file operations rather than running commands one at a time; the tips mention execute_code for this. - Review scheduled jobs: an unattended job that runs hourly on a frontier model adds up quickly. ### Related guides - [How to choose a model for Hermes Agent](https://hermeswatcher.com/learn/models-and-effective-configuration.md) - [Hermes Agent subagents and delegation explained](https://hermeswatcher.com/learn/subagents-and-delegation.md) - [Hermes Agent rate limits and provider errors](https://hermeswatcher.com/troubleshoot/rate-limits-and-provider-errors.md) - [Hermes Agent forgets things mid-conversation](https://hermeswatcher.com/troubleshoot/forgets-mid-conversation.md) ### Related tools - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) - [Scheduled tasks: automate a proven run](https://hermeswatcher.com/tools/scheduling.md) ### Sources - [Tips and Best Practices (official guide)](https://hermes-agent.nousresearch.com/docs/guides/tips) - [FAQ and Troubleshooting (official docs)](https://hermes-agent.nousresearch.com/docs/reference/faq) - [Configuration (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) - [Fallback Providers (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers) - [Subagent Delegation (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/delegation) - [CLI Commands Reference (official docs)](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) ## Hermes Agent security: approvals, allowlists, sandboxing > How Hermes's layered defences fit together, from dangerous-command approval and the hardline blocklist to file-write guards, container backends and gateway authorisation, and what each layer does not protect against. URL: https://hermeswatcher.com/learn/security-model-approvals-and-sandboxing Last reviewed: Oct 20, 2026 ### Layers, not a single wall The official security page describes eight layers: user authorisation, dangerous-command approval, file write safety, container isolation, MCP credential filtering, context file scanning, cross-session isolation and input sanitisation. None is meant to be perfect on its own. The useful mental model is: approvals and blocklists reduce accidents, containers provide real isolation, and authorisation decides who gets to ask in the first place. ### Dangerous-command approval Before running a command that looks risky, Hermes applies the policy in approvals.mode: - smart (default): an auxiliary model rates the risk, auto-approves low-risk commands, auto-denies dangerous ones and asks you when unsure. - manual: always prompts for dangerous commands. - off: disables checks, equivalent to --yolo. The docs say to use this only in trusted environments such as CI or containers. ### Timeouts, headless runs and the allowlist Prompts left unanswered are denied after approvals.timeout (300 seconds by default). Headless runs (cron jobs, one-shot hermes chat --oneshot runs and webhook/API sessions) default to deny through cron_mode, single_query_mode and unattended_mode, which is why an unattended task can fail on a command that works interactively. When you approve, you can choose once, for the session, always, or deny. "Always" saves the pattern to command_allowlist in config.yaml permanently, so the tips recommend starting with session. hermes approvals suggest proposes allowlist entries from your past approvals but applies nothing without --apply, and never proposes recursive deletes or sudo. Two backstops sit underneath. A hardline blocklist refuses commands such as rm -rf /, fork bombs and piping untrusted URLs to sh regardless of mode, YOLO or allowlists. And approvals.deny lets you add your own glob patterns that are blocked before YOLO or mode: off is even consulted. The docs caution that pattern matching is not a full shell parser, so it should not be your only containment. ### File writes and secrets The write_file and patch tools refuse to touch protected paths such as ~/.ssh/, ~/.aws/, .env files and Hermes's secret stores; you can narrow writes further with HERMES_WRITE_SAFE_ROOT. The docs are candid that the terminal tool runs as your user and can bypass these guards, so they reduce accidental damage rather than stopping a determined agent. Environment variables whose names contain KEY, TOKEN, SECRET, PASSWORD and similar are stripped from child processes unless you allow them via terminal.env_passthrough. MCP server subprocesses get only a short list of safe variables plus anything you configure, and MCP error messages are redacted before the model sees them. Optional checkpoints (checkpoints.enabled, off by default) snapshot files before edits and destructive commands so /rollback can restore them, though not on container backends. ### Containers as the real boundary The Docker backend drops Linux capabilities, sets no-new-privileges, limits processes to 256 and uses size-limited temporary mounts. Because the container is treated as the boundary, Docker, Singularity, Modal, Daytona and Vercel Sandbox skip the dangerous-command checks entirely. That is a deliberate trade: the tips remind you to lock down your container images, since nothing inside will be second-guessed. ### Who can reach the agent, and what it reads On the gateway, default-deny plus allowlists or DM pairing decide who can talk to the bot; GATEWAY_ALLOW_ALL_USERS=true is explicitly discouraged for any bot with terminal access. Context files such as AGENTS.md and .cursorrules are scanned for prompt injection and blocked on a match. URL tools block private, loopback and cloud-metadata addresses by default, and security.website_blocklist lets you deny domains across web and browser tools. The docs' production checklist is a good closing summary: explicit allowlists, a container backend with resource limits and a fixed terminal.cwd, secrets in ~/.hermes/.env with chmod 600, DM pairing on, a reviewed command_allowlist, a non-root user, an eye on ~/.hermes/logs/, and regular hermes update. ### Related guides - [Hermes Agent permissions for real workflows](https://hermeswatcher.com/learn/permissions-for-real-workflows.md) - [Hermes Agent task denied when scheduled](https://hermeswatcher.com/troubleshoot/unattended-task-permission-denied.md) - [Hermes Agent terminal backends: local, Docker, SSH, cloud](https://hermeswatcher.com/learn/choosing-a-terminal-backend.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) ### Related tools - [Turn a crowded inbox into a review queue](https://hermeswatcher.com/workflows/inbox-triage.md) - [Build a useful GitHub issue review](https://hermeswatcher.com/workflows/github-issue-review.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Telegram: reach Hermes from a private bot conversation](https://hermeswatcher.com/tools/telegram.md) - [MCP: connect external tool servers](https://hermeswatcher.com/tools/mcp.md) ### Sources - [Security (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/security) - [Tips and Best Practices (official guide)](https://hermes-agent.nousresearch.com/docs/guides/tips) - [Checkpoints and Rollback (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/checkpoints-and-rollback) ## How to update Hermes Agent safely > What hermes update actually does, how to preview and back up before updating, how release channels work, and how to recover if an update goes wrong. URL: https://hermeswatcher.com/learn/updating-hermes-safely Last reviewed: Oct 20, 2026 ### Know which update path you're on How you update depends on how you installed. The hermes update command is for source checkouts made by the install script. Desktop packages update through the in-app Update control; Docker users pull a new image and recreate the container; Termux uses pkg upgrade hermes-agent; Nix uses its own flake commands. Image-managed Docker installs refuse hermes update outright (exit code 2). If you're not sure which you have, hermes doctor reports the update method that applies. ### Preview before you pull Two read-only commands let you look before you leap. hermes update --check tells you whether your checkout is behind without applying anything. hermes update --plan lists the services, supervisors and restart methods the update would touch, which is worth a glance if you run gateways for several profiles. If you'd like belt and braces, hermes backup writes your whole Hermes home to a zip file, and hermes update --backup adds a full pre-pull backup to the run. ### What happens during an update - Pre-update snapshot: config.yaml, .env, auth.json, pairing data and cron jobs are saved. Quick snapshots are the default; set updates.pre_update_backup to quick, full or off. - Code update: the checkout moves to the configured release tag or branch. On Linux and macOS, gateways are paused first. - Syntax check with automatic rollback: if a critical file fails to parse, Hermes resets the checkout to the pre-pull commit. - Dependencies are prepared and validated. - Config migration: you're prompted for new options. You can rerun this later with hermes config check and hermes config migrate. - Gateways that were paused or service-managed are restarted (skip with --no-gateway-restart). ### Stable versus main Official checkouts follow the stable channel by default: the latest published vX.Y.Z release, never drafts or prereleases. hermes update --channel main tries main once without saving the choice; hermes update --set-channel main follows every commit; hermes update --set-channel stable takes you back to releases. For an agent that runs your bots or scheduled jobs, stable is the sensible default. If passive update notices bother you, hermes config set updates.check false turns them off without affecting manual checks. ### If you've edited the source Local edits to the checkout are stashed during updates. In non-interactive runs, updates.non_interactive_local_changes chooses stash (default) or discard. Find parked edits with git stash list and reapply them with git stash apply. If you made local commits on main, the update resets main to the upstream branch and saves your old HEAD under refs/hermes-update-backups/, so nothing is lost. After any update, git status --short shows whether anything was reapplied. ### After the update, and rolling back A quick post-update check from the docs: hermes doctor, hermes --version, hermes gateway status and hermes pm status. If a bot still behaves like the old version, run hermes gateway restart or rerun hermes update, which retries interrupted restarts. Updates ignore terminal disconnects and log to ~/.hermes/logs/update.log. Rolling back takes more care than updating. Automatic rollback only covers the syntax-check failure; code rollback never restores data. Once a new gateway has written state.db, older releases refuse to run on it. To go back anyway, stop the gateway, check out the older release, then restore the newest pre-update snapshot or a full backup with hermes import <backup.zip>. Sessions created after the update won't be in that snapshot, which is one more reason to stay on stable and update deliberately rather than on autopilot. ### Related guides - [Hermes Agent install or update failed](https://hermeswatcher.com/troubleshoot/install-or-update-failed.md) - [Where Hermes Agent runs: host vs work environment](https://hermeswatcher.com/learn/where-hermes-runs.md) - [Hermes Agent profiles: separate agents for separate jobs](https://hermeswatcher.com/learn/profiles-separate-agents.md) ### Related tools - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) ### Sources - [Updating and Uninstalling (official docs)](https://hermes-agent.nousresearch.com/docs/getting-started/updating) - [Installation (official docs)](https://hermes-agent.nousresearch.com/docs/getting-started/installation/) - [Docker (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/docker) ## Moving to Hermes Agent from OpenClaw and other agents > Use the built-in, preview-first importers to bring your persona, memory, skills, model settings and bot tokens across, then finish the handful of things that never migrate automatically. URL: https://hermeswatcher.com/learn/moving-from-openclaw-and-other-agents Last reviewed: Oct 20, 2026 ### Two importers, one pattern Hermes ships two migration commands. `hermes claw migrate` imports an OpenClaw setup, including older Clawdbot and Moltbot installs. `hermes import-agent` imports a Claude Code (`~/.claude`) or OpenAI Codex CLI (`~/.codex`) setup. Both work the same way: they print a per-item plan before writing anything, and `--dry-run` stops after the preview without touching disk. If you are installing Hermes fresh, the `hermes setup` wizard notices an existing `~/.openclaw` folder and offers to migrate before configuration starts. If you would rather be walked through it conversationally, with per-item conflict decisions, there is also an optional skill: `hermes skills install official/migration/openclaw-migration`. It runs the same migration script behind the CLI command. ### Do a dry run first Start with `hermes claw migrate --dry-run`. The command looks in `~/.openclaw` first, then the legacy `~/.clawdbot` and `~/.moltbot` folders. If your install lives elsewhere, add `--source /path/to/openclaw`. Read the preview carefully. It lists what will be imported, what conflicts with files you already have in Hermes, and what will only be archived. When the plan looks right, run `hermes claw migrate` and confirm. The flags worth knowing: - `--preset full` (the default) or `--preset user-data`, which leaves out infrastructure config. Neither preset copies secrets. - `--migrate-secrets` copies allowlisted API keys and bot tokens such as `TELEGRAM_BOT_TOKEN` into `~/.hermes/.env`. You have to pass it explicitly, even with `--preset full`. - `--overwrite` replaces conflicting Hermes files. Without it, the migration refuses to apply a plan that has conflicts. - `--skill-conflict skip|overwrite|rename` decides what happens when a skill name already exists. `rename` keeps both copies and gives the imported one an `-imported` suffix. - `--workspace-target <path>` is required if you want your workspace `AGENTS.md` copied into a project folder. - Before applying, Hermes writes a zip snapshot of `~/.hermes/` under `~/.hermes/backups/pre-migration-*.zip`, which you can restore with `hermes import`. Only skip this with `--no-backup` if you have your own backup. ### What comes across, and where it lands Your `SOUL.md` persona is copied to `~/.hermes/SOUL.md`. `MEMORY.md`, `USER.md` and the daily memory files are parsed into entries and merged, with duplicates removed, into `~/.hermes/memories/`. Skills from all four OpenClaw skill locations end up in `~/.hermes/skills/openclaw-imports/`. The default model, custom providers, MCP servers, TTS settings, browser settings, the exec timeout and Docker sandbox settings are mapped to their `config.yaml` equivalents. Telegram, Discord, Slack, Signal, Matrix and Mattermost tokens and allowlists are mapped to `.env` variables. Look closely at one mapping: OpenClaw approval mode `auto` becomes Hermes `approvals.mode: off`, which means no approval prompts at all. If you relied on that in OpenClaw, think about whether you still want it. We suggest starting on the Hermes default, `smart`, and loosening it later. ### What does not migrate automatically Anything without a direct Hermes equivalent is saved under `~/.hermes/migration/openclaw/<timestamp>/archive/` for you to handle by hand. That covers cron jobs, plugins, hooks and webhooks, the memory backend config, multi-agent lists, channel bindings, and the `IDENTITY.md`, `TOOLS.md`, `HEARTBEAT.md` and `BOOTSTRAP.md` workspace files. The official guide gives a replacement for each one: - Recreate scheduled work with `hermes cron create`. Periodic tasks from `HEARTBEAT.md` also become cron jobs. - Merge anything worth keeping from `IDENTITY.md` into `SOUL.md`. - Rebuild a multi-agent setup as Hermes profiles. - Idle and daily session-reset timers are deliberately not imported. Hermes conversations continue until you run `/new` or `/reset`. - WhatsApp pairs by QR code, so it has to be paired again with `hermes whatsapp`. - Secrets stored as SecretRefs with `source: file` or `source: exec` can't be resolved. Add those values yourself with `hermes config set`. ### After the import Read the report printed at the end, then start a new session. Imported skills and memory only show up in new sessions. Run `hermes status` to confirm your provider credentials, and `/skills` to check that the imported skills loaded. If tokens moved over, restart the gateway, for example with `hermes gateway restart`. When everything works, run `hermes claw cleanup`. It renames leftover OpenClaw folders with a `.pre-migration` suffix, so the two agents can't end up fighting over the same state. Stop OpenClaw first. The command warns if it is still running, because an active service can immediately recreate an empty folder. You can preview the cleanup with `--dry-run`. ### Coming from Claude Code or Codex instead `hermes import-agent claude-code` or `hermes import-agent codex` (or just `hermes import-agent` to auto-detect) brings over global instructions as memory entries, `Bash(...)` allow and deny rules as `command_allowlist` and `approvals.deny`, MCP servers, and skill folders. Claude Code slash commands are skipped with a note suggesting you convert them into skills. Credentials are never imported, and MCP environment values with secret-looking names are stripped and listed so you can add them back on purpose. If you keep using the other agent alongside Hermes, `hermes import-agent --sync` re-imports only the sources that have changed. That makes it safe to run on a schedule. ### Related guides - [Hermes Agent setup: your first 24 hours](https://hermeswatcher.com/learn/first-24-hours-default-setup.md) - [How Hermes Agent memory works (and where it stops)](https://hermeswatcher.com/learn/how-hermes-memory-works.md) - [Hermes Agent profiles: separate agents for separate jobs](https://hermeswatcher.com/learn/profiles-separate-agents.md) - [Hermes Agent SOUL.md and personalities explained](https://hermeswatcher.com/learn/soul-md-and-personalities.md) ### Related tools - [Carry project knowledge into the next session](https://hermeswatcher.com/workflows/project-knowledge.md) - [Skills: reusable procedures for repeated work](https://hermeswatcher.com/tools/skills.md) - [Persistent memory: retain compact working knowledge](https://hermeswatcher.com/tools/memory.md) - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) - [MCP: connect external tool servers](https://hermeswatcher.com/tools/mcp.md) - [Telegram: reach Hermes from a private bot conversation](https://hermeswatcher.com/tools/telegram.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) ### Sources - [Migrate from OpenClaw (official guide)](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw) - [CLI Commands Reference: hermes claw (official docs)](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) - [Openclaw Migration skill (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/skills/optional/migration/migration-openclaw-migration) - [Import from Other Agents (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/import-from-other-agents) ## Hermes Agent setup: your first 24 hours > An opinionated, documentation-grounded checklist for a new Hermes install: one working model, deliberate tools and approvals, memory you can trust, one skill, one scheduled job and a paired phone. URL: https://hermeswatcher.com/learn/first-24-hours-default-setup Last reviewed: Oct 20, 2026 ### The rule for day one The official quickstart has one rule of thumb, and we'd make it the rule for your whole first day: if Hermes can't complete a normal chat, don't add more features yet. Every step below assumes the one before it works. If something breaks, run the recovery order from the docs: `hermes doctor`, then `hermes model`, then `hermes setup`. ### Hour one: a model that actually answers Run `hermes setup`, or `hermes model` if you already know your provider. The quickest path is the Nous Portal option (`hermes setup --portal`), which handles login, model choice and the Tool Gateway in one step. Any provider in the catalog works, though. If you plan to run a local model, set its context to at least 64,000 tokens before you start. Hermes rejects smaller windows at startup. Then prove it works. Start `hermes` (or `hermes --tui` for the newer interface), ask something you can check, such as which file in the current folder looks like the main entrypoint, and keep the conversation going for a couple of turns. Exit, then run `hermes --continue` to make sure the session resumes. Use `hermes status` for a one-screen summary of your model, provider and gateway state. ### Hour two: tools and approvals on purpose Run `hermes tools` to see which toolsets are enabled on each platform, or `hermes tools --summary` for a quick printout. Our suggestion is to switch off anything you don't expect to use this week. Fewer tools means a smaller prompt and fewer surprises. You can always turn them back on. Keep `approvals.mode` on the default, `smart`. Low-risk commands are approved automatically, clearly dangerous ones are denied, and uncertain ones come to you. Avoid `off` and `/yolo` until you know how the agent behaves on your machine. Note that scheduled jobs deny dangerous commands by default (`approvals.cron_mode: deny`), which is a sensible default to keep. If you want stronger isolation, set `terminal.backend` to `docker` with `hermes config set terminal.backend docker`. ### Hour three: memory you can trust Built-in memory is on by default, stored in `MEMORY.md` and `USER.md`. Tell Hermes a few durable facts: your name, your timezone, where your projects live. Then run `/new` and ask it to recall them. Memory is loaded as a snapshot at the start of a session, so new entries only show up after a session boundary. That's normal, not a bug. If you'd rather approve what the agent writes about you, set `memory.write_approval: true`. Writes that aren't made in the foreground of the CLI are then staged for review with `/memory pending`, and you approve or reject them with `/memory approve` and `/memory reject`. This is optional, but useful while you're still building trust. ### Afternoon: one skill and one scheduled job Hermes already ships with bundled skills, and the agent picks them up by itself when a task matches one. Install exactly one more from the hub: browse with `hermes skills browse` or search with `hermes skills search <keyword>`, preview it with `hermes skills inspect <identifier>`, then install it with `hermes skills install <identifier>`. Installation runs a security scan first. Every installed skill also becomes a slash command. Next, create one recurring job whose result is easy to check, for example: `hermes cron create "every 1d at 09:00" "Summarize what changed in my notes folder yesterday" --name "Morning check"`. Cron jobs are run by the gateway, which ticks the scheduler every 60 seconds, so the gateway has to be running (next step). Check it with `hermes cron status` and `hermes cron list`, and trigger it once with `hermes cron run <job_id>` so you don't have to wait until tomorrow. ### Evening: pair your phone Run `hermes gateway setup` and connect one platform. Telegram is the most common choice. Install it as a background service with `hermes gateway install` (a user service on Linux, launchd on macOS, a login-time Scheduled Task on Windows) so it doesn't depend on an open terminal, then check it with `hermes gateway status`. Then DM your bot. By default, an unknown sender gets an 8-character pairing code, which expires after one hour. Approve yourself on the host with `hermes pairing approve telegram <CODE>`, and check who has access with `hermes pairing list`. In the chat, run `/sethome` so scheduled results have a home channel, then point your job at it with `hermes cron edit <job_id> --deliver telegram`. ### Before bed - Take a snapshot with `hermes backup` now that you have a setup worth keeping. - Leave fallback providers, extra profiles and more skills for day two. The docs recommend getting the base provider stable before adding routing. - On messaging platforms, a chat is one continuous session until you run `/new`. Start a fresh one at natural breaks so memory and costs stay healthy. ### Related guides - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [Hermes Agent security: approvals, allowlists, sandboxing](https://hermeswatcher.com/learn/security-model-approvals-and-sandboxing.md) - [How Hermes Agent memory works (and where it stops)](https://hermeswatcher.com/learn/how-hermes-memory-works.md) - [How to write your first Hermes Agent skill](https://hermeswatcher.com/learn/writing-your-first-skill.md) - [How to schedule recurring tasks in Hermes Agent](https://hermeswatcher.com/learn/scheduling-with-evidence.md) - [Moving to Hermes Agent from OpenClaw and other agents](https://hermeswatcher.com/learn/moving-from-openclaw-and-other-agents.md) ### Related tools - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) - [Persistent memory: retain compact working knowledge](https://hermeswatcher.com/tools/memory.md) - [Skills: reusable procedures for repeated work](https://hermeswatcher.com/tools/skills.md) - [Scheduled tasks: automate a proven run](https://hermeswatcher.com/tools/scheduling.md) - [Telegram: reach Hermes from a private bot conversation](https://hermeswatcher.com/tools/telegram.md) ### Sources - [Quickstart (official docs)](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) - [Tools and Toolsets (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) - [Security (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/security) - [Persistent Memory (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) - [Scheduled Tasks (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) - [Messaging Gateway (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) - [CLI Commands Reference (official docs)](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) ## Hermes Agent event hooks explained > Choose between gateway hooks, shell hooks, plugin hooks and outbound webhooks, and set up a hook that logs, blocks or notifies without surprising you later. URL: https://hermeswatcher.com/learn/event-hooks-explained Last reviewed: Oct 20, 2026 ### Four hook systems, four jobs Hooks let you run code at fixed points in Hermes' lifecycle: when a session starts, before a tool runs, after the model replies, when a subagent finishes. Hermes has four separate systems for this, and choosing the right one is most of the work: - Gateway hooks: a `HOOK.yaml` and a `handler.py` in a folder under `~/.hermes/hooks/`. They run only in the messaging gateway and suit logging, alerts and webhooks. - Shell hooks: a `hooks:` block in `config.yaml` that points at any executable script. They run in the CLI, the gateway, and the Desktop, TUI and dashboard chats, and they can block tool calls or inject context. - Plugin hooks: Python callbacks registered with `ctx.register_hook()` inside a plugin. They run in the CLI and the gateway. - Outbound webhooks: a `hooks.outbound:` list that POSTs signed JSON to HTTP endpoints when events fire. Nothing runs on your machine. ### Gateway hooks for chat-side alerts A gateway hook is a folder with two files. `HOOK.yaml` lists the events it listens to, such as `gateway:startup`, `session:start`, `session:reset`, `agent:start`, `agent:step`, `agent:end` or the wildcard `command:*`. `handler.py` defines a function named `handle` that receives the event type and a context dictionary. It can be async or a regular function. Errors are caught and logged, so a broken hook never crashes the agent. Be aware of the trust model. Putting the files in the folder is the opt-in. There is no enable list and no sandbox, and the handler runs inside the gateway process with the same access the gateway has. Read any hook's `handler.py` before you install it, just as you would a plugin. Gateway hooks load once, when the gateway starts, so restart the gateway after adding one. ### Shell hooks for guardrails and context Shell hooks are where most people should start, because they need no Python and work almost everywhere. Each entry names a plugin-hook event, an optional `matcher` regex (used only for `pre_tool_call` and `post_tool_call`), a `command`, and an optional `timeout` (default 60 seconds, capped at 300). Hermes sends a JSON payload to the script on stdin and reads JSON back from stdout. Three uses come up most often. A `post_tool_call` hook matching `write_file|patch` can auto-format files the agent just wrote. A `pre_tool_call` hook matching `terminal` can block a command by printing `{"decision": "block", "reason": "..."}`, or simply by exiting with code 2. A `pre_llm_call` hook can return `{"context": "..."}` to add something like `git status` output to the next turn. ### Consent and fail-closed behaviour The first time Hermes sees a given event and command pair, it asks before running it, and stores your answer in `~/.hermes/shell-hooks-allowlist.json`. Only a foreground `hermes chat` ever shows that prompt. The gateway, cron and other headless runs skip any hook that hasn't been approved and log a warning, so approve new hooks interactively first, or use `--accept-hooks`, `HERMES_ACCEPT_HOOKS=1` or `hooks_auto_accept: true` if you understand the trade-off. Two details matter for safety. First, consent is tied to the command string, not the script's contents, so later edits to the script are trusted silently. `hermes hooks doctor` flags scripts that changed after approval. Second, shell hooks fail open by default: a crash or timeout logs a warning and the tool call goes ahead. For a security check such as a secret scanner, set `fail_closed: true` on the `pre_tool_call` entry so a broken check blocks the call instead. ### Testing and maintaining hooks - `hermes hooks list` shows configured shell hooks and outbound targets, with matcher, timeout and consent status. - `hermes hooks test <event>` fires matching hooks with a synthetic payload and prints the parsed response. Use `--for-tool terminal` to test a tool matcher. - `hermes hooks revoke <command>` removes a consent entry. A running gateway stops running that hook within about 30 seconds. - `hermes hooks doctor` checks the executable bit, consent, changed scripts, JSON output and rough run time. - The dashboard's System page can also list, create and remove shell hooks, and its create form includes an explicit consent checkbox. ### Outbound webhooks to tell other systems If all you need is for another system to find out that something happened, such as a CI server or a monitoring board, use `hooks.outbound:` instead of writing a script. Each entry has a `url`, a list of `events` (for example `on_session_end` or `subagent_stop`), an optional `matcher` for tool events, and ideally `secret_env`, which names an environment variable holding the signing secret. Entries without a secret are sent unsigned and shown as `UNSIGNED` by `hermes hooks list`. Payloads include tool inputs, so only send them to endpoints you trust, preferably over `https://`. ### Related guides - [Hermes Agent security: approvals, allowlists, sandboxing](https://hermeswatcher.com/learn/security-model-approvals-and-sandboxing.md) - [Hermes Agent skills vs plugins vs MCP: which to use](https://hermeswatcher.com/learn/skills-plugins-and-mcp.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [Hermes Agent web dashboard: a quick tour](https://hermeswatcher.com/learn/web-dashboard-tour.md) ### Related tools - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Plugins: add tools and lifecycle behavior](https://hermeswatcher.com/tools/plugins.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Telegram: reach Hermes from a private bot conversation](https://hermeswatcher.com/tools/telegram.md) ### Sources - [Event Hooks (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks) - [CLI Commands Reference: hermes hooks (official docs)](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) - [Security (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/security) ## Hermes Agent SOUL.md and personalities explained > Use SOUL.md for the durable identity and tone of your agent, /personality for temporary modes, and AGENTS.md for project rules, so each layer does one job. URL: https://hermeswatcher.com/learn/soul-md-and-personalities Last reviewed: Oct 20, 2026 ### What SOUL.md actually is `SOUL.md` is the first thing in Hermes' system prompt. It is the agent's identity, and it replaces the built-in default identity instead of being added on top of it. Hermes creates a starter file at `~/.hermes/SOUL.md` (strictly, `$HERMES_HOME/SOUL.md`) the first time it runs and never overwrites a file you've already edited. If the file is empty or can't be read, Hermes falls back to its built-in identity. Hermes only loads `SOUL.md` from its home folder, never from the directory you launch it in. That's deliberate: your agent's personality shouldn't change because you `cd` into a different project. Each profile has its own home, so each profile can have its own `SOUL.md`. That's a clean way to run a terse coding agent next to a warmer personal assistant. ### What belongs in it, and what doesn't The docs draw a sharp line here. `SOUL.md` is for things that should follow you everywhere: tone, directness, how to handle uncertainty and disagreement, and what to avoid in style. `AGENTS.md` is for things that belong to one project: architecture, coding conventions, commands, ports, paths and deployment notes. A good test is to ask whether the instruction would still make sense in a completely different folder. If it would, it belongs in `SOUL.md`. - Strong: a few specific lines about voice. For example: be direct, admit uncertainty plainly, push back on weak ideas, keep answers compact unless depth helps. - Weak: generic filler like 'be helpful and clear'. Hermes already does that. - Wrong place: file paths, repo rules, temporary task instructions, or anything that tries to micro-manage the shape of every response. ### A first edit that pays off You don't need a long file. The official guide suggests changing a few lines so the agent sounds like someone you want to work with, then living with it for a few days. A simple structure helps: Identity (who the agent is), Style (how it sounds), Avoid (what it shouldn't do), and Defaults (how it behaves when a request is ambiguous). Edit the file directly, then start a new session to hear the difference. Because `SOUL.md` is your own file, Hermes still scans it for prompt-injection patterns, but a match doesn't block it the way it would block a project `AGENTS.md`. The file still loads, Hermes logs a warning, and `/context` marks the file for review. If you see that warning, read the flagged line rather than ignoring it. ### Personalities are temporary overlays `/personality` switches the agent into a mode for the current conversation without touching your `SOUL.md`. Built-in presets include `helpful`, `concise`, `technical`, `creative` and `teacher`, plus playful ones like `pirate`, `noir` and `shakespeare`. Type `/personality` on its own to list them and see which is active, and use `/personality none` (or `default` or `neutral`) to go back to your base voice. Presets work in the CLI, the TUI, the desktop app and messaging platforms. You can define your own under `agent.personalities` in `config.yaml`. For example, a `codereviewer` entry with a short paragraph describing a meticulous reviewer becomes available as `/personality codereviewer`. Reusing a built-in name overrides that preset. The active selection is stored as a name in `display.personality`, and personalities never change `agent.system_prompt`. ### How the layers stack Roughly, the prompt is built in this order: `SOUL.md` first, then tool guidance, memory and user context, skills guidance, context files such as `AGENTS.md`, the timestamp, platform formatting hints, and finally any overlay such as `/personality`. The recommended setup follows from that order: a thoughtful global `SOUL.md`, project instructions in `AGENTS.md`, and `/personality` only when you want a temporary change of mode. Terminal appearance is a separate setting entirely. `/skin` and `display.skin` change how Hermes looks, not how it talks. ### Related guides - [Hermes Agent memory vs context files vs project notes](https://hermeswatcher.com/learn/memory-context-and-project-records.md) - [Hermes Agent ignoring your project instructions](https://hermeswatcher.com/troubleshoot/project-instructions-not-loaded.md) - [Hermes Agent profiles: separate agents for separate jobs](https://hermeswatcher.com/learn/profiles-separate-agents.md) - [Hermes Agent setup: your first 24 hours](https://hermeswatcher.com/learn/first-24-hours-default-setup.md) ### Related tools - [Carry project knowledge into the next session](https://hermeswatcher.com/workflows/project-knowledge.md) - [Context files: give a project durable instructions](https://hermeswatcher.com/tools/context-files.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Persistent memory: retain compact working knowledge](https://hermeswatcher.com/tools/memory.md) ### Sources - [Personality and SOUL.md (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/personality) - [Use SOUL.md with Hermes (official guide)](https://hermes-agent.nousresearch.com/docs/guides/use-soul-with-hermes) - [Context Files (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) ## Hermes Agent web dashboard: a quick tour > What the local dashboard can do, which pages save you the most time, and how to reach it from another machine without exposing your API keys. URL: https://hermeswatcher.com/learn/web-dashboard-tour Last reviewed: Oct 20, 2026 ### Starting it Run `hermes dashboard`. Hermes starts a local web server and opens `http://127.0.0.1:9119` in your browser. By default it binds to `127.0.0.1` with no login, because it's only reachable from your own machine. Useful flags are `--port` to change the port, `--no-open` to skip opening the browser, and `--host` to change the bind address (see the security section below before you use that one). The dashboard is machine-level: one server manages every profile. When more than one profile exists, a switcher in the sidebar decides which profile the Config, API Keys, Skills, MCP and Chat pages read from and write to, and an amber banner appears when you're managing a profile other than the dashboard's own. Running a profile alias such as `worker dashboard` opens the same server with that profile selected. ### The pages worth learning first - Status: version, gateway state and connected platforms, active and recent sessions. It refreshes every five seconds, and a banner warns when the host is low on memory or disk. - Config: a form editor for `config.yaml`. Dropdowns and toggles appear wherever values are constrained, for example `approvals.mode`. Changes apply to the next session or after a gateway restart. - API Keys: set, update or delete values in `.env`, with redacted previews. In a running CLI session, `/reload` picks up new keys without a restart. - Sessions: full-text search, expandable transcripts with tool calls, rename, export to JSON, prune and delete. - Logs and Analytics: filtered and live-tailed agent, gateway and error logs, plus token and cost breakdowns over 7, 30 or 90 days. - Cron, Skills, MCP, Webhooks, Pairing and Channels: browser versions of the matching CLI commands. Pairing, for example, lets you approve or revoke messaging users without a terminal. - System: gateway start, stop and restart, memory provider choice, credential pool, `doctor`, backup and restore, checkpoint pruning and shell hooks. ### The Chat tab Chat embeds the real Hermes TUI, the same interface as `hermes --tui`, in the browser. Slash commands, the model picker, approval prompts and tool cards all behave the same way. A right-hand rail lists recent sessions for the active profile so you can switch between them, and a workspace picker chooses the folder a new chat starts in. That's handy when you're driving Hermes from a phone and want it working in a specific repository. The chat pane needs Node.js, like the TUI, and a working pseudo-terminal. On native Windows the official docs describe a ConPTY bridge through `pywinpty`, and note that a missing or broken native dependency can make the terminal unavailable. If you see a banner in place of the terminal, the rest of the dashboard still works, and WSL2 is the documented alternative. ### Reaching it from another machine, safely The dashboard reads and writes your `.env`, so treat it like the keys themselves. Binding to anything other than `127.0.0.1`, `::1` or `localhost`, including `--host 0.0.0.0`, turns on an authentication gate. The server refuses to start until an auth provider is configured. Three ship with Hermes: username and password (for a trusted network or VPN only), Nous Portal OAuth (recommended for anything reachable from the internet), and self-hosted OIDC. The old `--insecure` flag no longer turns authentication off. For a personal server, the simplest approach is the one the docs suggest: keep the dashboard on `127.0.0.1` and reach it over an SSH tunnel or Tailscale. You get no login screen and no public port. ### When the dashboard won't start FastAPI, Uvicorn and the PTY helper are core dependencies. If they're damaged, `hermes pm repair` followed by a restart is the documented fix. On first launch the frontend builds itself automatically if `npm` is available. If you just changed something in Config or Channels and nothing happened, remember that most changes take effect on the next session or gateway restart. Channels has a restart button on the page for exactly that reason. ### Related guides - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [Hermes Agent sessions: search and resume past work](https://hermeswatcher.com/learn/sessions-and-session-search.md) - [How to keep Hermes Agent costs down](https://hermeswatcher.com/learn/keeping-costs-under-control.md) - [Hermes Agent event hooks explained](https://hermeswatcher.com/learn/event-hooks-explained.md) - [Hermes Agent profiles: separate agents for separate jobs](https://hermeswatcher.com/learn/profiles-separate-agents.md) ### Related tools - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Desktop: manage conversations and inspect artifacts visually](https://hermeswatcher.com/tools/desktop.md) - [Scheduled tasks: automate a proven run](https://hermeswatcher.com/tools/scheduling.md) - [Skills: reusable procedures for repeated work](https://hermeswatcher.com/tools/skills.md) - [MCP: connect external tool servers](https://hermeswatcher.com/tools/mcp.md) ### Sources - [Hermes Web Dashboard (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/web-dashboard) - [CLI Commands Reference: hermes dashboard (official docs)](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) - [Windows (Native) Guide (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native) ## Hermes Agent goals and loops: keep it working on its own > When to use /goal to keep working until something is done, /loop to repeat a check on a timer, and cron for work that must run when you are away. URL: https://hermeswatcher.com/learn/goals-and-loops Last reviewed: Oct 20, 2026 ### Three ways to keep work moving Hermes has two in-session commands for work that takes more than one turn, and they're easy to confuse. `/goal` is judge-driven: after each turn a small judge model checks whether the objective is met, and if it isn't, Hermes continues automatically. `/loop` is timer-driven: it re-runs a prompt every few minutes until a stop condition fires. Both live inside your current session. For anything that has to run unattended, survive restarts, or happen while you're away, use a cron job instead. Kanban is a separate tool again, a board of many tasks handed to worker processes, and `/goal` never creates kanban cards. ### Setting a goal that can actually finish `/goal <text>` sets the objective and starts the first turn right away. You'll see a continuation line after each turn until the judge declares it achieved, or the goal pauses. The default budget is 20 continuation turns (`goals.max_turns`). When it runs out, the goal pauses, and `/goal resume` starts a fresh budget. A vague goal gets judged vaguely, so give it a completion contract. Either let Hermes draft one with `/goal draft <text>`, or add lines such as `verify:`, `constraints:`, `boundaries:` and `stop when:` beneath the headline. With a contract, the judge only marks the goal done when there's concrete evidence, such as a passing command or test output. For a mechanical check, add a quality gate with `/goal gate add <command>`. The gate has to exit 0 before the judge is even asked, and a failing gate's output becomes the next instruction. - `/goal status` shows progress, `/goal pause` and `/goal resume` stop and restart the loop, and `/goal clear` drops the goal. - `/subgoal <text>` adds another acceptance criterion partway through without restarting. - If the judge decides the goal can't be achieved, the goal pauses with a reason instead of being marked done. - Anything you type takes priority over the automatic continuation. ### Loops for polling and monitoring `/loop 5m check the deploy status and tell me if it's live yet` runs once straight away, then every five minutes. Leave out the interval and the loop paces itself: it starts at one minute and backs off up to 15 minutes while the replies don't change. A rule of thumb from the docs: use a fixed interval when an outside clock drives the work, and self-pacing when the work sets the rhythm. You can also loop a slash command, for example `/loop 10m /recap`. Always give a loop a way to end. `--times N` caps the number of runs. `--until <condition>` asks the same judge that `/goal` uses whether the condition is met. The agent can also end its reply with `LOOP_COMPLETE`, and `/loop stop` ends it immediately. As a backstop, `loops.max_ticks` (default 100) pauses any loop that runs too long. Each tick is a full agent turn, so match the interval to how often the thing you're watching actually changes. ### How they interact Each session has one loop and one goal. While a goal is actively continuing, loop wakeups wait. They resume when the goal finishes, pauses, or parks on a background process. That makes a parked goal plus a loop a useful pairing: the goal waits on a long CI run while the loop keeps an eye on something else. Both survive `/resume` and context compression. Neither changes the system prompt, so prompt caching keeps working. ### Keeping the judge cheap The judge runs once per turn and is small, about 200 output tokens. By default it uses your main model. To save money, route it to a fast, cheap model under `auxiliary.goal_judge` in `config.yaml`, with a `provider` and `model`. That setting also applies to `/loop --until` conditions. Both commands work in the CLI, the TUI, the desktop app, dashboard chat and messaging platforms. On a messaging platform, the gateway fires loop wakeups between your messages and posts the results as normal replies. ### Related guides - [How to schedule recurring tasks in Hermes Agent](https://hermeswatcher.com/learn/scheduling-with-evidence.md) - [Hermes Agent stuck in a tool loop](https://hermeswatcher.com/troubleshoot/tool-loop-or-stuck-task.md) - [How to keep Hermes Agent costs down](https://hermeswatcher.com/learn/keeping-costs-under-control.md) - [Hermes Agent subagents and delegation explained](https://hermeswatcher.com/learn/subagents-and-delegation.md) ### Related tools - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Build a useful GitHub issue review](https://hermeswatcher.com/workflows/github-issue-review.md) - [Scheduled tasks: automate a proven run](https://hermeswatcher.com/tools/scheduling.md) - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) - [Subagent delegation: split big jobs across parallel child agents](https://hermeswatcher.com/tools/subagent-delegation.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) ### Sources - [Persistent Goals (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/goals) - [Recurring Loops (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/loops) - [Scheduled Tasks (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) - [Kanban (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban) ## Hermes Agent vision: send it screenshots and images > How to attach images in the terminal or from chat apps, how Hermes routes them for vision and text-only models, and the settings that keep image-heavy sessions affordable. URL: https://hermeswatcher.com/learn/vision-and-images Last reviewed: Oct 20, 2026 ### Getting an image into the conversation In the CLI, copy an image and either paste it or type `/paste`. Each attached image shows up as a badge above the input. You can attach several before sending, and `Ctrl+C` clears them. Terminals can't send raw image bytes, so if your clipboard holds only an image and pasting does nothing, use `/paste`, which reads the clipboard directly. Attached images are saved as PNG files under `~/.hermes/images/`. From your phone, just send the photo to your bot on Telegram, Discord, Slack or WhatsApp. These platforms handle the upload themselves, so none of the clipboard limitations below apply. You can also paste an image URL into a message, and the agent can look at it with the `vision_analyze` tool. ### Clipboard setup by platform - macOS: works out of the box using `osascript`. Installing `pngpaste` makes it faster. - Linux on X11: install `xclip`. On Wayland: install `wl-clipboard`. Run `echo $XDG_SESSION_TYPE` to find out which one you're using. - WSL2: no install needed. Hermes reads the Windows clipboard through `powershell.exe`. - Over SSH: clipboard images don't work, because the clipboard tools read the remote machine's clipboard, not yours. Copy the file over with `scp` and reference it by path, use a URL, or send the image through a messaging app. ### Vision models and text-only models You don't need to choose a special model for images to work. If the current model supports vision, Hermes sends the actual pixels. If it doesn't, the image goes through `vision_analyze`, where an auxiliary vision model describes it and the description is added to the conversation. This happens automatically, so you can switch models mid-session without changing how you work. Browser screenshots, computer-use captures and MCP image results all follow the same rule. To override the automatic choice, set `agent.image_input_mode` to `native` (always send pixels), `text` (always send a description) or leave it on `auto`. The documented reason to change it is a backend that accepts text but rejects image input. In that case, keep your main model and point `auxiliary.vision` at a different vision-capable provider and model. In `auto` mode, an explicitly configured `auxiliary.vision` backend already switches images to the description path. ### Keeping image-heavy sessions affordable An image embedded natively is re-sent with every later request in the session, so it keeps costing tokens. Two settings limit that. `vision.embed_target_bytes` (default 256 KB) downscales large images to fit. Raise it, for example to `1048576`, if dense screenshots of tables come back unreadable. `vision.max_calls_per_image` caps how often the same image can be embedded. By default only delegated subagents are capped, at 3, but you can set a number for every session. `vision.replay_recent_images` (default 3) re-sends your most recent images when a session is rebuilt from history, for example after a resume or a gateway restart, so a follow-up question about a photo still sees it. Set it to `0` to turn that off. On the gateway, the stored copy of a chat image is cleaned up after 24 hours, so a question about a photo from yesterday may only see a `[screenshot]` placeholder. Send the image again if it matters. ### A quick checklist when an image is ignored - No badge appeared: use `/paste`, and install `xclip` or `wl-clipboard` on Linux. - Working over SSH: transfer the file, or use a messaging app instead. - The model says it can't see images: check `agent.image_input_mode` and your `auxiliary.vision` settings. - The model only sees an `[image omitted ...]` note for an SVG, BMP or TIFF on a Responses-style backend such as `openai-codex`: those backends accept only JPEG, PNG, GIF and WebP. Hermes converts SVGs to PNG when a rasterizer such as `rsvg-convert` or `cairosvg` is installed. Other formats need converting before you send them. ### Related guides - [How to choose a model for Hermes Agent](https://hermeswatcher.com/learn/models-and-effective-configuration.md) - [How to keep Hermes Agent costs down](https://hermeswatcher.com/learn/keeping-costs-under-control.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) ### Related tools - [Collect content ideas without losing the evidence](https://hermeswatcher.com/workflows/content-research-queue.md) - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) - [Telegram: reach Hermes from a private bot conversation](https://hermeswatcher.com/tools/telegram.md) - [Browser tools: interact with pages when retrieval is insufficient](https://hermeswatcher.com/tools/browser-tools.md) - [Image generation: create images from a text prompt](https://hermeswatcher.com/tools/image-generation.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) ### Sources - [Vision and Image Paste (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/vision) - [Configuration: auxiliary models (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) ## How to set up Hermes Agent on Telegram > Connect Hermes Agent to Telegram: create a bot with Create with QR or BotFather, set your allowlist, start the gateway and chat from your phone. URL: https://hermeswatcher.com/learn/hermes-agent-telegram-setup Last reviewed: Oct 29, 2026 ### What you need Hermes Agent can run as a Telegram bot. Once it is connected, you can chat with your agent from any device, send voice memos for transcription through your configured speech provider, and receive scheduled-task results. It supports text, voice, images and file attachments. Setup has three parts: create a bot, tell Hermes who may use it, and start the messaging gateway. An allowlist is the list of people permitted to use your agent. For background, see [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md). Compare platforms at [messaging platforms](https://hermeswatcher.com/messaging.md). - Hermes Agent installed, with a model provider configured. - A Telegram account. - Your numeric Telegram user ID. This is not your @username. The steps below show how to find it. - A machine that stays on, if the bot should always answer. A laptop works while it is awake. For a bot that stays available, the official team tutorial uses a server or VPS. ### Create the bot The quickest route is the Create with QR button on the Messaging → Telegram page in the Hermes dashboard and the desktop app. Scan the code, or open the link, in Telegram. Hermes creates the bot for you, detects your Telegram user ID, writes `TELEGRAM_BOT_TOKEN` and `TELEGRAM_ALLOWED_USERS` into your profile's `.env`, and restarts the gateway. If you use it, skip ahead to sending your first message. To create the bot yourself, use @BotFather, Telegram's official bot management tool. - Open Telegram and search for @BotFather, or open [BotFather in Telegram](https://t.me/BotFather). - Send `/newbot`. - Choose a display name, for example "Hermes Agent". - Choose a username. It must be unique and end in `bot`, for example `my_hermes_bot`. - BotFather replies with your API token. It looks like `123456789:ABCdefGHIjklMNOpqrSTUvwxYZ`. Keep the token secret. Anyone with it can control your bot. If it leaks, revoke it straight away with `/revoke` in BotFather. ### Connect it to Hermes Hermes uses numeric Telegram user IDs to control access. Message @userinfobot and it replies with your ID, a number like `123456789`. Then run the setup wizard and select Telegram. It asks for your bot token and allowed user IDs, then writes the configuration for you. If you prefer to edit the file yourself, add the two lines shown below to `~/.hermes/.env`. Separate multiple user IDs with commas. Terminal: ``` hermes gateway setup ``` ~/.hermes/.env (manual option): ``` TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ TELEGRAM_ALLOWED_USERS=123456789 ``` The gateway does not execute unknown users' requests without an explicit grant. An allowlisted user, an approved DM pairing or another supported grant can authorize access. An absent allowlist does not revoke an approved pairing. Keep allow-all disabled on a private bot, including `GATEWAY_ALLOW_ALL_USERS`. DM pairing is an alternative to a fixed list. Without a restrictive policy, an unknown DM can receive a one-time code. With an explicit allowlist, current gateway code normally suppresses unsolicited codes unless the platform policy opts into pairing. Approve an issued code on the host with `hermes pairing approve telegram <code>`. Codes expire after one hour. `hermes pairing list` shows pairing state. `hermes pairing revoke telegram <user-id>` removes a pairing grant; also remove any allowlist entry that still grants access. Authorized people can reach this profile's configured tools, including terminal access by default. The allowlist controls who can ask, while tool, approval and sandbox settings control what the agent may do. Review those settings before allowing anyone else. ### Start the gateway and send your first message Run the gateway in the foreground first so you can watch it start. Terminal: ``` hermes gateway ``` With the gateway running, find your bot in Telegram and send a harmless message from your allowed account. Check that its reply reaches that conversation and inspect the gateway output for errors. Press `Ctrl+C` to stop the foreground gateway. `/new` starts a fresh conversation. `/sethome` chooses this chat as the home destination for a bare `telegram` delivery target. Chat-created scheduled jobs default to their origin; CLI-created jobs default to local output. Explicit chat or topic targets select their own destination. See [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md). When the agent wants to run a potentially dangerous command, it asks for approval in the chat. Reply "yes" or "y" to approve, or "no" or "n" to deny. ### What it can do The official comparison table lists voice, images, files, threads, typing and streaming. It leaves reactions unmarked, while the Telegram page describes them. They are off by default; enable them with `telegram.reactions: true` in `config.yaml` or `TELEGRAM_REACTIONS=true`. Voice means notes or spoken replies, not a live call. Voice features depend on your configured speech provider. Local faster-whisper is the normal local transcription engine where supported; native Windows ARM64 and Intel macOS do not receive it. Use a supported hosted or command-based provider there. Voice notes and spoken replies are separate from live voice conversations. ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. Closing the lid usually puts a laptop to sleep, and the bot goes quiet. A foreground gateway stops when you close the terminal. Install it as a background service instead: a user systemd service on Linux, a launchd service on macOS, or a Scheduled Task that runs at logon on Windows. Install the service: ``` hermes gateway install ``` Start it: ``` hermes gateway start ``` Check it: ``` hermes gateway status ``` On a Linux server you never log into, the docs suggest running `sudo loginctl enable-linger $USER` once, so the user service starts at boot and survives logout. For hosting choices, see [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md). For how the gateway handles sessions and platforms, see [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md). When this computer is off, asleep or disconnected, Hermes cannot process messages or run scheduled jobs. A background service does not keep a powered-off host running. On Windows, Task Scheduler watches the launcher rather than later gateway crashes. Check `hermes gateway status` and use `hermes gateway start` if it has stopped. #### Messages sent while the computer was off Telegram drops pending updates on a cold boot by default. Set `platforms.telegram.extra.drop_pending_on_cold_boot: false` in config.yaml to receive that backlog. Old commands can run later, and a crash can repeat an update that was partly processed. Only turn this on if you are happy for old messages to run as tasks later. Optional config.yaml: receive pending updates after a cold boot: ``` platforms: telegram: extra: drop_pending_on_cold_boot: false ``` ### Group chats and permissions Telegram bots have privacy mode turned on by default. With it on, the bot only sees messages that start with a `/` command, replies to its own messages, service messages, and messages in channels where it is an admin. Visibility, authorization and mention rules are separate gates. A message must reach the bot, its sender or group must have an execution grant, and the message must pass any mention filter. Changing privacy mode alone does not grant agent access. - To let the bot see every group message, message @BotFather, send `/mybots`, select your bot, then go to Bot Settings → Group Privacy → Turn off. - After changing privacy, remove the bot from the group and add it again. Telegram keeps the old setting until you do. - Instead of turning privacy off, you can promote the bot to group admin. Admin bots receive all messages. - `TELEGRAM_ALLOWED_USERS` grants sender access in DMs and groups. It is one option alongside approved pairing and the group grants below. - `TELEGRAM_GROUP_ALLOWED_USERS` lets listed people use the bot in groups without giving them DM access. A chat ID in `TELEGRAM_GROUP_ALLOWED_CHATS` authorizes every member of that group. Group chat IDs are negative numbers. - Set `telegram.require_mention: true` so the bot only answers replies to it, @mentions and commands addressed to it. If it is unset, the bot responds to normal group messages it can see. ### If it doesn't answer Most setup issues come down to the token, the allowlist or privacy mode. For a wider checklist, see [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md). - Bot not responding at all: check that `TELEGRAM_BOT_TOKEN` is correct and read the `hermes gateway` logs for errors. - Bot ignores you, or replies "unauthorized": your user ID is probably not in `TELEGRAM_ALLOWED_USERS`. With an allowlist set, Hermes normally stays silent to unknown users. Check the number with @userinfobot. - Bot ignores group messages: privacy mode is probably on. Turn it off or make the bot an admin, then remove and re-add it. - Token revoked or invalid: get a new one in BotFather with `/revoke`, then `/newbot` or `/token`, and update your `.env` file. ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes Telegram docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) - [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md) ### Related tools - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Telegram: reach Hermes from a private bot conversation](https://hermeswatcher.com/tools/telegram.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) - [Scheduled tasks: automate a proven run](https://hermeswatcher.com/tools/scheduling.md) ### Sources - [Telegram](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram) - [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) - [Tutorial: Team Telegram Assistant](https://hermes-agent.nousresearch.com/docs/guides/team-telegram-assistant) - [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) - [Gateway authorization and pairing policy (pinned source)](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L653-L773) - [Scheduled delivery defaults](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) - [Voice mode and speech-provider requirements](https://hermes-agent.nousresearch.com/docs/user-guide/features/voice-mode) ## How to set up Hermes Agent on Discord > Connect Hermes Agent to Discord: create a bot, turn on Message Content Intent, invite it, set your allowlist and start the gateway. URL: https://hermeswatcher.com/learn/hermes-agent-discord-setup Last reviewed: Oct 29, 2026 ### What you need Hermes Agent can run as a Discord bot, so you can chat with your agent in direct messages or server channels. It supports text, voice messages, file attachments and slash commands. Authorized DMs need no @mention. Server channels normally require an @mention, and every request must still pass the access policy. For background, see [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md). Compare interfaces at [messaging platforms](https://hermeswatcher.com/messaging.md). - Hermes Agent installed, with a model provider configured. - A Discord account, and access to the Discord Developer Portal. - The Manage Server permission on the server you want to add the bot to. - Your numeric Discord user ID. The steps below show how to find it. ### Create the bot and invite it Everything here happens in the [Discord Developer Portal](https://discord.com/developers/applications). - Click New Application, enter a name such as "Hermes Agent", accept the Developer Terms of Service and click Create. Note the Application ID on the General Information page. - Click Bot in the left sidebar. Under Authorization Flow, set Public Bot to ON. This lets anyone with the invite link add it to a server, while the Hermes allowlist still decides who can use the agent. To stop others adding it, leave Public Bot OFF and use the manual invite link below. Leave Require OAuth2 Code Grant OFF in either case. - Under Privileged Gateway Intents, enable Message Content Intent. Enable Server Members Intent when using username or role allowlists; numeric user-ID-only authorization does not itself require it. Presence Intent is optional. Save Changes. - Under Token, click Reset Token and copy the token. Discord shows it only once. - Click Installation. Under Installation Contexts, enable Guild Install. Set Install Link to Discord Provided Link. Under Default Install Settings, select the scopes `bot` and `applications.commands` and the permissions you need. - Open the invite link, pick your server in the Add to Server dropdown, click Continue, then Authorize. Manual invite URL (replace YOUR_APP_ID): ``` https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=309237763136 ``` Message Content Intent is easy to miss. Hermes always asks Discord for message content, so if the intent is off, Discord refuses the connection and the bot never comes online. If you keep the bot private (Public Bot OFF), use the manual URL above instead of the Installation tab. Its permissions number is the docs' recommended set. Never share the token or commit it to Git. Anyone with it has full control of your bot. The bot shows as offline in your server until you start the gateway. Keep the recommended manual invite permission integer `309237763136`. The setup wizard prints `309240908864` when requesting Connect and Speak for voice channels. Invite permissions and Gateway Intents are separate controls. ### Connect it to Hermes To find your user ID, open Discord, go to Settings → Advanced and turn Developer Mode ON. Then right-click your own username and choose Copy User ID. It is a long number like `284102345871466496`. Run the setup wizard, select Discord and paste your bot token. The wizard checks the token with Discord, checks the privileged intents, prints the invite link and offers to allowlist you as the bot's owner. To configure it by hand instead, add the lines below to `~/.hermes/.env`. Separate multiple user IDs with commas. Terminal: ``` hermes gateway setup ``` ~/.hermes/.env (manual option): ``` DISCORD_BOT_TOKEN=your-bot-token DISCORD_ALLOWED_USERS=284102345871466496 ``` Only authorize people you trust. An allowlist, an approved pairing or another supported explicit grant can authorize agent work. An allowlist is the list of permitted users, roles or chats. `DISCORD_ALLOWED_CHANNELS` can scope access to whole channels, so consider who can post there. Keep allow-all disabled on a private bot. Authorized users can use the profile's configured tools, including terminal and file access, subject to its security settings. For servers where access follows roles, set `DISCORD_ALLOWED_ROLES` to a comma-separated list of role IDs. Anyone with one of those roles is authorized, alongside the user list. New DM pairing codes are not promised when a restrictive policy or explicit allowlist is set. Inspect the gateway log and `hermes pairing list` rather than widening access to diagnose silence. ### Start the gateway and send your first message Start the gateway in the foreground first so you can watch it connect. Terminal: ``` hermes gateway ``` With the gateway running, send a harmless DM from an authorized account, or @mention it in a channel it can see. Check that the reply reaches that conversation and inspect the gateway output for errors. Use `/sethome` in a supported channel to choose the home destination for a bare `discord` delivery target. Chat-created scheduled jobs default to their origin, CLI-created jobs to local output, and explicit targets select their own channel. See [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md). ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. A foreground gateway stops when you close the terminal. Install it as a background service instead. The docs describe a user systemd service on Linux, a launchd service on macOS, and a Scheduled Task that runs at logon on Windows. Install the service: ``` hermes gateway install ``` Start it: ``` hermes gateway start ``` Restart after changing settings: ``` hermes gateway restart ``` Check the running service: ``` hermes gateway status ``` For hosting choices, see [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md). For how the gateway handles sessions and platforms, see [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md). If the host is off, asleep or offline, the bot cannot answer and scheduled jobs cannot run. Windows Task Scheduler watches the launcher, not later gateway crashes. Check the actual running state and use `hermes gateway start` if it has stopped. ### Servers, channels and permissions - Mentions: `DISCORD_REQUIRE_MENTION` defaults to `true` for server channels. Authorized DMs need no mention, but must still pass the access policy. - Mention-free channels: list IDs in `DISCORD_FREE_RESPONSE_CHANNELS` to remove the tagging requirement. This changes triggers, not authorization. Replies stay inline by default in these channels. - Threads: `DISCORD_AUTO_THREAD` defaults to `true` for top-level mentions in text channels. Mention-free channels skip auto-threading by default; `discord.free_response_auto_thread: true` enables it there. Existing threads keep their own session history. - Shared channels: each user gets their own session inside a channel by default (`group_sessions_per_user: true`), so two people in one channel do not share a transcript. - Channel limits: `DISCORD_ALLOWED_CHANNELS` restricts the bot to listed channels. `DISCORD_IGNORED_CHANNELS` lists channels where it never responds. ### If it doesn't answer Most Discord issues come from intents, the access policy or channel permissions. For a wider checklist, see [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md). - Bot stays offline and the log mentions privileged intents: enable Message Content Intent and Save Changes. Enable Server Members Intent if you use username or role allowlists. Then run `hermes gateway restart`. - Bot is online but silent: inspect the gateway log for an access-policy error, then check the allowed user, role or channel and approved pairings. For a private numeric-ID setup, add your own `DISCORD_ALLOWED_USERS` value and restart. - Bot is offline: check that `hermes gateway` is running and that `DISCORD_BOT_TOKEN` is correct. If you reset the token, update it. - Bot ignores you: check the access policy first, then channel visibility and mention rules. An allowlist entry, approved pairing or supported role/channel grant must admit the request. - Bot cannot see one channel: in that channel's Permissions, give the bot's role View Channel and Read Message History. - 403 Forbidden errors: re-invite the bot with the correct permissions, or adjust its role in Server Settings → Roles. ### What it can do The overview lists voice, images, files, threads, reactions, typing and streaming for Discord. Actual media and speech use still depends on the configured model, providers and permissions. Voice-message transcription and spoken replies are distinct from joining a live Discord voice channel. Local faster-whisper is the normal local transcription engine where supported. Native Windows ARM64 and Intel macOS need a supported hosted or command-based provider instead. Live voice additionally needs the documented voice dependencies and Connect/Speak permissions. ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes Discord docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) - [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md) ### Related tools - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Discord: keep agent conversation scoped to the right people](https://hermeswatcher.com/tools/discord.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) ### Sources - [Discord](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord) - [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) - [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) - [Gateway authorization and pairing policy (pinned source)](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L653-L773) - [Scheduled delivery defaults](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) - [Voice mode and speech-provider requirements](https://hermes-agent.nousresearch.com/docs/user-guide/features/voice-mode) ## How to set up Hermes Agent on WhatsApp with the Baileys bridge > Connect Hermes Agent to WhatsApp: link a number with a QR code, set your allowlist, start the gateway and message your agent from your phone. URL: https://hermeswatcher.com/learn/hermes-agent-whatsapp-setup Last reviewed: Oct 29, 2026 ### What you need Hermes Agent can connect to WhatsApp so you can message your agent from your phone. It uses a built-in bridge based on Baileys, which emulates a WhatsApp Web session. It does not use the official WhatsApp Business API, so no Meta developer account or Business verification is needed. The official docs warn that this unofficial bridge carries a risk of account restrictions. Use a dedicated number to isolate that risk from your personal account. Business users should read [How to set up Hermes Agent on WhatsApp with the Business Cloud API](https://hermeswatcher.com/learn/hermes-agent-whatsapp-business-cloud-api-setup.md) for the separate Meta-supported integration, which needs a business account and a public webhook. A webhook is an HTTP callback carrying an event from another service. This guide covers the Baileys bridge. Compare routes at [messaging platforms](https://hermeswatcher.com/messaging.md). - Hermes Agent installed, with a model provider configured. - Node.js v18 or newer and npm. The bridge runs as a Node.js process. - A phone with WhatsApp installed, to scan the QR code. - A dedicated phone number for the bot, rather than your personal number, to isolate account-restriction risk. ### Choose a mode and a number There are two modes. Bot mode is recommended: give the bot its own phone number and message that number. Self-chat mode links your own WhatsApp so you can message yourself. That also exposes your personal account to the bridge's restriction risk, so the dedicated-number recommendation still matters. For bot mode, use a dedicated number you control and can keep active. Register it with WhatsApp before linking the bridge. Check current acceptance and inactivity rules with WhatsApp and the number provider. - The Hermes docs list Google Voice, prepaid SIM and VoIP possibilities. Acceptance of a particular number is not established by this guide. - Carrier costs and number-expiry rules vary. Do not rely on a blanket 90-day call rule or an assumption that a number is free or accepted. Install WhatsApp on a phone and register the new number. To lower the ban risk, keep usage conversational, avoid bulk messages, and do not automate outbound messages to people who have not messaged first. ### Connect it to Hermes Run the WhatsApp wizard. It asks for bot or self-chat mode and which phone numbers may message the bot, installs bridge dependencies if needed, then shows a QR code. At the allowed-numbers prompt, enter specific numbers with country code and no `+`. Do not enter `*` or leave it blank. You can also run `hermes gateway setup` and pick WhatsApp for a guided walk-through. Terminal: ``` hermes whatsapp ``` On the phone, open WhatsApp, go to Settings → Linked Devices, tap Link a Device and point the camera at the QR code. The wizard confirms the connection and saves the session. If the code looks garbled, make your terminal at least 60 columns wide. The wizard saves these settings to `~/.hermes/.env`. Open the file and confirm they match the example below. Phone numbers include the country code, with no `+`. Separate several numbers with commas. ### Set access and start the gateway ~/.hermes/.env: ``` WHATSAPP_ENABLED=true WHATSAPP_MODE=bot WHATSAPP_ALLOWED_USERS=15551234567 ``` ~/.hermes/config.yaml, silence unknown DMs: ``` whatsapp: unauthorized_dm_behavior: ignore ``` Terminal: ``` hermes gateway ``` An allowlist is the list of people permitted to use the agent. Put specific phone numbers in `WHATSAPP_ALLOWED_USERS` and keep allow-all disabled on a private bot. Unknown requests cannot run agent work without an explicit grant. Approved pairing can also grant access; an empty allowlist does not revoke it. `WHATSAPP_ALLOWED_USERS=*` and `WHATSAPP_ALLOW_ALL_USERS=true` widen access. By default, WhatsApp still answers unknown DMs with a pairing code, even when `WHATSAPP_ALLOWED_USERS` is set. For a private number, add the YAML shown above to `~/.hermes/config.yaml` so strangers get no reply. A code grants nothing until you approve it. Check the sender before running `hermes pairing approve whatsapp <code>`. The gateway starts the WhatsApp bridge automatically using the saved session. Send a message to the bot number from an allowed phone, or message yourself in self-chat mode. Replies carry a "☤ Hermes Agent" header by default, and you can change or remove it with `whatsapp.reply_prefix` in `config.yaml`. ### What it can do The overview table lists images, files, typing and streaming for the bridge, but leaves voice unmarked. The WhatsApp and voice documentation describe voice-note paths. Transcription and spoken replies depend on configured speech providers. These are voice notes, not a live voice call. Local faster-whisper is the normal local transcription engine where supported. Native Windows ARM64 and Intel macOS need a supported hosted or command-based provider instead. - Text, images and file attachments are documented. Bridge media handling and WhatsApp protocol changes can affect delivery. - Groups use the separate group policy described below. The overview does not mark threads or reactions as supported for the bridge. ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. A foreground gateway stops when you close the terminal. Install it as a service so it keeps running in the background. Install as a user service: ``` hermes gateway install ``` Linux only: boot-time system service: ``` sudo hermes gateway install --system ``` Start the installed service: ``` hermes gateway start ``` Check the running service: ``` hermes gateway status ``` The session is saved under `~/.hermes/platforms/whatsapp/session`, so you do not need to scan the QR code after every restart. That folder holds full session credentials. Protect it like a password and never share or commit it. The gateway reconnects after short network blips on its own. If the session breaks, for example after a phone reset or a WhatsApp update, run `hermes whatsapp` again and scan a fresh code. For hosting choices, see [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md). For how the gateway handles sessions and platforms, see [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md). Service installation alone does not prove delivery. Send a harmless message from an allowed phone and check its reply. Both the Hermes host and bridge must remain available. If the computer is off, asleep or disconnected, the agent cannot answer or run jobs. Windows Task Scheduler does not supervise later gateway crashes; check status and start the gateway if needed. On Unix-like hosts, the docs recommend `chmod 700 ~/.hermes/platforms/whatsapp/session`. If the session leaks, unlink the device in WhatsApp under Settings → Linked Devices. ### Group chats and permissions In bot mode, groups follow a group policy, not the DM allowlist. The default policy, `pairing`, forwards nothing from groups. - `allowlist` admits only the groups listed in `WHATSAPP_GROUP_ALLOWED_USERS`, as group JIDs such as `120363001234567890@g.us`. - `open` admits every group the bot is a member of. - Set the policy with `WHATSAPP_GROUP_POLICY` or `whatsapp.group_policy`. - If `WHATSAPP_ALLOWED_USERS` is set, each group participant must also be on it, or paired. - The bot answers every admitted group message by default. Set `WHATSAPP_REQUIRE_MENTION=true` to answer only @mentions, replies to the bot and `/commands`. ### If it doesn't answer For a wider checklist, see [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md). - QR code not scanning: widen the terminal to 60 or more columns, try another terminal, and scan from the bot number's WhatsApp, not your personal one. - QR code expired: codes refresh about every 20 seconds. Run `hermes whatsapp` again. - Messages not received: check that `WHATSAPP_ALLOWED_USERS` has the sender's number with country code and no `+` or spaces. Set `WHATSAPP_DEBUG=true` in `.env` and restart the gateway to see raw events in `bridge.log`. - Logged out unexpectedly: WhatsApp unlinks devices after long inactivity. Keep the phone on and online, then re-pair with `hermes whatsapp`. - Stopped working after a WhatsApp update: update Hermes to get the latest bridge, then re-pair. - macOS says Node.js is not installed: run `hermes gateway install` to refresh the service PATH, then `hermes gateway start`. ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes WhatsApp with the Baileys bridge docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [How to set up Hermes Agent on WhatsApp with the Business Cloud API](https://hermeswatcher.com/learn/hermes-agent-whatsapp-business-cloud-api-setup.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) ### Related tools - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [WhatsApp: chat with Hermes from your phone](https://hermeswatcher.com/tools/whatsapp.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) ### Sources - [WhatsApp](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp) - [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) - [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) - [Gateway authorization and pairing policy (pinned source)](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L653-L773) - [WhatsApp Business Cloud API](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp-cloud) - [Voice mode](https://hermes-agent.nousresearch.com/docs/user-guide/features/voice-mode) - [hermes_cli/main_platform_setup.py](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/hermes_cli/main_platform_setup.py) ## How to set up Hermes Agent on Slack > Create a Slack app from the Hermes manifest, save both tokens, restrict access and start the gateway for DMs, channels and threads. URL: https://hermeswatcher.com/learn/hermes-agent-slack-setup Last reviewed: Oct 29, 2026 ### What you need Hermes connects to Slack through Socket Mode, an outbound WebSocket connection that stays open to receive events. You do not need a public URL or tunnel for this route. - Hermes Agent installed with a model provider configured. Start with [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) if the gateway is new to you. - A Slack workspace where you may create and install an app. Ask the workspace administrator if app installation is restricted. - Two different secrets: a bot token beginning `xoxb-` and an app-level token beginning `xapp-`. You will also need your Slack Member ID. - A computer that stays on and connected whenever you want the bot to answer. ### Create the Slack app A manifest is a configuration file that declares the app permissions, events and commands. The official Hermes docs recommend generating one with Agent view for a new app: Terminal: ``` hermes slack manifest --agent-view --write ``` Open the generated `slack-manifest.json` in your Hermes home (`~/.hermes/` on Linux, macOS and WSL). At [Slack app management](https://api.slack.com/apps), choose Create New App, then From an app manifest. Select your workspace, paste the JSON, review the requested configuration and create the app. [Slack manifest instructions](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/) describe this flow. The Hermes manifest supplies the scopes, event subscriptions and slash commands. Continue with the token and Messages Tab checks below even when you use the manifest. The manifest does not generate the app-level `xapp-` token; create it in the next step. ### Get both tokens and enable messages - In Settings → Socket Mode, confirm Enable Socket Mode is on. Under Settings → Basic Information → App-Level Tokens, create a token with connections:write. Copy its `xapp-` value for `SLACK_APP_TOKEN`. - In Features → App Home → Show Tabs, enable Messages Tab and allow users to send slash commands and messages from that tab. Slack otherwise blocks DMs to the app. - In Settings → Install App, choose Install to Workspace. Review the permissions and authorize the installation. Copy the Bot User OAuth Token beginning `xoxb-` for `SLACK_BOT_TOKEN`. Slack also exposes installation under OAuth & Permissions. - Keep both tokens secret. Store them in your private profile configuration, never in a shared screenshot or Git repository. The Hermes docs recommend file permissions 600 on Unix and rotating tokens in Slack app settings. [Slack Socket Mode instructions](https://docs.slack.dev/tools/python-slack-sdk/socket-mode/) confirm that the app-level token and bot token have different jobs. Do not substitute one for the other. ### Choose who can talk to it Find your own Member ID in Slack: open your full profile, open the more menu and choose Copy member ID. It looks like U01ABC2DEF3, rather than a display name. Repeat for each authorized person. An allowlist is the list of people permitted to use the agent. Authorize only people you trust with its enabled tools and files. Keep `GATEWAY_ALLOW_ALL_USERS` unset or false and review existing global allowlists and pairing approvals, which can also grant access. Do not expect an unknown sender to receive a pairing code when an allowlist is set. For a shared workspace, `SLACK_ALLOWED_CHANNELS` can also restrict conversations by channel ID. This is separate from sender authorization. The docs list IDs beginning C, G or D; inspect the channel details to get the actual ID. Keep your intended test conversation in the permitted set. ### Connect it to Hermes Run the setup wizard and select Slack. Supply the two tokens and allowed Member IDs. For manual configuration, the official docs give these environment variables. The platform docs use `~/.hermes/.env` for the default profile on Linux, macOS and WSL. Native Windows normally uses `%LOCALAPPDATA%\hermes\.env`. If you use a custom Hermes home or another profile, edit that profile's file instead. Replace every example value before starting. Setup wizard: ``` hermes gateway setup ``` Profile .env, manual alternative: ``` SLACK_BOT_TOKEN=xoxb-your-bot-token-here SLACK_APP_TOKEN=xapp-your-app-token-here SLACK_ALLOWED_USERS=U01ABC2DEF3 ``` Separate multiple allowed Member IDs with commas. Keep the tokens out of the public Slack channel. Restart an existing gateway after changing its credentials. For scheduled delivery, the optional `SLACK_HOME_CHANNEL` holds the destination channel ID. Invite the bot there before using it. The channel name alone is not the ID. ### Start the gateway and send your first message Start in a terminal so you can read connection and authorization errors. Then open a DM with the installed app and send a short message such as Hello. Foreground gateway: ``` hermes gateway ``` In each Slack channel you want to use: ``` /invite @Hermes Agent ``` Use your bot's name in the invitation. Hermes does not automatically join channels. After inviting it, send an @mention in that channel. For an authorized sender, 1:1 DMs do not need a mention. Channels normally need an @mention to start a conversation. Follow-ups in a thread the bot has joined can continue without another mention. Group DMs use shared-conversation controls rather than the 1:1 DM exemption. Confirm the response in Slack, then try a thread reply and a small non-sensitive attachment. ### What it can do - The official comparison table lists voice, images, files, threads, reactions, typing indicators and streaming updates for Slack. - Incoming audio uses your configured speech-to-text provider. Text-to-speech replies arrive as audio file attachments. Voice requires the relevant speech services to be configured. - Reading uploads needs files:read; uploading files needs files:write. Channel history and event subscriptions determine which messages reach the bot. - Native streaming and custom working-state text depend on Slack app features and assistant:write. The docs describe fallback to edit-based updates when native streaming is unavailable. - Messages from other bots are ignored by default. Keep that default for an initial setup. Enabling unrestricted bot replies can create loops. - Reaction-triggered agent turns are optional and need additional scopes and events. A reaction appearing in Slack does not by itself mean it starts an agent task. ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. After your first message succeeds, stop the foreground gateway with Ctrl+C. For a normal host installation, the official gateway docs give these service commands: Install, start and inspect the host service: ``` hermes gateway install hermes gateway start hermes gateway status ``` Linux uses systemd, macOS uses launchd, and Windows uses a Scheduled Task at logon. On a headless Linux host using a user service, the docs give `sudo loginctl enable-linger $USER` to keep it available after logout. Windows Task Scheduler does not restart a gateway that crashes after its launcher exits. In a container, use the documented container startup and restart policy instead of installing a host user service. For hosting choices, see [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md). ### If it doesn't answer - No DM reply: check message.im in Event Subscriptions, the Messages Tab setting, both tokens and your allowed Member ID. Read the gateway logs for invalid_auth or not_authed. - DM works but channel messages do not: confirm the invitation, app_mention, message.channels and channels:history. Private channels also need message.groups and groups:history. - Group DM is silent: check message.mpim, mpim:history and mpim:read, plus the shared-conversation mention and channel restrictions. - Uploads cannot be read: check files:read. A successful text reply does not establish attachment access. - After changing scopes or event subscriptions, reinstall the app to the workspace. Then restart the gateway if you changed its configuration. - If the connection drops, inspect the computer's network connection. For more checks, see [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md). ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes Slack docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/slack) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [How to set up Hermes Agent on Microsoft Teams](https://hermeswatcher.com/learn/hermes-agent-microsoft-teams-setup.md) - [How to set up Hermes Agent on Google Chat](https://hermeswatcher.com/learn/hermes-agent-google-chat-setup.md) - [How to set up Hermes Agent on Matrix](https://hermeswatcher.com/learn/hermes-agent-matrix-setup.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) ### Related tools - [Slack: bring Hermes into your team workspace](https://hermeswatcher.com/tools/slack.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) ### Sources - [Hermes Agent: Slack](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/slack) - [Slack: configure apps with manifests](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/) - [Slack: Socket Mode client](https://docs.slack.dev/tools/python-slack-sdk/socket-mode/) - [Messaging gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) - [Gateway authorization source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L660-L772) - [Native Windows settings paths](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native) ## How to set up Hermes Agent on Microsoft Teams > Register a Teams bot, connect its HTTPS webhook to Hermes, restrict access by user ID and send a first direct message. URL: https://hermeswatcher.com/learn/hermes-agent-microsoft-teams-setup Last reviewed: Oct 29, 2026 ### What you need Teams sends messages to Hermes through a webhook, a URL that receives event requests. It needs a public HTTPS URL: an internet-reachable address with an encrypted connection. A local-only address is insufficient. - Hermes Agent installed with a model provider configured. - A Microsoft 365 account in a tenant that allows custom app upload. A tenant is your organization's Microsoft environment. An administrator may need to enable this permission. - Node.js and npm to install the Teams CLI. The Microsoft registration quickstart lists Node.js 22.12 or later. - A public HTTPS endpoint, or a development tunnel forwarding to the local Hermes HTTP port 3978. A tunnel gives a local service a public address. - A computer that remains on, plus the Teams client where you will install the app. This guide covers normal bot conversations. The separate [Microsoft Teams Meetings workflow](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/teams-meetings) requires additional setup. ### Ask your Microsoft 365 admin for - Permission to upload custom apps in your organization. - Depending on your organization's policies, you may also need approval to register apps and to use Dev Tunnels. ### Install the Teams CLI and sign in The official Hermes page uses the preview CLI command below. The current [Microsoft registration quickstart](https://learn.microsoft.com/en-us/microsoftteams/platform/teams-sdk/get-started/quickstart-register) instead shows `npm install -g @microsoft/teams.cli`. Microsoft's page installs the standard release. The Hermes docs use the `@preview` release, so use the Hermes command below. Hermes-documented Teams CLI setup: ``` npm install -g @microsoft/teams.cli@preview teams login teams status --verbose ``` Sign in to the intended Microsoft 365 organization. Check that custom app upload is enabled. Record your AAD object ID (your Microsoft Entra ID user ID, formerly Azure Active Directory) from the verbose status output. You will put it in the allowlist. This is your account's directory ID, not its email address. Hermes supplies the bot runtime. Do not scaffold or run the separate Microsoft echo-bot project as part of this connection. ### Expose the local webhook For local development, install and sign in to Microsoft Dev Tunnels. Microsoft documents the Windows install command below; its tunnel guide also lists installation for macOS and Linux. Then create and host the named tunnel using the commands from the Hermes page. Named profile: when one gateway serves several profiles (the default), a secondary profile's Teams endpoint is `https://<your-host>/p/<profile>/api/messages` on the default profile's shared API-server listener, not port 3978. Register the exact URL logged at startup and point the tunnel at that shared listener's port. The unprefixed examples below are for the default profile. Windows, if Dev Tunnels is not installed: ``` winget install Microsoft.devtunnel ``` Sign in to Dev Tunnels: ``` devtunnel user login ``` Create and host the tunnel: ``` devtunnel create hermes-bot --allow-anonymous devtunnel port create hermes-bot -p 3978 --protocol http devtunnel host hermes-bot ``` Leave the hosting terminal open and copy the printed HTTPS address. Anonymous tunnel access lets Teams reach the webhook; it does not authorize people to operate Hermes. Keep bot request authentication and the user allowlist in place. HTTPS ends at the tunnel. It must forward plain HTTP to the local Hermes listener. If you change `TEAMS_PORT`, use that port in the tunnel too. See [Microsoft tunnel instructions](https://learn.microsoft.com/en-us/microsoftteams/platform/teams-sdk/developer-tools/local-tunnels). The documented Teams listener binds all interfaces (IPv4 and IPv6) on port 3978, rather than loopback only. Block direct public access to port 3978 with your firewall and let only your reverse proxy or tunnel reach it. ### Create the Teams app With the tunnel running, register the bot using the official Hermes command. Replace the URL placeholder with your actual tunnel hostname. Keep /api/messages at the end. Terminal, Bash line continuation: ``` teams app create \ --name "Hermes" \ --endpoint "https://<your-tunnel-url>/api/messages" ``` Save the reported `CLIENT_ID`, `CLIENT_SECRET`, `TENANT_ID`, Teams App ID and installation link. The Hermes docs say the client secret is not shown again. Keep the secret private. The Microsoft quickstart also documents writing registration credentials into an environment file. Hermes uses the TEAMS_ names in the next step, so do not assume the unprefixed CLI names configure Hermes automatically. In PowerShell, put the command on one line or use a backtick for line continuation. ### Choose who can talk to it and connect Hermes Run `hermes gateway setup` and select Microsoft Teams for the guided route. For manual setup, add the following values to your active profile .env. The platform docs use `~/.hermes/.env` for the default profile on Linux, macOS and WSL. Native Windows normally uses `%LOCALAPPDATA%\hermes\.env`. If you use a custom Hermes home or another profile, edit that profile's file instead. Replace every example value before starting. Set `TEAMS_ALLOWED_USERS` to your own AAD object ID first. Separate additional authorized IDs with commas. An allowlist is the list of people permitted to use the agent. Authorize only people you trust with its enabled tools and files. Keep `GATEWAY_ALLOW_ALL_USERS` unset or false and `TEAMS_ALLOW_ALL_USERS` unset or false and review existing global allowlists and pairing approvals, which can also grant access. Do not expect an unknown sender to receive a pairing code when an allowlist is set. Setup wizard: ``` hermes gateway setup ``` Profile .env, manual alternative: ``` TEAMS_CLIENT_ID=<your-client-id> TEAMS_CLIENT_SECRET=<your-client-secret> TEAMS_TENANT_ID=<your-tenant-id> TEAMS_ALLOWED_USERS=<your-aad-object-id> ## Optional; official default false. Set true once the app manifest grants message-read RSC permissions. TEAMS_REQUIRE_MENTION=true ``` Keep `TEAMS_CLIENT_SECRET` out of repositories, shared chats and logs. The Hermes docs recommend private .env permissions and secret rotation. With `TEAMS_REQUIRE_MENTION=true`, the bot answers in channels and group chats only when someone @mentions it or replies to it. This matters only once the app's manifest grants resource-specific consent (RSC) to read messages (`ChannelMessage.Read.Group` or `ChatMessage.Read.Chat`), which makes Teams deliver every message in the conversation. The mention setting is a trigger rule, not a replacement for sender authorization. Personal DMs are mention-exempt. ### Start the gateway and install the app in Teams Start the gateway in the foreground. In another terminal, use the health check if you need to inspect the listener. Foreground gateway: ``` hermes gateway ``` Local listener check: ``` curl http://localhost:3978/health ``` Recover the installation link if needed: ``` teams app get <teamsAppId> --install-link ``` The official docs show ok as the health response and a log entry for a listener on port 3978 at /api/messages. A health response alone does not show that Teams can reach it. Open the installation link while signed into the intended Teams account, then add the app. Replace <teamsAppId> with the Teams App ID from registration if you need to retrieve the link. Send Hello in a personal DM from your allowed account. Then try an @mention in a group or channel where the app is installed. Inspect both the Teams response and gateway logs before treating the connection as ready. ### Only if the Teams SDK is missing Skip this unless the gateway log says the Teams SDK is missing. The docs say the gateway can request it on first start. For a source or local installation missing the Teams SDK, the official page gives this dependency command. Use a PM-prepared source checkout, as described in the [package-management workflow](https://hermes-agent.nousresearch.com/docs/reference/package-management#developer-workflow). PM is the Hermes package manager. Do not run the command in an unrelated system Python. Activated Hermes source checkout: ``` python -c "import pm; pm.sync_venv(['teams'], explicit=True)" ``` After it completes, reactivate the same checkout and restart Hermes so it uses the prepared environment. The docs say the gateway can request the optional extra on first startup when policy permits. This command is a recovery path for a missing dependency, not a separate bot runtime. ### What it can do - The official comparison table lists images, threads and a typing indicator for Teams. It does not list voice, general file attachments, emoji reactions or streaming updates for this adapter. Do not assume every attachment type is supported. - Personal chats do not need mentions. Group and channel conversations use mentions unless message-read consent and configured trigger rules broaden intake. - Potentially dangerous commands can produce an Adaptive Card with Allow Once, Allow Session, Always Allow and Deny. Choose the narrowest approval that fits the task; Always Allow persists the pattern. - Meeting transcript summaries are a separate workflow. Configuring this conversational bot does not subscribe it to Microsoft Graph meeting events. ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. After your first message succeeds, stop the foreground gateway with Ctrl+C. For a normal host installation, the official gateway docs give these service commands: Install, start and inspect the host service: ``` hermes gateway install hermes gateway start hermes gateway status ``` Linux uses systemd, macOS uses launchd, and Windows uses a Scheduled Task at logon. On a headless Linux host using a user service, the docs give `sudo loginctl enable-linger $USER` to keep it available after logout. Windows Task Scheduler does not restart a gateway that crashes after its launcher exits. In a container, use the documented container startup and restart policy instead of installing a host user service. For hosting choices, see [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md). #### Keep the public endpoint available A running gateway service does not keep a development tunnel alive. If the tunnel stops, Teams cannot deliver messages even while the local health check answers. If its URL changes, update the app endpoint. For a permanent host, the Hermes docs describe a reverse proxy with a valid public TLS certificate, forwarding to plain HTTP at 127.0.0.1:3978. A reverse proxy accepts public requests and forwards them to the local listener. Block direct public access to port 3978 with your firewall; let only the proxy or tunnel reach it. If you move to a permanent domain, update the registered endpoint (replace both placeholders): ``` teams app update --id <teamsAppId> --endpoint "https://your-domain.com/api/messages" ``` Use an endpoint you control. The official docs say Teams rejects self-signed certificates. See [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md) for host choices. ### If it doesn't answer - Cannot install the app: check the signed-in tenant and whether custom app upload is enabled. - Local health check works but Teams is silent: check the tunnel process and the registered HTTPS URL, including /api/messages. - Logs show UNKNOWN / HTTP/1.0 with a 400 response: the tunnel may be forwarding HTTPS to the plain HTTP listener. Forward HTTP on the local port. - Authentication errors: check all three TEAMS_ credentials and that the tenant matches your login. Missing model configuration is a separate error. - Messages arrive but are ignored: compare your AAD object ID with `TEAMS_ALLOWED_USERS` and check mention rules. - Missing Teams SDK or adapter: use the PM dependency step, reactivate the environment and restart the gateway. Read detailed service logs with `hermes gateway status -l`. - For the broader checklist, see [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md). ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes Microsoft Teams docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/teams) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [How to set up Hermes Agent on Slack](https://hermeswatcher.com/learn/hermes-agent-slack-setup.md) - [How to set up Hermes Agent on Google Chat](https://hermeswatcher.com/learn/hermes-agent-google-chat-setup.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) ### Related tools - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) ### Sources - [Hermes Agent: Microsoft Teams](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/teams) - [Microsoft: register your app](https://learn.microsoft.com/en-us/microsoftteams/platform/teams-sdk/get-started/quickstart-register) - [Microsoft: local tunnels](https://learn.microsoft.com/en-us/microsoftteams/platform/teams-sdk/developer-tools/local-tunnels) - [Package management: source checkout workflow](https://hermes-agent.nousresearch.com/docs/reference/package-management#developer-workflow) - [Messaging gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) - [Gateway authorization source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L660-L772) - [Native Windows settings paths](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native) - [website/docs/user-guide/multi-profile-gateways.md](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/website/docs/user-guide/multi-profile-gateways.md) ## How to set up Hermes Agent on Google Chat > Connect Hermes through a Google Chat app and Pub/Sub pull subscription, restrict users and optionally enable native file uploads. URL: https://hermeswatcher.com/learn/hermes-agent-google-chat-setup Last reviewed: Oct 29, 2026 ### What you need Hermes receives Google Chat events through a Pub/Sub pull subscription and sends replies through the Chat API. Pub/Sub is the Google message queue; pull means Hermes connects out to collect events. This documented route needs no public callback URL or tunnel. Native Windows on ARM64 is not supported: the Google Chat dependency (google-cloud-pubsub/grpcio) has no build for that platform. If you enable optional file access, complete the [Google OAuth consent configuration](https://developers.google.com/workspace/guides/configure-oauth-consent) before creating its Desktop client. Follow Google's instructions for your app's audience and test users. - Hermes Agent installed with a model provider configured. - A Google Workspace account with access to Chat and permission to configure an app. A Gmail-only account is not the account type described by the Hermes setup. - A Google Cloud project where you can enable APIs, create a service account and manage topic and subscription permissions. - A computer that remains on and connected while you want Hermes to answer. The [Google Pub/Sub quickstart](https://developers.google.com/workspace/chat/quickstart/pub-sub) lists a Business or Enterprise Workspace account and a Cloud project with billing enabled. The Hermes page describes broader Workspace availability and small-volume free usage. Confirm your edition and billing requirements before proceeding; this guide makes no free-service promise. ### Create the Cloud project and service account At [Google Cloud Console](https://console.cloud.google.com), create or choose the intended project and record its project ID. Under APIs & Services → Library, enable Google Chat API and Cloud Pub/Sub API. Under IAM & Admin → Service Accounts, create hermes-chat-bot. A service account is an application identity, separate from the people chatting with the bot. Skip broad project-level Pub/Sub roles; the permissions below belong on individual resources. - Open the service account, then Keys → Add key → Create new key. Select JSON and download the key file. - Place the key on the Hermes host in a private location, such as ~/.hermes/google-chat-sa.json. Only the account running Hermes should be able to read it. Keep it out of Git, chat messages and screenshots. - If key creation is blocked by organization policy, ask the administrator to review the requirement. Do not weaken organization policy as a routine setup fix. The [Google service account key guide](https://docs.cloud.google.com/iam/docs/keys-create-delete) documents the JSON key flow and organization restrictions. This key authenticates Hermes to Google; it does not authorize a human to operate the agent. On Linux or macOS, restrict the downloaded service-account key with `chmod 600 ~/.hermes/google-chat-sa.json`. ### Create the topic, pull subscription and permissions - Under Pub/Sub → Topics, create a topic with ID hermes-chat-events. - Create a subscription for that topic with ID hermes-chat-events-sub, delivery type Pull and message retention of 7 days, following the Hermes page. - On the topic, grant Pub/Sub Publisher to chat-api-push@system.gserviceaccount.com. This is the publisher documented for a Chat app that is not a Workspace add-on. - On the subscription, grant your own service account Pub/Sub Subscriber and Pub/Sub Viewer. Viewer is needed for the Hermes startup reachability check. - Record the full subscription name: projects/<your-project>/subscriptions/hermes-chat-events-sub. Replace the project placeholder with your project ID. Keep the resources distinct: Google Chat publishes to the topic, while Hermes reads the subscription. The current Google quickstart has separate add-on and non-add-on instructions. Use its [Chat apps that are not add-ons](https://developers.google.com/workspace/chat/quickstart/pub-sub#chat-apps-that-arent-add-ons:-build-a-google-chat-app-with-pubsub) section with this Hermes route. ### Configure the Chat app for a private first conversation Open APIs & Services → Enabled APIs & Services → Google Chat API → Configuration. The current Google instructions for a standalone Chat app say to clear Build this Chat app as a Google Workspace add-on and confirm Disable if that option is enabled. - Enter the app name, a public avatar image URL and a short description. - Enable Join spaces and group conversations. The Hermes page also says to enable Receive 1:1 messages where that setting is shown. - For Connection settings, choose Cloud Pub/Sub and enter projects/<your-project>/topics/hermes-chat-events with your actual project ID. - Under Visibility, make the app available to specific people and groups in your domain and include your own Workspace email. Keep the first conversation restricted. - Save the configuration. This guide does not require a public Marketplace listing. Follow the [Google non-add-on configuration instructions](https://developers.google.com/workspace/chat/quickstart/pub-sub#publish-app) for the current console layout. Do not mix its generated add-on publisher identity with the standalone route above. ### Choose who can talk to it and connect Hermes Run the wizard and select Google Chat, or add these variables to your active profile .env. Use an absolute path to the service account JSON that the Hermes process can read. The platform docs use `~/.hermes/.env` for the default profile on Linux, macOS and WSL. Native Windows normally uses `%LOCALAPPDATA%\hermes\.env`. If you use a custom Hermes home or another profile, edit that profile's file instead. Replace every example value before starting. Use your own Workspace email in `GOOGLE_CHAT_ALLOWED_USERS` first. Separate additional permitted emails with commas. App visibility and resource permissions do not replace this sender list. An allowlist is the list of people permitted to use the agent. Authorize only people you trust with its enabled tools and files. Keep `GATEWAY_ALLOW_ALL_USERS` unset or false and review existing global allowlists and pairing approvals, which can also grant access. Do not expect an unknown sender to receive a pairing code when an allowlist is set. Setup wizard: ``` hermes gateway setup ``` Profile .env, manual alternative: ``` GOOGLE_CHAT_PROJECT_ID=my-chat-bot-123 GOOGLE_CHAT_SUBSCRIPTION_NAME=projects/my-chat-bot-123/subscriptions/hermes-chat-events-sub GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=/home/you/.hermes/google-chat-sa.json GOOGLE_CHAT_ALLOWED_USERS=you@yourdomain.com ``` Use your actual project ID consistently in both resource names. Native Windows needs a real Windows path to the JSON file, rather than the Linux example. For multiple Hermes profiles, put each profile's Google Chat settings in its own .env. The official docs say secondary profiles do not inherit another profile's project, subscription or service account. The optional `GOOGLE_CHAT_HOME_CHANNEL` uses a Chat space resource such as spaces/AAAA... for scheduled delivery. Set a real destination where the app is installed before relying on it. ### Prepare dependencies and send a first message For a source or local install, the official Hermes page gives this maintained dependency installer. Use the [PM-prepared source environment](https://hermes-agent.nousresearch.com/docs/reference/package-management#developer-workflow), then reactivate it before starting the gateway. PM is the Hermes package manager. Activated Hermes source checkout: ``` python -m plugins.platforms.google_chat.oauth --install-deps ``` Foreground gateway, after reactivation: ``` hermes gateway ``` The docs say published Docker images include the Google Chat extra. Their environment is read-only and on-demand dependency installation is disabled, so the installer is not a way to modify those images. Look for [GoogleChat] Connected in the gateway logs. In Google Chat, sign in with the Workspace account included in Visibility, choose New chat, search for the app and open its DM. Send Hello from the email in your Hermes allowlist. The official docs describe a posted working-state marker that is edited into the answer. Confirm the actual reply in Chat. If the app does not appear, revisit Visibility before changing Hermes credentials. ### What it can do - The official comparison table lists images, files, threads and a typing indicator. It does not list voice, emoji reactions or streaming for Google Chat. - The working-state indicator is a real Chat message edited into the final response. It does not indicate that text is being streamed as it is generated. - Replies inside an existing Chat thread stay in that thread and use a separate Hermes session. The documented message limit is 4,000 characters, with longer replies split. - Basic delivery includes text, inline images by URL and download cards for audio, video and documents. Native Chat file widgets require the optional user authorization below. Native voice notes are not documented as supported. - The platform page describes Card v2 buttons two ways: its formatting table says Card v2 buttons are unsupported, while its Clarify section describes multiple-choice Card v2 buttons with a text fallback. Card interactions may differ, so keep the text fallback available. ### Optional: enable native file attachments The Google Chat native file upload requires user credentials, rather than the bot service account. OAuth is the consent flow that lets Hermes upload as the user requesting the file. Start with text chat; add this only if native attachments are needed. Create a Desktop app OAuth client in the same project. The Hermes page uses APIs & Services → Credentials → Create credentials → OAuth client ID. The current [Google credential instructions](https://developers.google.com/workspace/guides/create-credentials#desktop-app) place this under Google Auth platform → Clients → Create Client → Desktop app. Download its JSON and move it privately to the Hermes host. Register the client in the default profile, from the prepared source environment: ``` python -m plugins.platforms.google_chat.oauth \ --client-secret /path/to/client_secret.json ``` Named profile, optional file-access registration: ``` hermes -p <profile> python -m plugins.platforms.google_chat.oauth --client-secret /path/to/client_secret.json ``` In your own DM with the bot: ``` /setup-files /setup-files start ``` Replace the JSON path before running the command. Each Hermes profile needs its own client registration. Keep the client secret and stored user tokens private. Open the OAuth URL from the bot and review the consent request. The official flow requests chat.messages.create. After consent, the browser is expected to fail at `http://localhost:1/` with a code in the address bar. Copy that URL or code back only into your own bot DM as `/setup-files <PASTED_URL>`. Do not share the URL elsewhere. Each user completes this flow in their own DM. Later uploads use that user's token. `/setup-files revoke` removes that user's token without deleting other users' tokens. ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. After your first message succeeds, stop the foreground gateway with Ctrl+C. For a normal host installation, the official gateway docs give these service commands: Install, start and inspect the host service: ``` hermes gateway install hermes gateway start hermes gateway status ``` Linux uses systemd, macOS uses launchd, and Windows uses a Scheduled Task at logon. On a headless Linux host using a user service, the docs give `sudo loginctl enable-linger $USER` to keep it available after logout. Windows Task Scheduler does not restart a gateway that crashes after its launcher exits. In a container, use the documented container startup and restart policy instead of installing a host user service. For hosting choices, see [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md). ### If it doesn't answer - App is missing from search: confirm your Workspace account is included in the Chat API Visibility settings and that you selected the standalone app configuration. - No events reach the subscription: check the exact topic path and the topic Publisher grant for chat-api-push@system.gserviceaccount.com. - Undelivered messages build up: check the service account JSON path, its subscription Subscriber and Viewer permissions, and whether the gateway is running. Retention is not a promise that every offline message will become an agent reply. - Configuration validation fails: read the specific variable named in the gateway log. Make sure the selected profile has its own credentials. - Repeated Pub/Sub stream died messages: check whether credentials were rotated or the subscription was removed. An outbound 403 can mean the bot was removed from its Chat space. - Text replies work but native uploads do not: finish `/setup-files` for the requesting user. The service account alone cannot perform that upload. - See [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) for the wider gateway checklist. ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes Google Chat docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/google_chat) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [How to set up Hermes Agent on Slack](https://hermeswatcher.com/learn/hermes-agent-slack-setup.md) - [How to set up Hermes Agent on Microsoft Teams](https://hermeswatcher.com/learn/hermes-agent-microsoft-teams-setup.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) ### Related tools - [Google Workspace: connect everyday work with explicit scopes](https://hermeswatcher.com/tools/google-workspace.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) ### Sources - [Hermes Agent: Google Chat](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/google_chat) - [Google: Chat apps behind a firewall with Pub/Sub](https://developers.google.com/workspace/chat/quickstart/pub-sub) - [Google: create and protect service account keys](https://docs.cloud.google.com/iam/docs/keys-create-delete) - [Google: desktop OAuth credentials](https://developers.google.com/workspace/guides/create-credentials#desktop-app) - [Package management: source checkout workflow](https://hermes-agent.nousresearch.com/docs/reference/package-management#developer-workflow) - [Messaging gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) - [Gateway authorization source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L660-L772) - [Native Windows settings paths](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native) - [pyproject.toml](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/pyproject.toml) ## How to set up Hermes Agent on Matrix > Create a Matrix bot account, configure its credentials and allowlists, choose an encryption mode and start a private conversation. URL: https://hermeswatcher.com/learn/hermes-agent-matrix-setup Last reviewed: Oct 29, 2026 ### What you need Matrix is a messaging protocol that connects accounts through homeservers. A homeserver is the server that hosts your Matrix account. Hermes signs into a Matrix account and receives messages through that server. Platform support: the Matrix dependencies are Linux-only, including WSL2. Native macOS and Windows cannot load the adapter directly. Use a Linux host or WSL2, or [official Proxy Mode](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/matrix#proxy-mode-e2ee-on-macos): a Linux container runs the adapter and forwards requests to your host's API server. Proxy Mode exposes the host's API server to the container, so it needs a strong `API_SERVER_KEY` and network protection. In v1, approval prompts are handled on the host rather than in Matrix, and tool progress is not relayed. - Hermes Agent installed with a model provider configured. - A dedicated Matrix account for the bot on a homeserver where you can register or have an administrator create it. You can use a public or self-hosted server. - The bot's homeserver URL and access token, or its full user ID and password for the documented password-login alternative. - Your own full Matrix user ID, such as @alice:matrix.example.org, for access control. - The Matrix Python dependencies (the `matrix` extra, Linux only) are needed to connect. Hermes can request them on first use. Encrypted rooms also need the system libolm library. - A computer with access to the homeserver that stays on whenever you want the bot available. ### Create the bot account and get its token For the client-based route, open [Element Web](https://app.element.io) and choose Create Account. Select the intended homeserver, register a separate bot identity and complete that server's registration and email checks. [Element onboarding](https://docs.element.io/latest/element-support/quick-start-guide/onboarding/) describes this flow. Sign into Element as the bot. Open Settings → Help & About. Under Advanced, reveal Access Token and copy it. The [Element FAQ](https://docs.element.io/latest/element-support/frequently-asked-questions/) confirms this token grants full account access. Record the full bot user ID and homeserver URL. In your own account, open profile settings and copy your full Matrix user ID for the sender allowlist. A display name is not a user ID. Keep the token secret and out of Git, screenshots and shared messages. The Hermes docs say to revoke compromised account sessions. An administrator can also create the bot account on a private server; this guide uses Element rather than installing a new homeserver. Password login is another documented option. It stores the bot's password in the profile configuration, so it needs the same private handling as a token. ### Choose who can talk to it An allowlist is the list of people permitted to use the agent. Authorize only people you trust with its enabled tools and files. Keep `GATEWAY_ALLOW_ALL_USERS` unset or false and review existing global allowlists and pairing approvals, which can also grant access. Do not expect an unknown sender to receive a pairing code when an allowlist is set. Set `MATRIX_ALLOWED_USERS` to the full IDs of trusted people. For shared rooms, also set `MATRIX_ALLOWED_ROOMS` to their internal room IDs, such as !abc123:matrix.example.org. In Element, the Hermes docs point to room settings → Advanced for the internal ID. A #room:server alias is not the internal ID. The room allowlist does not restrict DMs. The official page says rooms with two or fewer joined members are treated as DMs, even when named. Those conversations bypass room filtering and mention rules, so the user allowlist remains essential. The bot automatically accepts room invitations. A room invitation or an @mention should not be treated as permission to operate the agent. Do not leave access implicit or use an empty allowlist as an access policy. ### Connect it to Hermes Run the setup wizard and select Matrix. Provide the homeserver URL, credentials and allowed user IDs. To configure manually, use one of these credential alternatives in the active profile .env. These adapter settings belong to the Linux or WSL2 installation, normally in `~/.hermes/.env`. For a native macOS or Windows agent, use the separate Proxy Mode instructions. If you use a custom Hermes home or another profile, edit that profile's file instead. Replace every example value before starting. Setup wizard: ``` hermes gateway setup ``` Profile .env, token alternative: ``` MATRIX_HOMESERVER=https://matrix.example.org MATRIX_ACCESS_TOKEN=*** MATRIX_ALLOWED_USERS=@alice:matrix.example.org MATRIX_ALLOWED_ROOMS=!abc123:matrix.example.org ``` Profile .env, password alternative: ``` MATRIX_HOMESERVER=https://matrix.example.org MATRIX_USER_ID=@hermes:matrix.example.org MATRIX_PASSWORD=*** MATRIX_ALLOWED_USERS=@alice:matrix.example.org ``` Use either your real token or the password-login settings; *** is only a secret placeholder. The password example still needs `MATRIX_ALLOWED_ROOMS` if you will use shared rooms. Separate multiple users or rooms with commas. Keep user separation enabled for shared rooms. The official page describes group_sessions_per_user: true as the default, giving participants separate context within a room. Turning it off shares a transcript and its context costs. ### Prepare dependencies and choose encryption deliberately End-to-end encryption (E2EE) encrypts messages between Matrix clients. The official Hermes page supports off, optional and required modes. Choose the mode before starting an encrypted conversation. The official page gives this command for the Matrix extra. Run it only in a [PM-prepared Hermes source checkout](https://hermes-agent.nousresearch.com/docs/reference/package-management#developer-workflow), then reactivate the checkout and restart Hermes. PM is the Hermes package manager. Activated Hermes source checkout: ``` python -c "import pm; pm.sync_venv(['matrix'], explicit=True)" ``` Debian or Ubuntu, for encryption: ``` sudo apt install libolm-dev ``` Fedora, for encryption: ``` sudo dnf install libolm-devel ``` Profile .env, refuse to run if encryption can't start: ``` MATRIX_E2EE_MODE=required ``` On the Linux host or WSL2 installation, use the system-library command for your distribution. For a native macOS or Windows agent, follow Proxy Mode instead of installing the adapter natively. off does not initialize end-to-end encryption. optional tries encryption but keeps unencrypted rooms usable if crypto cannot initialize. required fails closed if dependencies or crypto setup are missing. Use required when encrypted operation is a requirement. Required mode is not proof that every room is encrypted. Choose an encrypted Matrix conversation and check its state in your client. The bot can decrypt content to process it; Matrix transport encryption does not describe what an external model provider receives. Keep ~/.hermes/platforms/matrix/store/ private and persistent. The official docs warn that deleting its crypto database destroys the bot's encryption identity and can require recovery. Do not delete it as a routine troubleshooting step. For cross-signing, the official page documents `MATRIX_RECOVERY_KEY` so the bot can sign its device. Use only the bot account's recovery key and protect it like a password. If an encrypted conversation fails, follow the official device-verification instructions before sending sensitive material. ### Start the gateway and send your first message Start the foreground gateway and read its connection and encryption logs. From your allowed personal account, invite the bot's full Matrix ID to a private DM or an intended room. Foreground gateway: ``` hermes gateway ``` The docs describe automatic acceptance of invitations. In a DM, send Hello. In a regular room, @mention the bot. Confirm the response in your Matrix client before relying on the connection. If you need encrypted chat, confirm that the conversation is encrypted and follow the official instructions to verify or trust the bot's device. A successful login or sync alone does not establish decryption. For scheduled output, set the destination from the intended conversation with `/sethome`, or !sethome if your client intercepts slash commands. The documented environment setting is `MATRIX_HOME_ROOM`, containing the internal room ID. ### What it can do - The official comparison table lists voice, images, files, threads, reactions, typing indicators and streaming updates for Matrix. The platform page also documents video and optional encryption. - DMs normally do not need a mention. Regular rooms need one by default; threads where the bot has participated can continue without another mention. The default room behavior creates threads to keep conversations separate. - Use normal slash commands when your Matrix client sends them. If it intercepts them, Hermes documents known !command aliases, such as !sethome. - Voice bubbles depend on a client that supports the documented Matrix voice-message extension. Incoming voice can be routed to speech-to-text; speech services still need their own configuration. - Media is uploaded to the homeserver. The documented default media limit is 100 MB. Inbound media must use Matrix content URIs beginning mxc://, rather than arbitrary web download URLs. - Approvals and model selection can use reactions. Approval controls are requester-bound by default when Hermes knows who requested the action. - The adapter does not expose room creation, invitations or redaction as Matrix-specific agent tools. Do not confuse internal adapter controls with tools you can ask the model to use. ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. After your first message succeeds, stop the foreground gateway with Ctrl+C. For a normal host installation, the official gateway docs give these service commands: Install, start and inspect the host service: ``` hermes gateway install hermes gateway start hermes gateway status ``` For this Linux or WSL2 adapter, use the Linux service instructions. macOS and native Windows need the separate Linux Proxy Mode adapter. On a headless Linux host using a user service, the docs give `sudo loginctl enable-linger $USER` to keep it available after logout. Windows Task Scheduler does not restart a gateway that crashes after its launcher exits. In a container, use the documented container startup and restart policy instead of installing a host user service. For hosting choices, see [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md). ### If it doesn't answer - Bot appears offline: check that the gateway is running, the homeserver URL is reachable and the token is valid. - Bot joins but ignores you: check your full @user:server ID in `MATRIX_ALLOWED_USERS`, then restart after changing configuration. - A regular room is silent: check its internal ID against `MATRIX_ALLOWED_ROOMS` and @mention the bot. Remember that DM-classified rooms bypass that room filter. - Missing Matrix dependency: request the Matrix extra through PM in the correct source environment, reactivate it and restart. - Decryption errors: check libolm, the selected encryption mode and trust in the bot's device. The official page warns against assuming access to messages from before the bot joined. Follow its E2EE recovery section for an existing damaged identity. - Connected and able to send, but no inbound replies: inspect sync-related errors in gateway logs. A successful outbound message alone does not establish that event handling is healthy. - Bridge traffic echoes: keep bridge or appservice identities out of your sender allowlist. Leave notice processing at its default unless a trusted workflow needs it. - See [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) for the general gateway checklist. - Connected but all messages are ignored: check the host clock. A clock running ahead can make live events appear too old. Enable NTP time synchronization and restart. ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes Matrix docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/matrix) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [How to set up Hermes Agent on Slack](https://hermeswatcher.com/learn/hermes-agent-slack-setup.md) - [How to set up Hermes Agent on Google Chat](https://hermeswatcher.com/learn/hermes-agent-google-chat-setup.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) ### Related tools - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) ### Sources - [Hermes Agent: Matrix](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/matrix) - [Element: account onboarding](https://docs.element.io/latest/element-support/quick-start-guide/onboarding/) - [Element: access token FAQ](https://docs.element.io/latest/element-support/frequently-asked-questions/) - [Package management: source checkout workflow](https://hermes-agent.nousresearch.com/docs/reference/package-management#developer-workflow) - [Messaging gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) - [Gateway authorization source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L660-L772) - [Native Windows settings paths](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native) - [pyproject.toml](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/pyproject.toml) ## How to set up Hermes Agent on Signal > Link Signal through signal-cli, restrict access, start both processes and send a first message, with notes on media and keeping the host online. URL: https://hermeswatcher.com/learn/hermes-agent-signal-setup Last reviewed: Oct 29, 2026 ### What you need Hermes connects through signal-cli, an external client linked to your Signal account. A daemon, a process that stays running, passes messages between Signal and the Hermes gateway. This is a bridge setup rather than a Signal bot account API. For background, see [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md). Linking signal-cli adds a device that can decrypt incoming Signal messages on this computer. Use a dedicated Signal account to keep personal chats separate. Messages sent to Hermes are processed by its configured model provider and tools. If another service on this computer already uses port 8080, choose another port and use it consistently wherever this guide shows 8080. - Hermes Agent installed with a model provider configured. - Signal on your phone and the phone number for the account you will link. - signal-cli installed using its own installation instructions. Hermes lists Java 17+, but the current signal-cli README requires JRE 25 for its Java build. Follow the requirements for the release you install. - A host that stays awake and online, with both signal-cli and the Hermes gateway running when you want replies. ### Install and link signal-cli Use the installation instructions at [signal-cli installation instructions](https://github.com/AsamK/signal-cli#installation) for your operating system. Keep signal-cli current: its maintainers warn that old releases can stop working after Signal server changes. Run the linking command below. On your phone, open Signal, go to Settings, then Linked Devices, and choose Link New Device. Follow the linking prompt using the QR code or URI produced by signal-cli. Your phone remains the primary device. Link the secondary device: ``` signal-cli link -n "HermesAgent" ``` Protect the session data in `~/.local/share/signal-cli/` like a password. It contains account credentials. Do not share it or include it in a support screenshot. ### Start the Signal bridge Replace `+15551234567` with your Signal account number in E.164 format: a plus sign, country code and number. Start the daemon, leave it running, then check it from a second terminal. The example listens on `127.0.0.1`, also called loopback. Only programs on that computer can connect to this address. Keep this local setup for the first connection. Terminal 1: run signal-cli: ``` signal-cli --account +15551234567 daemon --http 127.0.0.1:8080 ``` Terminal 2: check the daemon: ``` curl http://127.0.0.1:8080/api/v1/check ``` The official docs describe a response containing signal-cli version information. If the check cannot reach the daemon, resolve that before configuring Hermes. ### Connect it to Hermes Run the gateway wizard and select Signal. It checks for signal-cli, asks for the HTTP address, tests the connection, then asks for the account number and allowed users. The allowed-users prompt defaults to the account number. Alternatively, edit `~/.hermes/.env` using the example below. Replace both example phone numbers: `SIGNAL_ACCOUNT` is the linked account, while `SIGNAL_ALLOWED_USERS` names the people allowed to use the agent. Gateway wizard: ``` hermes gateway setup ``` ~/.hermes/.env (manual alternative): ``` SIGNAL_HTTP_URL=http://127.0.0.1:8080 SIGNAL_ACCOUNT=+15551234567 SIGNAL_ALLOWED_USERS=+15551234567,+15559876543 ``` ### Choose who can talk to it An allowlist is an explicit list of people allowed to use the agent. Set `SIGNAL_ALLOWED_USERS` to comma-separated E.164 phone numbers or Signal UUIDs. Grant access only to people you trust with the agent's tools, which can include terminal access. DM pairing is another route. If your policy offers an unknown direct-message sender a code, review the request locally before approving it. With a restrictive allowlist or policy, unknown senders can be ignored instead. Do not expect a pairing code in every configuration. In `hermes gateway setup`, answer No to “Enable group messaging?” unless you need groups. If you answer Yes, enter specific group IDs. Pressing Enter with no existing group list saves `*`, allowing all groups. - Leave `SIGNAL_ALLOW_ALL_USERS` unset for this setup. - Leave `SIGNAL_GROUP_ALLOWED_USERS` unset to ignore group messages. Despite its name, this setting takes group IDs. Add only specific trusted group IDs if you need groups; `*` monitors every group the account belongs to. - A group setting and a sender's permission are separate checks. Do not treat permission to monitor a group as permission for every member to operate the agent. Approve a code only after checking the sender: ``` hermes pairing approve signal CODE ``` ### Start the gateway and send your first message With signal-cli still running, start Hermes in another terminal. Send a short text from an allowed account to the linked Signal account. If you linked your own number, use Signal's Note to Self from your phone. The platform docs describe this route when `SIGNAL_ACCOUNT` matches your number. Include your number in the allowlist. Run the gateway in the foreground: ``` hermes gateway ``` Look for the inbound message in the gateway output and a reply on your phone. `Ctrl+C` stops the foreground gateway. ### What it can do The gateway comparison table lists images, files and typing indicators for Signal. It does not mark voice, threads, reactions or streaming as supported. The Signal page gives more detail and differs from that table on audio and reactions. - The Signal page describes incoming images, documents and audio. Incoming voice transcription needs Whisper configured. Outgoing audio is sent as an attachment, alongside support for images, video and documents. - The page states a 100 MB attachment limit in either direction and warns that Signal rate-limits uploads. - It also describes native formatting, quoted replies and reactions, with plaintext fallback on older signal-cli versions. A quoted reply does not establish support for separate threaded conversations. - Long replies are split into numbered messages. Signal cannot edit sent messages, so Hermes suppresses live tool-progress bubbles even when verbose mode is enabled. ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. Both processes must stay running: the Hermes gateway and the separate signal-cli daemon. Installing the Hermes service does not manage signal-cli for you. The Signal docs suggest a service or a persistent terminal session for the daemon. After the foreground check, stop that gateway before using the service. These service commands are for the Hermes host. Install the gateway service: ``` hermes gateway install ``` Start it: ``` hermes gateway start ``` Check it: ``` hermes gateway status ``` The gateway uses systemd on Linux, launchd on macOS, or a logon Scheduled Task on Windows. A Windows task does not supervise a later gateway crash. Check status if replies stop. A sleeping or switched-off host cannot process requests or send replies. For hosting choices, see [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md). ### If it doesn't answer - Repeat the local daemon check. Confirm the daemon's account number matches `SIGNAL_ACCOUNT` and its address matches `SIGNAL_HTTP_URL`. - Check the sender's full phone number, including `+` and country code, against the allowlist. Group messages are ignored until their group IDs are configured. - Check signal-cli logs and the installed release's Java requirements if the connection drops. For duplicates, make sure only one signal-cli instance is listening on the account. - Check that Hermes is using the intended profile. Saved credentials do not mean a gateway is running; an explicit disabled platform setting overrides credentials. See [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md). ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes Signal docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/signal) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) - [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md) ### Related tools - [Signal: a private, end-to-end encrypted channel to your agent](https://hermeswatcher.com/tools/signal.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) ### Sources - [Signal setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/signal) - [Signal setup source snapshot](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/signal.md) - [Messaging gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) - [Gateway access policy source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L730-L773) - [signal-cli installation requirements](https://github.com/AsamK/signal-cli/blob/master/README.md#installation) - [plugins/platforms/signal/setup.py](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/plugins/platforms/signal/setup.py) ## How to set up Hermes Agent on email > Use a dedicated IMAP/SMTP inbox, allow trusted senders, pin sender authentication and start the Hermes email gateway for threaded replies. URL: https://hermeswatcher.com/learn/hermes-agent-email-setup Last reviewed: Oct 29, 2026 ### What you need The email gateway turns a dedicated inbox into a way to talk to Hermes. IMAP reads incoming mail; SMTP sends replies. This adapter uses Python's built-in mail modules. You do not need the separate Himalaya CLI or mailbox-management skill. For gateway background, see [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md). - Hermes installed with a model provider, on a host that stays on when you want replies. - A dedicated email account with IMAP and SMTP access, its server names, ports and provider-supported password or app password. Use a separate inbox because the agent has full inbox access through IMAP. - The full email addresses of the people allowed to use it, plus the receiving server's sender-authentication identifier explained below. - An email account may have provider costs. The Hermes documentation does not require a separate paid email gateway service. ### Prepare the dedicated mailbox Confirm that your provider permits the IMAP/SMTP authentication method this adapter uses. Obtain the server names and ports from that provider. The documented defaults are IMAP over TLS on port 993 and SMTP with STARTTLS on port 587. Both encrypt the connection. For a Gmail account that permits app passwords, enable 2-Step Verification, open [Google app passwords](https://myaccount.google.com/apppasswords) and create an app password for this setup. Copy it when shown and use it instead of your normal Google password. Google says app passwords may be unavailable for organization accounts, Advanced Protection, or security-key-only 2-Step Verification. If your account does not offer a supported credential, check its provider or administrator's instructions before proceeding. Do not assume an Outlook or Microsoft 365 account accepts app passwords merely because the Hermes page includes that example. Keep the password secret. Hermes stores it in `~/.hermes/.env`. On Unix-like hosts, the email docs recommend restricting that file's permissions with `chmod 600`. ### Choose senders and pin their authentication Set `EMAIL_ALLOWED_USERS` to full, comma-separated email addresses. This allowlist restricts who may operate the agent. A bare chat username does not grant access to an email address. Unknown email senders are ignored by default; email pairing is opt-in. An address in a From field can be forged. Hermes also checks the sender-domain authentication result stamped by your receiving mail server, such as DMARC or aligned SPF/DKIM. An allowlist alone is not enough. Open the raw source of a message delivered to this inbox. In the topmost `Authentication-Results` header, find the identifier before the first semicolon. Set `EMAIL_AUTHSERV_ID` to that exact value. Gmail's documented example is `mx.google.com`; use your own receiving server's value for another provider. Confirm with your provider or mail administrator that the receiving server removes incoming headers claiming its own identifier before adding its stamp. A matching string alone does not establish that the header is trustworthy. A self-hosted server needs a stable identifier, not a changing relay hostname. Without this pin, Hermes drops messages that require authenticated senders. Keep sender authentication enabled and leave `EMAIL_ALLOW_ALL_USERS` unset. Do not enable `EMAIL_TRUST_FROM_HEADER` to work around setup errors: that makes Hermes trust the written From address. Review any existing global allowlist or approved pairings too: the docs say these can also admit senders. Access is to the agent and its configured tools, not just to a mail reply. ### Connect it to Hermes Run the wizard and select Email. It asks for the address, password, server names and allowed senders. Then check `~/.hermes/.env` and add the required authentication pin if it is missing. For manual setup, the Gmail example below shows the required fields and an explicit sender list. Replace the address, password and senders. For another provider, also replace the server names, ports if needed, and authentication identifier. The shown password is a placeholder. Gateway wizard: ``` hermes gateway setup ``` ~/.hermes/.env (manual Gmail example): ``` EMAIL_ADDRESS=hermes@gmail.com EMAIL_PASSWORD=abcd efgh ijkl mnop EMAIL_IMAP_HOST=imap.gmail.com EMAIL_SMTP_HOST=smtp.gmail.com EMAIL_ALLOWED_USERS=your@email.com,colleague@work.com EMAIL_AUTHSERV_ID=mx.google.com EMAIL_IMAP_PORT=993 EMAIL_SMTP_PORT=587 EMAIL_POLL_INTERVAL=15 ``` Local relays such as Proton Mail Bridge have different transport settings. Follow the email page's local-relay section if needed. Its certificate-verification exception is limited to loopback hosts, not an instruction to disable checks on remote mail servers. ### Start the gateway and send a new email Before starting, note the documented mailbox change: the adapter marks all existing inbox messages as seen on startup. It then processes new unseen messages. Use the dedicated mailbox, not a personal or shared inbox containing unrelated unread mail. Start the gateway and watch its IMAP and SMTP connection checks. Once it is listening, send a new, short email from an allowed address to the agent's inbox. The default polling interval is 15 seconds, before model processing and mail delivery time. Run in the foreground: ``` hermes gateway ``` Look for receipt in the gateway output and a reply in the sender's mailbox. Reply to that email to check the conversation thread. `Ctrl+C` stops the foreground gateway. ### What it can do The gateway table lists images, files and threads for email. It does not mark voice, reactions, typing indicators or streaming as supported. - Incoming image and document attachments are cached locally for the agent's tools. HTML-only email is converted to plain text. - SMTP replies are plain text, with reply headers to preserve threads. Some mail clients may still display automated replies outside the expected thread. - The agent can attach files in replies through the documented `MEDIA:/path/to/file` mechanism. - Self-messages and automated, bulk or no-reply mail are filtered. A mailing-list message or an email carrying `Auto-Submitted`, `Precedence: bulk` or `List-Unsubscribe` headers is not a suitable first check. To skip all incoming attachments, merge the following into your existing `~/.hermes/config.yaml`. This skips attachment and inline parts before decoding; it still processes body text. ~/.hermes/config.yaml (optional, skip incoming attachments): ``` platforms: email: skip_attachments: true ``` ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. After checking the foreground setup, stop that gateway before installing and starting the background service. The service is systemd on Linux, launchd on macOS, or a logon Scheduled Task on Windows. Install the gateway service: ``` hermes gateway install ``` Start it: ``` hermes gateway start ``` Check it: ``` hermes gateway status ``` A service cannot answer while its host is asleep or switched off. Do not rely on catching up later: the documented startup behavior marks existing inbox mail as seen. Send a fresh email after restarting to check delivery. On Windows, Task Scheduler does not restart a gateway that crashes after its launcher exits. Check status if replies stop. See [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md) for hosting choices. Only after ordinary replies are behaving as expected, optionally set `EMAIL_HOME_ADDRESS` in `.env` to the address that should receive scheduled-task results. ### If it doesn't answer - Connection failure: check both server names and ports, IMAP availability and the provider-supported credential. For Gmail, use the app password and check whether an account password change revoked it. - No inbound message: send a new email after startup from a full address on the allowlist. Check that it is not filtered as automated mail. - Unauthenticated From warning: check the exact topmost `Authentication-Results` identifier, `EMAIL_AUTHSERV_ID`, and the sender's authentication verdict. An allowed sender can still fail authentication after broken DKIM or forwarding. Fix the authentication problem rather than opening access. - Missing reply: inspect the sender's spam folder and gateway output. For duplicate replies, check `hermes gateway status` and make sure only one gateway is running. - Saved settings but no adapter: check the selected profile and any explicit `platforms.email.enabled: false`. See [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) and [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md). ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes email docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/email) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) - [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md) - [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md) ### Related tools - [Email gateway: give Hermes its own inbox](https://hermeswatcher.com/tools/email-gateway.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) ### Sources - [Email setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/email) - [Email setup source snapshot](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/email.md) - [Messaging gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) - [Google account app passwords](https://support.google.com/accounts/answer/185833) ## How to set up Hermes Agent on iMessage with Photon > Connect iMessage through Photon's hosted service without a Mac relay. Set access controls and understand shared-line and incoming-attachment limits. URL: https://hermeswatcher.com/learn/hermes-agent-imessage-photon-setup Last reviewed: Oct 29, 2026 ### Which iMessage route? With Photon, you text a phone number that Photon gives you. The agent replies through that managed line. It does not run inside your own Apple ID. Your messages pass through Photon's service on their way to Hermes. Check its privacy terms before sending sensitive information. Photon is a hosted vendor service: no Mac relay is needed, but you need a Photon account and an iMessage-capable phone number. Hermes docs describe free shared lines and a paid Business dedicated line. Shared lines need the recipient to message first; incoming attachments are metadata-only, so the agent cannot read their contents. BlueBubbles runs through your own Mac, which must stay on and signed into Messages. For that route, see [How to set up Hermes Agent on iMessage with BlueBubbles](https://hermeswatcher.com/learn/hermes-agent-imessage-bluebubbles-setup.md). Both routes also need the Hermes host online for replies. ### What you need Hermes uses a small Node helper process, called a sidecar, to maintain the Photon connection. The gateway manages that process. This route does not need a webhook, public HTTPS URL or tunnel. Those are ways of accepting incoming internet requests; Photon uses a persistent connection instead. - Hermes installed with a model provider on the computer or server that will run the gateway. - A Photon account at [the Photon dashboard](https://app.photon.codes/) and a phone number that can receive iMessage, used to bind your account. - Node.js. Hermes can provision its managed Node with the command below. The adapter can also use Node from PATH. Provision managed Node if needed: ``` hermes pm install node ``` ### Connect the Photon account Run the gateway wizard and choose Photon iMessage. Alternatively, use the direct setup command below with your own iMessage-capable number in international format, including `+` and the country code. Choose one setup route. Follow the device-login approval at `app.photon.codes`. Setup prepares your Photon account for Hermes, registers your phone number and installs the helper it needs. It also creates a new secret, so run it again only when you mean to. Record the assigned iMessage line it prints: that is the number you text to reach the agent. Gateway wizard: ``` hermes gateway setup ``` Direct alternative, replace the example number: ``` hermes photon setup --phone +15551234567 ``` Setup writes `PHOTON_PROJECT_ID` and `PHOTON_PROJECT_SECRET` into `~/.hermes/.env`. The saved device token and dashboard project metadata live in `~/.hermes/auth.json`. Protect both files and keep their credentials out of chat, screenshots and source control. On a read-only installation, the documented sidecar fallback is a writable copy under `~/.hermes/photon/sidecar`. Setup still needs to install that helper's dependencies. ### Choose who can talk to it For a personal setup, add your own number to `PHOTON_ALLOWED_USERS` in `~/.hermes/.env`. This allowlist is the explicit list of people allowed to use your agent. Replace the example numbers; use full international numbers (E.164 format: a plus sign, country code and number), separated by commas. Even with an allowlist, an unknown sender might receive a pairing code. A code does nothing until you approve it, so approve only people you recognize. ~/.hermes/.env (restrict access): ``` PHOTON_ALLOWED_USERS=+15551234567,+15559876543 ``` Inspect pairing requests if using pairing: ``` hermes pairing list ``` Approve only a sender you recognize: ``` hermes pairing approve photon <CODE> ``` Leave `PHOTON_ALLOW_ALL_USERS` unset. Access to the agent can include access to its terminal and other tools. By default, Hermes answers authorized direct and group messages. To require a wake word in groups, the docs expose `PHOTON_REQUIRE_MENTION` in `.env`; enable it with the boolean value `true`. Defaults match Hermes and @Hermes agent. This gate does not replace sender authorization and does not gate direct messages. ### Start the gateway and send your first message For an initial foreground check, run the gateway and leave the terminal open. Hermes starts the Node helper automatically. In another terminal, inspect Photon status to see the registered phone number, assigned line and sidecar health. From your allowed iMessage number, text a short message to the assigned line. On a shared line, you must message it first before the agent can send to you. Look for the inbound event and a reply. An assigned number or stored credential alone does not show that messages are being delivered. Run the gateway in the foreground: ``` hermes gateway ``` Inspect Photon status: ``` hermes photon status ``` `Ctrl+C` stops the foreground gateway and its managed helper. Complete your own message check before using this channel for scheduled notifications. ### What it can do and where it stops The gateway table marks voice, images, files, reactions and typing for Photon. It does not mark threads or streaming. The platform page adds an important direction limit: incoming attachments provide filenames and media types only. The agent cannot read the incoming image, document or audio bytes through this adapter. - Outgoing images, voice notes, videos and documents are documented. Captions arrive as a separate iMessage bubble after the media. - The platform page also documents native polls and message effects. These are channel capabilities, not a promise that every model response will use them. - Read receipts are sent after an inbound message is forwarded to Hermes, before the model or tools finish. Read is not proof that the task completed. Set `PHOTON_READ_RECEIPTS=false` in `.env` if you want to disable those receipts. ### Shared lines, quotas and cost Hermes docs describe a free shared-line pool with no subscription needed for the first message. Different recipients may see different sending numbers, while each conversation keeps its number. The paid Business tier provides a dedicated number shared across your recipients. Check the current dedicated-line price in your Photon account. The same docs report 5,000 messages per server per day and 50 new-conversation initiations per shared line per day. They separately state that a shared line cannot initiate contact with a new recipient at all until that recipient texts the line. Treat the recipient-first rule as a requirement, not as permission to cold-message 50 people. These are the terms reported in the Hermes documentation, not an independent check of your Photon account's commercial terms. Confirm the current plan and limits in your account before relying on them. ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. After the foreground check, stop that gateway before installing and starting a background service. The gateway owns the sidecar; cron jobs and standalone sends also reuse that running helper. A hosted Photon line does not keep your Hermes agent running for you. Install the gateway service: ``` hermes gateway install ``` Start it: ``` hermes gateway start ``` Check it: ``` hermes gateway status ``` For hosting choices, see [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md). The service uses systemd on Linux, launchd on macOS, or a logon Scheduled Task on Windows. The Windows launcher does not supervise later gateway crashes, so check status if replies stop. ### If it doesn't answer Start with `hermes photon status`. Check the registered number, assigned line, saved login and sidecar health before changing access controls. - Missing sidecar dependencies: run the documented repair command below. The platform page says a PATH Node installation must be 18.17 or newer if the helper will not start. - Missing device token or no assigned line: run `hermes photon setup` and inspect your Photon dashboard. Setup rotates the project secret; do not treat it as a read-only status check. - Unknown sender ignored: check the E.164 number in the allowlist. An unknown sender may be ignored or receive a pairing code. A code grants no access until you approve it. - Standalone send rejected or gateway reported down: start the gateway, then check the helper. A new shared-line recipient must send the first message. - Incoming file cannot be read: this is a documented adapter limit, not a reason to open access or reinstall. See [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) for the broader gateway checklist. Repair sidecar dependencies if status requests it: ``` hermes photon install-sidecar ``` ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes iMessage with Photon docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/photon) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [How to set up Hermes Agent on iMessage with BlueBubbles](https://hermeswatcher.com/learn/hermes-agent-imessage-bluebubbles-setup.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) - [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md) ### Related tools - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) ### Sources - [Photon iMessage setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/photon) - [Photon setup source snapshot](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/photon.md) - [BlueBubbles iMessage setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/bluebubbles) - [Messaging gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) - [Gateway access policy source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L730-L773) - [gateway/authz_mixin.py](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/gateway/authz_mixin.py) - [plugins/platforms/photon/adapter.py](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/plugins/platforms/photon/adapter.py) ## How to set up Hermes Agent on iMessage with BlueBubbles > Use an always-on Mac and BlueBubbles to connect iMessage to Hermes. Configure both network directions, authorize senders and check delivery. URL: https://hermeswatcher.com/learn/hermes-agent-imessage-bluebubbles-setup Last reviewed: Oct 29, 2026 ### Which iMessage route? BlueBubbles needs a Mac that stays on and signed into Messages with your Apple ID. Hermes docs describe BlueBubbles as free, open-source server software. You supply the Mac and keep it available. Photon is a hosted vendor service that needs no Mac relay. It requires a Photon account and an iMessage-capable number. Hermes docs describe free shared lines, a paid dedicated-line tier, recipient-first contact on shared lines and metadata-only incoming attachments. See [How to set up Hermes Agent on iMessage with Photon](https://hermeswatcher.com/learn/hermes-agent-imessage-photon-setup.md). Both routes need the Hermes host online. ### What you need BlueBubbles bridges Messages on your Mac to Hermes. Hermes can run on the Mac or on another reachable machine. Starting with both on the same Mac uses the documented local webhook defaults and avoids the separate-machine network setup. - A Mac running BlueBubbles Server 1.0.0 or newer, with your Apple ID signed into Messages. - Hermes installed with a model provider and a gateway host that stays awake and online. - The BlueBubbles server address and password, plus network access in both directions if Hermes runs on a different machine. - Basic text and media can use a foreground, logged-in macOS user without the optional Private API helper. Background-user setups have additional requirements described below. ### Prepare the Mac and BlueBubbles server Download BlueBubbles Server from [the BlueBubbles site](https://bluebubbles.app/) and complete its setup wizard. Sign into Messages with the intended Apple ID and choose the connection method appropriate to your setup. The Hermes page lists local network, Ngrok, Cloudflare or Dynamic DNS options. In BlueBubbles Server, open Settings, then API. Record the server URL and server password. The Hermes docs use `http://192.168.1.10:1234` as a local-network example; replace it with the address of your server. The account running BlueBubbles should remain logged in. A Mac sitting at the login screen, or a user switched into the background, can fail to send through AppleScript without the Private API helper. Keeping the Mac powered on alone is not sufficient. Keep the server password secret. It is used for API access and in the registered webhook URL, so treat full callback URLs and logs containing them as credentials too. ### Connect it to Hermes Run the wizard, select BlueBubbles (iMessage), and enter the server URL and password. Alternatively, add the two settings below to `~/.hermes/.env`, replacing the example address and password. Setup saves credentials, but does not override an explicit `platforms.bluebubbles.enabled: false` in `~/.hermes/config.yaml`. Check this setting if you previously used another iMessage bridge. Gateway wizard: ``` hermes gateway setup ``` ~/.hermes/.env (manual alternative): ``` BLUEBUBBLES_SERVER_URL=http://192.168.1.10:1234 BLUEBUBBLES_PASSWORD=your-server-password ``` Check explicit enablement: ``` hermes config get platforms.bluebubbles.enabled ``` The docs say `true` enables the adapter, an unset key lets credentials drive enablement, and `false` disables it. If it is explicitly false, change the existing `platforms.bluebubbles.enabled` setting to true. Avoid two active bridges handling the same account. ### Choose who can talk to it Set `BLUEBUBBLES_ALLOWED_USERS` in `.env` to the phone numbers or email addresses allowed to operate your agent. This allowlist is separate from the server password, which authenticates the bridge connection. DM pairing is an alternative when the gateway policy offers a code. Inspect the request locally and approve only a sender you recognize. Restrictive allowlists or policies can suppress pairing codes, so the platform page's pairing example is not a promise for every configuration. ~/.hermes/.env (replace with your identities): ``` BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567 ``` Inspect requests if using pairing: ``` hermes pairing list ``` Approve a recognized sender: ``` hermes pairing approve bluebubbles <CODE> ``` Optional group gate, merge into ~/.hermes/config.yaml: ``` platforms: bluebubbles: enabled: true extra: require_mention: true ``` Leave `BLUEBUBBLES_ALLOW_ALL_USERS` unset. Authorized people can use the agent's configured tools, which may include terminal access. Without mention gating, the docs say Hermes answers every authorized direct or group message. With it enabled, groups need a matching wake word such as Hermes or @Hermes agent. Direct messages still work normally; a mention does not grant sender access. ### Check both network directions Hermes calls `BLUEBUBBLES_SERVER_URL` to send messages through the Mac. In the other direction, BlueBubbles calls a webhook on Hermes to report new messages. A webhook is an HTTP callback carrying an event. Reaching the Mac's API does not establish that the Mac can reach this callback. Hermes registers the webhook automatically when it connects. Do not create one manually as a normal setup step. The documented default listener is `127.0.0.1:8645`, with path `/bluebubbles-webhook`. This loopback address is suitable when Hermes and BlueBubbles share a machine. If they run on separate machines, set `BLUEBUBBLES_WEBHOOK_HOST` in `.env` to an address on the Hermes host that the Mac can reach, then restart the gateway. Check routing and firewall access to the configured port. The default port is 8645. A loopback listener cannot be reached from the other machine. For the separate-machine setup, use a specific LAN address of the Hermes host, such as `192.168.1.20`, for `BLUEBUBBLES_WEBHOOK_HOST`. Do not use `0.0.0.0`, `::`, `127.0.0.1` or `localhost`: the adapter registers those as `http://localhost:8645/...`, which points back to the Mac. This follows the official adapter code; shared-listener profiles use the gateway's logged profile URL instead. The callback includes `?password=...` because the BlueBubbles webhook API does not support custom headers. Keep the connection and its URLs private. This guide does not prescribe exposing that listener directly to the public internet. ### Start the gateway and send your first message Start the gateway with the Mac, Messages and BlueBubbles running. Inspect the gateway log in a second terminal. Look for both a BlueBubbles connection and successful webhook registration. Send a short iMessage from another device using an allowed sender identity to the Mac's Messages account. Check that Hermes logs the incoming message and returns a reply. A webhook row or successful setup wizard alone does not establish delivery. Run the gateway in the foreground: ``` hermes gateway ``` Inspect the gateway log: ``` hermes logs gateway ``` `Ctrl+C` stops the foreground gateway. Hermes removes its registered webhook on clean shutdown. ### What it can do and the Private API caveat The gateway table marks images, files, reactions and typing for BlueBubbles, but does not mark voice, threads or streaming. The platform page also describes sending and receiving audio, including voice attachments. Keep that distinction rather than treating the table as a complete voice specification. - The page documents text, images, videos and documents. Incoming media is downloaded and cached locally for the agent. Outgoing text has Markdown stripped. - Tapback reactions, typing indicators, read receipts and creating new chats by address require the optional Private API helper. Those features are conditional even though some are marked in the overview table. - Basic text and media without the helper assume BlueBubbles can control Messages in a logged-in foreground macOS session. The docs say reliable sending from a background user or login-screen setup also requires the helper. - Review BlueBubbles' linked helper instructions before choosing that advanced setup. This guide does not install or change the Mac's Private API configuration. ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. After the foreground check, stop that gateway before using the service commands below. The gateway service is launchd on macOS, systemd on Linux, or a logon Scheduled Task on Windows. This manages Hermes, not BlueBubbles or the Mac's Messages login. Install the gateway service: ``` hermes gateway install ``` Start it: ``` hermes gateway start ``` Check it: ``` hermes gateway status ``` Keep the Mac awake, the correct Messages account signed in, BlueBubbles running and the Hermes host online. If either host is asleep or off, replies cannot complete through this route. See [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md). If Hermes runs on Windows, its Scheduled Task does not supervise a later gateway crash. Check status if replies stop. Leave `BLUEBUBBLES_HOME_CHANNEL` empty until ordinary sending is reliable. The docs warn that restart notifications and recovered replies can pile up when Mac-side sending fails. ### If it doesn't answer - Cannot reach server: check the Mac is on, BlueBubbles is running, and the configured URL and password match the intended server and Apple ID. - No incoming event: inspect `hermes logs gateway` for webhook registration errors. On separate hosts, check the callback bind address and Mac-to-Hermes reachability. Only inspect Settings, API, Webhooks in BlueBubbles if the log indicates registration failed. - Setup succeeded but no adapter: check `hermes config get platforms.bluebubbles.enabled`. An explicit false setting wins over saved credentials. - Sends hang or recovered replies repeat: inspect Mac-side AppleScript permissions and whether the BlueBubbles user is in the foreground. Do not repeatedly restart into a failing home-channel delivery loop. - Duplicate replies: check for two active iMessage bridges. The platform page also records a separate session-addressing issue, so duplicates are not always fixed by configuration. Follow its linked issue reports if the problem remains. - Check [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) for the shared gateway checklist, and [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md) if processing finished but the reply did not arrive. ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes iMessage with BlueBubbles docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/bluebubbles) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [How to set up Hermes Agent on iMessage with Photon](https://hermeswatcher.com/learn/hermes-agent-imessage-photon-setup.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) - [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md) - [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md) ### Related tools - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) ### Sources - [BlueBubbles iMessage setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/bluebubbles) - [BlueBubbles setup source snapshot](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/bluebubbles.md) - [Photon iMessage setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/photon) - [Messaging gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) - [Gateway access policy source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L730-L773) - [plugins/platforms/bluebubbles/adapter.py](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/plugins/platforms/bluebubbles/adapter.py) ## How to set up Hermes Agent on WhatsApp with the Business Cloud API > Connect business WhatsApp to Hermes with a Meta app, signed HTTPS webhook and allowlist. Understand the 24-hour delivery window. URL: https://hermeswatcher.com/learn/hermes-agent-whatsapp-business-cloud-api-setup Last reviewed: Oct 29, 2026 ### What you need This guide covers the `whatsapp_cloud` adapter, which connects Hermes to Meta's official business messaging API. It is separate from the QR-linked Baileys bridge in [How to set up Hermes Agent on WhatsApp with the Baileys bridge](https://hermeswatcher.com/learn/hermes-agent-whatsapp-setup.md). It does not use a Node.js bridge or QR pairing. Compare routes at [messaging platforms](https://hermeswatcher.com/messaging.md). You need a configured Hermes model and a host that stays online. A public HTTPS URL is an encrypted address reachable from the internet. Meta calls that address with a webhook, an HTTP request carrying a message or delivery event. A tunnel can forward the public address to a port on your Hermes host. This walkthrough sets up a private bot for you and named staff. Hermes handles direct chats only. Free-form replies are allowed only within 24 hours of the sender's last message; Hermes does not implement the templates required outside that window. - A Meta Business account, a Meta app with WhatsApp enabled and a linked WhatsApp Business Account, also called a WABA. - A dedicated business phone number and access to its Phone Number ID in Meta's API Setup page. The ID is not the phone number. - An access token, App Secret and webhook verify token. Protect all three like passwords. - A public HTTPS route to the webhook listener, which uses port 8090 and path `/whatsapp/webhook` by default. - Optional ffmpeg on the host's PATH for native outgoing voice-note bubbles. Speech features also need configured speech providers. ### Create the Meta app and collect credentials The official Hermes guide describes these Meta dashboard steps. Open [Meta for Developers: My Apps](https://developers.facebook.com/apps), choose Create App and the use case to connect with customers through WhatsApp, then select a business portfolio. Review Meta's publishing requirements. Open the WhatsApp Quickstart and API Setup, and check that a WABA is linked. Copy the Phone Number ID from below the From selector in API Setup, then generate an access token. Get the App Secret from Settings → Basic. The App Secret authenticates incoming request signatures. The webhook verify token is a separate shared secret for Meta's initial callback check. - Temporary access tokens expire after 24 hours. For ongoing operation, follow the official guide's System User token process in Business settings. - That process creates a system user, assigns the app and WhatsApp assets, then requests `business_management`, `whatsapp_business_messaging` and `whatsapp_business_management`. Check the available token-expiry setting and protect or rotate the result as a long-lived credential. - In development mode, Meta separately restricts recipients. In API Setup, open To → Manage phone number list and verify each test number (up to five in development mode). This is separate from the Hermes allowlist and is not a substitute for it. ### Connect it to Hermes Run the dedicated wizard on the Hermes host. It prompts for credentials, checks their form and prints the follow-up tunnel and Meta-dashboard steps. A successful wizard does not establish that incoming messages or replies reached their destination. Terminal: ``` hermes whatsapp-cloud ``` Generate a verify token, manual setup only: ``` python -c "import secrets; print(secrets.token_urlsafe(32))" ``` For manual setup, use the active profile's .env. The default profile uses `~/.hermes/.env`. Set `WHATSAPP_CLOUD_PHONE_NUMBER_ID`, `WHATSAPP_CLOUD_ACCESS_TOKEN`, `WHATSAPP_CLOUD_APP_SECRET` and `WHATSAPP_CLOUD_VERIFY_TOKEN` to your actual values. Do not substitute a phone number for the Phone Number ID. The wizard generates a verify token. For manual setup, use the manual verify-token command shown here. Save the result as `WHATSAPP_CLOUD_VERIFY_TOKEN`, then enter the same value in Meta. The App Secret and verify token are required for this secure inbound walkthrough, even though plugin metadata labels them optional. Without the App Secret, inbound POST delivery is refused with HTTP 503. Never commit .env or paste real credentials into a chat. ### Choose who can talk to it > **Before you open customer access:** This guide sets up a private bot for you and named staff. If customers can message it, strangers can use your agent and its enabled tools, which can include a terminal on your computer. Before you widen access, read the [official security and command-approval docs](https://hermes-agent.nousresearch.com/docs/user-guide/security) and limit the agent's tools. Keep `WHATSAPP_CLOUD_ALLOW_ALL_USERS` off until you have. An allowlist is the list of senders permitted to ask the agent to do work. Add only the phone numbers you intend to authorize, with country code and no plus sign, spaces or dashes. Replace the example below with your own number. Keep `WHATSAPP_CLOUD_ALLOW_ALL_USERS` disabled on a private bot. Active profile .env, replace the example number: ``` WHATSAPP_CLOUD_ALLOWED_USERS=15551234567 ``` Unknown requests cannot execute agent work without an explicit grant. Approved pairings and other supported grants also matter; an empty allowlist does not revoke them. Do not expect every stranger to receive a pairing code when a restrictive allowlist or policy is set. Meta's development recipient list controls which test numbers can receive messages. Hermes authorization controls incoming agent work. Check both before your first message. A valid signature authenticates Meta's webhook transport, not permission for every sender to use your agent. ### Expose the webhook and subscribe to messages If you need cloudflared, the official guide lists `winget install Cloudflare.cloudflared` on Windows and `brew install cloudflared` on macOS; Linux uses the release binary. If cloudflared is already installed, the official guide gives the quick-tunnel command below. Run it alongside the gateway. The printed HTTPS address forwards traffic to the local listener. This makes the webhook reachable from the internet, so keep signature validation and the allowlist in place. Keep the listener port and tunnel target consistent. `WHATSAPP_CLOUD_WEBHOOK_PORT` defaults to 8090. The documented unset webhook host binds to all interfaces on IPv4 and IPv6. Check firewall and tunnel routing instead of assuming this listener is private loopback. Named profile: under the default multiplexed gateway, a secondary profile's callback is `https://<your-host>/p/<profile>/whatsapp/webhook` on the default profile's shared listener, not port 8090. Use the exact URL logged at startup and target that listener's port. The unprefixed example below is for the default profile. Separate terminal, with cloudflared installed: ``` cloudflared tunnel --url http://localhost:8090 ``` Hermes host: ``` hermes gateway ``` In Meta's WhatsApp Configuration webhook settings, enter the printed HTTPS address followed by `/whatsapp/webhook`, and the exact `WHATSAPP_CLOUD_VERIFY_TOKEN` saved in Hermes. Choose Verify and save. Then subscribe to the `messages` webhook field. Completing callback validation without that subscription does not establish inbound chat delivery. A quick-tunnel address changes when cloudflared restarts. Update Meta's callback address after a change. For a stable deployment, follow the official guide's named-tunnel or existing HTTPS reverse-proxy instructions. Do not expose unrelated Hermes services while arranging this route. Block direct public access to port 8090 with your firewall and allow only your proxy or tunnel to reach it. ### Send a first message and inspect the result From your authorized test phone, send a harmless DM to the business number. Keep the gateway and tunnel terminals open. Check that the message reaches Hermes and that its reply appears in the same conversation. Do not infer success from a saved token or callback handshake alone. Local webhook health, on the Hermes host: ``` curl http://localhost:8090/health ``` The health response can report `verify_token_configured`, `app_secret_configured` and `ffmpeg_present`. It does not establish that a human message was processed or received. The health endpoint is unauthenticated and reports configuration-presence information; restrict its public exposure at the proxy if needed. For home-channel deliveries, the Cloud adapter documents `WHATSAPP_CLOUD_HOME_CHANNEL`. Check the actual configured delivery target. Chat-created jobs default to their origin; a home destination is not a universal override. See [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md). ### What it can do - Text, incoming images, documents and voice notes are documented. Incoming voice notes use your configured speech-to-text provider. - Outgoing images, videos, documents and text-to-speech audio are documented. With ffmpeg available, speech can be converted to a native WhatsApp voice note; otherwise it falls back to an MP3 attachment. - Native buttons support clarification, command approvals and slash-command confirmations, with text fallback. Read receipts and a typing indicator are documented. - The overview table marks voice, images, files and typing for Cloud API. It does not mark threads, reactions or streaming. The current Hermes adapter handles DMs only, even if a Meta account has other platform capabilities. - Local faster-whisper is the usual local transcription engine, but it is unavailable on native Windows ARM64 or Intel macOS (repository package markers); use a hosted speech-to-text provider there. ### Understand the 24-hour delivery limit Meta permits free-form outbound replies within 24 hours of the user's last inbound message. Outside that window, Meta requires an approved message template. The current Hermes Cloud adapter does not implement template sending, so this guide cannot provide a template workaround. A scheduled notification or long-running result can fail with Graph error `131047` after the window closes. The user can send a new DM to reopen the window. Choose another appropriate delivery destination if the task must notify you after a long quiet period. An official API does not remove account, review or delivery requirements. ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. After checking foreground behavior, stop that foreground gateway before starting its installed service. Keep the host, internet connection and tunnel available. If the computer is off or asleep, Hermes cannot process incoming messages or run jobs. A background service does not keep a powered-off host running. Install the gateway service: ``` hermes gateway install ``` Start the service: ``` hermes gateway start ``` Check actual running state: ``` hermes gateway status ``` Apply credential or configuration changes: ``` hermes gateway restart ``` The gateway service does not install or supervise your separate tunnel process. Keep that running using the provider's documented deployment method. Windows Task Scheduler watches the gateway launcher rather than later gateway crashes, so check status and start it again if needed. Rotate compromised access tokens and App Secrets. Keep .env and copied diagnostics private. See [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md) and [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) for host and service choices. ### If it doesn't answer - Callback validation fails: check the current HTTPS address, path, exact verify token and running gateway. Keep the App Secret configured. - No inbound messages: check the `messages` subscription, request signature errors, Hermes allowlist and Meta development recipient settings separately. - Graph error 100: check the Phone Number ID, not the phone number. Graph error 190: check token expiry, revocation and required permissions. - Graph error 131047: the 24-hour window expired. Current Hermes has no template-sending implementation. - Voice transcription is empty: check the configured speech provider and its dependencies or credentials. For the default local provider, request its dependency in the activated, PM-prepared Hermes source checkout with the command below (PM is the Hermes package manager). Missing ffmpeg affects outgoing voice-note formatting rather than granting voice access. - For the wider diagnostic path, see [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) and [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md). Voice transcription fix, activated Hermes source checkout: ``` python -c "import pm; pm.sync_venv(['stt-whisper'], explicit=True)" ``` ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes WhatsApp with the Business Cloud API docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp-cloud) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [How to set up Hermes Agent on WhatsApp with the Baileys bridge](https://hermeswatcher.com/learn/hermes-agent-whatsapp-setup.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) - [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md) - [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md) ### Related tools - [WhatsApp: chat with Hermes from your phone](https://hermeswatcher.com/tools/whatsapp.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) - [Scheduled tasks: automate a proven run](https://hermeswatcher.com/tools/scheduling.md) ### Sources - [WhatsApp Business Cloud API, official Hermes guide](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp-cloud) - [Cloud API guide at the research snapshot](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/whatsapp-cloud.md) - [Gateway operation and service lifecycle](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) - [Gateway authorization and pairing policy (pinned source)](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L653-L773) - [Scheduled delivery options](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) - [Voice mode and speech-provider requirements](https://hermes-agent.nousresearch.com/docs/user-guide/features/voice-mode) - [Gateway feature comparison at the research snapshot](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/index.md#L31-L67) - [website/docs/user-guide/multi-profile-gateways.md](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/website/docs/user-guide/multi-profile-gateways.md) - [pyproject.toml](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/pyproject.toml) ## How to set up Hermes Agent with Open WebUI and the API server > Use Open WebUI with the Hermes API server. Set a strong key, keep loopback private and understand Docker reachability and host tool access. URL: https://hermeswatcher.com/learn/hermes-agent-open-webui-setup Last reviewed: Oct 29, 2026 ### What you need Open WebUI is a browser chat interface. It connects to the Hermes gateway's OpenAI-compatible HTTP API, which accepts requests in the OpenAI client format. Hermes still needs its own model provider and any tool backends your tasks require. Open WebUI does not supply those by itself. The API is an agent runtime, not a pure model proxy. Tools run on the Hermes API-server host. If Open WebUI is on a laptop and Hermes is on a server, terminal commands, file operations, browser tools and local MCP tools operate on that server. They do not gain access to the laptop's workspace. Choose the host and profile before granting access. Compare interfaces at [messaging platforms](https://hermeswatcher.com/messaging.md). For an API client rather than a browser interface, see the [official API server examples](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server). If port 8080 is taken, follow [Open WebUI's documentation](https://docs.openwebui.com/getting-started/quick-start/) to serve on another port. - A working Hermes installation and configured model provider on the intended host. - A private Open WebUI installation, or uv available to follow the vendor's Python launch example below. - A fresh API bearer key. A bearer key grants whoever holds it access to the endpoint, so treat it as a password. - A network route from the Open WebUI backend to Hermes. Start with both on one host when possible, keeping the API on loopback. ### Create a strong key and enable the API Generate a fresh random secret on your own host. Hermes requires `API_SERVER_KEY` to be at least 16 characters and rejects known placeholders, even on localhost. The command below produces a longer random value. Never use a short example key from a quick start. Enable the API only in the default profile. For a secondary profile served by it, follow the named-profile instructions under access below. Generate the private API key, requires OpenSSL: ``` openssl rand -hex 32 ``` Enable the API server: ``` hermes config set API_SERVER_ENABLED true ``` Save the generated key with `hermes config set API_SERVER_KEY <your-generated-key>`, which writes the secret to the active profile's `.env`. The default profile uses `~/.hermes/.env`. Use that same value later in Open WebUI. Keep it out of Git, browser-side JavaScript, screenshots and shared logs. Do not substitute a model-provider key for this separate client-access key. `API_SERVER_HOST` defaults to `127.0.0.1` and `API_SERVER_PORT` to `8642`. Loopback means only programs sharing that host's network can connect directly. Keep that default for a same-host setup. A key is required even there. Restart an already-running gateway after changing configuration. ### Start Hermes and check the local endpoint Start the gateway in the foreground so you can inspect startup errors. If a managed gateway is already running, use `hermes gateway restart` rather than launching another copy. First foreground launch: ``` hermes gateway ``` In another terminal on the Hermes host: ``` curl -s http://127.0.0.1:8642/health ``` Authenticated model list, replace the key (official Open WebUI guide): ``` curl -H "Authorization: Bearer <your-API_SERVER_KEY>" http://127.0.0.1:8642/v1/models ``` Look for the API listener at `http://127.0.0.1:8642`. Check `/v1/models` with an Authorization header whose value is `Bearer ` followed by your actual `API_SERVER_KEY`. It should list the profile name, or `hermes-agent` for the default profile. A health response alone does not check authenticated model listing. If the listener refuses to start, inspect the key-strength error rather than weakening authentication. A 401 from model listing means the presented key or routed profile does not match. Check the active profile and saved key on both sides without sharing them. ### Start Open WebUI and connect it For a same-host Python setup with uv already installed, the vendor quick start gives the launch commands below. Choose the one for your operating system. `DATA_DIR` is where Open WebUI keeps chats and settings. macOS or Linux, vendor uv launch example: ``` DATA_DIR=~/.open-webui uvx --python 3.12 open-webui@latest serve ``` Windows PowerShell, vendor uv launch example: ``` $env:DATA_DIR="C:\open-webui\data"; uvx --python 3.12 open-webui@latest serve ``` The vendor's Python example serves the interface at `http://localhost:8080`. Create the first admin account before allowing anyone else to reach it. Keep the interface private using your host's network controls and retain login requirements. In Open WebUI, open Profile avatar → Admin Settings → Connections → under OpenAI API, the wrench (Manage) → + Add New Connection. Add a connection with URL `http://127.0.0.1:8642/v1` for the same-host Python setup. Enter the exact Hermes `API_SERVER_KEY`, check the connection and save. Include `/v1` in the base URL. Select the profile model and start with Chat Completions, the recommended mode in the Hermes guide. Open WebUI sends requests from its backend to Hermes, so this integration does not need `API_SERVER_CORS_ORIGINS`. Do not enable broad browser origins to solve a backend connection failure. ### Docker and remote reachability Inside a Docker container, localhost refers to the container rather than the host. The Hermes Docker example uses `http://host.docker.internal:8642/v1`, `OPENAI_API_BASE_URL` and `OPENAI_API_KEY`. On Linux, its host mapping example is `--add-host=host.docker.internal:host-gateway`. On Linux, the official page lists host networking: use `--network=host` and `OPENAI_API_BASE_URL=http://localhost:8642/v1`. This keeps Hermes on loopback. With host networking, container port mapping does not apply: Open WebUI listens on its own port directly on the host. A Docker host-name mapping alone does not make a loopback listener reachable. If you change `API_SERVER_HOST` for container or remote access, restrict who can reach that interface with firewall or private-network controls and use encrypted transport across untrusted networks. A public HTTPS URL is an internet-reachable encrypted address; it still needs access controls. Do not expose this terminal-capable API publicly just to make Docker connect. Keep the bearer key required. Follow the linked official guides after choosing the protected network path. - Check authenticated `/v1/models` from the Open WebUI backend's network, not only from a terminal on the Hermes host. - Use the address reachable by that backend and retain `/v1`. `OPENAI_API_KEY` must match the intended profile's `API_SERVER_KEY`. - Existing Open WebUI connection settings are stored in its database. Changing container environment variables alone may not replace a saved URL or key. Edit the saved connection in the Admin UI; preserve the data volume. - If you are not running Ollama, set `ENABLE_OLLAMA_API=false` or disable Ollama under Admin Settings → Connections. ### Choose who can talk to the agent The API server uses a bearer key rather than a messenger's numeric-user allowlist or DM pairing flow. The equivalent access decision is which trusted users and client backends can use the profile's key and tools. An allowlist means a list of approved people or origins; a browser-origin list controls browser requests, not who possesses the API credential. Keep Open WebUI authentication enabled and grant backend access only to people you trust with that Hermes profile. Do not assume separate WebUI accounts isolate a shared Hermes profile's memory, skills, credentials or files. For each extra profile, put only a fresh `API_SERVER_KEY` in that profile's `.env`. Do not enable `api_server` in it: the default profile's listener serves it at `/p/<profile>/v1`. The default key is rejected on named-profile prefixes. Confirm which profiles the gateway serves and assign only the intended connections to users. Do not copy older per-port or separate-service examples as a required topology. ### Send a first message and understand the features Choose the advertised profile model and send a harmless text prompt. Confirm a final reply appears in that chat and inspect Hermes logs for errors. A green connection check is not enough. If you later check workspace behavior, use a harmless read-only request and confirm that the reported location is the intended Hermes host. - The agent uses that host/profile's configured tools, memory and skills. Streaming can show tool progress before final text. - Chat Completions is the recommended starting mode. Responses is experimental in Open WebUI; the Hermes guide notes that Open WebUI still sends full history rather than relying on `previous_response_id` for continuation. - The gateway overview has no feature-table row for Open WebUI plus API server. Do not infer voice, images, files, reactions or chat-platform threads from another adapter's row. Frontend and model support matter. - The model shown by the endpoint names the profile by default. Bare model names on Chat Completions and Responses do not necessarily select another backend model. See the API reference for configured routes, explicit provider selection and the `direct_model_requests` option. ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. After checking foreground behavior, stop that foreground gateway before starting its installed service. These commands manage Hermes, not Open WebUI. Keep the WebUI backend and protected network route running too. Install the Hermes gateway service: ``` hermes gateway install ``` Start the service: ``` hermes gateway start ``` Check running state: ``` hermes gateway status ``` Apply Hermes configuration changes: ``` hermes gateway restart ``` If the Hermes computer is off, asleep or offline, no agent requests or scheduled jobs can run there. If the Open WebUI backend is down, its chat interface cannot reach the agent even if Hermes is healthy. A service does not keep a powered-off host running. Windows Task Scheduler starts the gateway launcher and does not supervise later gateway crashes. Check the actual process state and start it if necessary. Keep the profile .env and Open WebUI data directory private. See [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md). ### If it doesn't answer - API never listens: check `API_SERVER_ENABLED`, active profile, key length and placeholder rejection, then restart the running gateway. - 401 or invalid key: compare the saved Open WebUI connection key with the intended profile's key. For `/p/<profile>/v1`, use that named profile's key. - No models: retain `/v1`, inspect authenticated `/v1/models`, and check the backend-to-Hermes network path. Docker localhost and loopback binding are different issues. - Saved correction has no effect: update the Open WebUI connection database through the Admin UI. Do not delete chats or its volume as a first repair. - Model appears but no reply: inspect Hermes provider credentials, tool errors and logs. A task may still be using tools; health and connectivity do not establish final completion. - For the wider gateway checklist, see [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md). For scheduled destinations, see [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md). ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes Open WebUI and the API server docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/open-webui) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) - [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md) - [Hermes Agent profiles: separate agents for separate jobs](https://hermeswatcher.com/learn/profiles-separate-agents.md) - [Hermes Agent security: approvals, allowlists, sandboxing](https://hermeswatcher.com/learn/security-model-approvals-and-sandboxing.md) - [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md) ### Related tools - [API server: use Hermes from any OpenAI-compatible client](https://hermeswatcher.com/tools/api-server.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md) ### Sources - [Open WebUI integration, official Hermes guide](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/open-webui) - [Open WebUI guide at the research snapshot](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/open-webui.md) - [API server reference](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server) - [API key strength guard (pinned implementation)](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/platforms/api_server.py#L3908-L3934) - [Multi-profile gateway operation](https://hermes-agent.nousresearch.com/docs/user-guide/multi-profile-gateways) - [Gateway service lifecycle](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) - [Open WebUI vendor quick start](https://docs.openwebui.com/getting-started/quick-start/) - [website/docs/user-guide/multi-profile-gateways.md](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/website/docs/user-guide/multi-profile-gateways.md) - [Open WebUI official uv installation instructions](https://raw.githubusercontent.com/open-webui/docs/main/docs/getting-started/quick-start/tab-python/Uv.md) # Troubleshooting ## Hermes Agent memory not carrying over between sessions > Check the actual write, profile and session boundary before adding more reminders to the prompt. URL: https://hermeswatcher.com/troubleshoot/memory-did-not-persist Last reviewed: Oct 19, 2026 ### Find the missing evidence Start with one concrete fact and the session in which it was supposedly saved. The official guide distinguishes a memory tool write from a conversational confirmation. Inspect the relevant memory file or tool result: if the entry is absent, the save has not been established. Ask for the specific memory write and verify the resulting entry. If the entry exists, compare the profile used by the writing session with the profile used by the reading session. A named profile has its own memory. Also inspect whether write approval has staged the change and whether memory is enabled. Use the documented pending-memory review flow when appropriate; do not assume a staged entry is already persistent state. ### Test the smallest recovery Once the entry is confirmed, start a fresh session and ask for that fact without supplying it again. Current documentation describes memory as a snapshot loaded at session start, so an already-running conversation is a poor test of a new write. Retain the profile name, saved entry and recovery answer together. If the answer remains wrong, check whether an older project instruction or a contradictory source record supplies the competing value. Ask the agent to identify the origin of its answer. Correct the authoritative record rather than piling several incompatible reminders into memory. For detailed project knowledge, store the evidence in files and use memory to point toward them. ### Expected result and limits Recovery is demonstrated when a fresh session in the intended profile can retrieve the correct fact and identify its source. One successful recovery does not prove all memories are current or complete. This diagnostic is documentation-supported; it has not been run against your installation, and UI details may differ by release. ### Related tools - [Carry project knowledge into the next session](https://hermeswatcher.com/workflows/project-knowledge.md) - [Persistent memory: retain compact working knowledge](https://hermeswatcher.com/tools/memory.md) ### Sources - [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) ## Hermes Agent ignoring your project instructions > Verify the active directory, chosen context file and loading evidence before rewriting the rules. URL: https://hermeswatcher.com/troubleshoot/project-instructions-not-loaded Last reviewed: Oct 19, 2026 ### Locate the session's actual project Record where the session started, which project it is working in and the instruction file you expected it to use. The context-file guide documents selection priorities and directory discovery. A file existing somewhere on the machine does not establish that it was selected for this session. In particular, inspect higher-priority files and local overrides before assuming an AGENTS.md edit took effect. Ask the agent to identify the applicable instruction source and quote one harmless, distinctive rule. Compare that answer with the file itself and available loading diagnostics. If the wrong project or directory was used, start from the intended workspace and repeat the small check. Avoid duplicating the same instructions across many unrelated folders. ### Check loading failures Look for a blocked-file notice, a read failure or a truncation marker. A long instruction document can obscure its own essential rules. Reduce the startup guidance to project purpose, key paths and operating constraints, then move detailed reference material into documents the agent can open when needed. If the correct file loaded but behavior still conflicts, use one minimal task that exposes the rule and record the actual action. Ask for the specific reason it departed from the instruction. This separates file discovery from instruction following, which require different repairs. Repeated rewriting without identifying which stage failed makes the result harder to diagnose. ### Expected result and limits The useful evidence is a known applicable file, a successful loading indication and correct behavior on a bounded task. It is not merely the agent saying it understands. This guide uses current context-file documentation; installed releases may implement different priorities. Preserve existing project customizations while inspecting overrides or simplifying guidance. ### Related tools - [Carry project knowledge into the next session](https://hermeswatcher.com/workflows/project-knowledge.md) - [Build a useful GitHub issue review](https://hermeswatcher.com/workflows/github-issue-review.md) - [Context files: give a project durable instructions](https://hermeswatcher.com/tools/context-files.md) ### Sources - [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) ## Hermes Agent scheduled job didn't run > Separate a stopped scheduler, an unwritable store and a failed job before recreating the schedule. URL: https://hermeswatcher.com/troubleshoot/scheduled-job-missed-run Last reviewed: Oct 19, 2026 ### Inspect the scheduler first Record the job identifier, intended timezone, expected run time and active profile. In current Hermes, hermes cron status reports scheduler health and hermes cron list shows job state. Inspect the last successful tick, overdue indicators and any scheduler-host information. An enabled row describes a stored schedule, not proof that an execution started. If the gateway or ticker is unhealthy, restore the correct scheduler service and check again before creating another job. If status reports an unwritable cron store, address its specific disk-space, mount or ownership error. Avoid editing the job database to force a due time; that can hide the original fault and complicate duplicate prevention. ### Distinguish no attempt from a failed attempt Look for an execution record around the expected instant. If none exists, retain the scheduler diagnostics. If an attempt exists, inspect its terminal state and error: provider access, task execution and output generation are different branches from scheduling. Use one bounded manual invocation only after understanding whether a late catch-up or another attempt is already active. Before retrying an externally active task, inspect its destination for partial work. A missing final summary does not prove that no message, file or remote change occurred. Reconcile existing output first so recovery does not duplicate the operation. Prefer updating the existing job by identity over creating a replacement with a similar name. ### Expected result and limits Confirm a new execution receipt, inspect the resulting artifact and verify delivery separately. Current documentation includes catch-up and store-health behavior that older builds may lack. This is a diagnostic sequence, not permission to restart an unrelated gateway or change service ownership without understanding the deployment. ### Related tools - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Scheduled tasks: automate a proven run](https://hermeswatcher.com/tools/scheduling.md) ### Sources - [Scheduled Tasks](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) ## Hermes Agent task finished but no message arrived > The task ran but no message arrived? Check the saved result and intended destination before you run the whole task again. URL: https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery Last reviewed: Oct 29, 2026 ### Establish what completed Find the exact attempt by job identity and time. Inspect whether it produced a final response, a saved artifact or only intermediate tool output. The scheduled-task documentation tracks execution and delivery separately, so a missing notification does not erase evidence of successful work. If there is no usable output, investigate generation first. A valid summary should contain the expected source window, required sections and current data. If an artifact exists, record its location and timestamp before attempting delivery repair. Preserve it so a communication failure does not require repeating expensive research. ### Trace the intended destination Compare the configured destination with the actual platform, account and conversation expected by the user. Inspect `hermes cron list`, `hermes cron runs <job-id> --limit 20` and `hermes cron doctor`. Successful execution with a failed notification records `last_status: delivery_failed` and the reason in `last_delivery_error`. A correct platform name with the wrong conversation identifier is still the wrong destination. Check the target and any available receipt or message readback before replaying a send. Use one explicitly permitted private destination for recovery checks. If a timeout leaves the send outcome uncertain, inspect the conversation before sending again. If output arrived but was empty, stale or truncated, classify that as an output-quality issue rather than a transport failure. Keep generation status and delivery status in the run record so the same symptom leads to the correct repair next time. Check the configured `deliver` value and saved output before blaming the platform. Jobs created in messaging default to `origin`, the conversation where the job was created. Jobs created in the CLI default to `local`, under `~/.hermes/cron/output/`. A bare platform name uses its configured home channel; an explicit chat or topic target selects that destination. `all` expands to configured home channels at fire time. It does not discover recipients, and with no configured homes it provides no targets. Confirm platform delivery limits. WhatsApp Cloud API allows free-form replies only within 24 hours of the user's last inbound message. The current Hermes adapter does not implement the templates required outside that window, so a delayed notification can fail even when generation succeeded. See [How to set up Hermes Agent on WhatsApp with the Business Cloud API](https://hermeswatcher.com/learn/hermes-agent-whatsapp-business-cloud-api-setup.md). Compare destination types at [messaging platforms](https://hermeswatcher.com/messaging.md). For delivery into another bot conversation, use the [official scheduled-task delivery reference](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron). A queued request does not establish that a reply finished. List jobs and delivery status: ``` hermes cron list ``` Inspect one job, replace <job-id>: ``` hermes cron runs <job-id> --limit 20 ``` Inspect scheduling and delivery problems: ``` hermes cron doctor ``` ### Expected result and limits Success means the intended recipient can access the actual artifact and the run record identifies that result. A timer, process exit or agent success sentence alone is insufficient. Channel behavior differs across integrations; consult the specific platform guide when an error identifies a platform constraint. If the Hermes host is off, asleep or disconnected, jobs cannot run there and messages cannot be delivered through its stopped gateway. For human messaging, the allowlist is the list of approved users; check authorization separately from the delivery route. Other routes use their own authentication, such as the API bearer key. Keep tokens and unredacted saved output private when sharing diagnostics. For inbound silence, see [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md). ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes scheduled delivery docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) - [How to set up Hermes Agent on WhatsApp with the Business Cloud API](https://hermeswatcher.com/learn/hermes-agent-whatsapp-business-cloud-api-setup.md) - [How to set up Hermes Agent with Open WebUI and the API server](https://hermeswatcher.com/learn/hermes-agent-open-webui-setup.md) ### Related tools - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Scheduled tasks: automate a proven run](https://hermeswatcher.com/tools/scheduling.md) - [Telegram: reach Hermes from a private bot conversation](https://hermeswatcher.com/tools/telegram.md) - [Discord: keep agent conversation scoped to the right people](https://hermeswatcher.com/tools/discord.md) ### Sources - [Scheduled Tasks](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) - [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) - [WhatsApp Business Cloud API delivery limits](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp-cloud) - [Messaging gateway operation](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) - [Security and access control](https://hermes-agent.nousresearch.com/docs/user-guide/security) ## Hermes Agent MCP tool missing or failing > Separate discovery, connection, authentication and operation failures using one known read-only request. URL: https://hermeswatcher.com/troubleshoot/mcp-tool-missing-or-failing Last reviewed: Oct 19, 2026 ### Classify the first failure Record the server name, active profile, expected tool and first meaningful error. If no tool appears, inspect whether the server is configured and whether tool filters or enabled toolsets exclude it. If discovery succeeds but connection fails, focus on the server process or URL, executable availability and initialization errors before changing the prompt. For an authorization failure, verify which account and scopes the integration actually uses. The official MCP guide documents an explicit hermes mcp login flow for applicable OAuth servers. Complete authentication through the documented flow rather than pasting tokens into chat or copying credentials between unrelated profiles. ### Use a small discriminating check Choose a known object the account is allowed to read. If listing works but opening the object fails, investigate item-level access or an identifier mismatch. If one tool works and another fails, retain both requests and results; that difference is more useful than repeatedly reconnecting the whole server. Distinguish a connection timeout from a tool-call timeout. The current guide documents separate timeout settings for those stages. Increase a limit only when evidence shows legitimate work needs longer, rather than using a large timeout to conceal a dead process. After repair, repeat the same small request and inspect the returned data before resuming a large workflow. ### Expected result and limits A passing check returns the expected object from the intended account through the intended tool. It does not establish write authorization or every server capability. This guide covers Hermes-side diagnosis; server-specific setup and provider permissions require that server's own primary documentation. No third-party server has been tested for this entry. ### Related tools - [Turn a crowded inbox into a review queue](https://hermeswatcher.com/workflows/inbox-triage.md) - [Build a useful GitHub issue review](https://hermeswatcher.com/workflows/github-issue-review.md) - [MCP: connect external tool servers](https://hermeswatcher.com/tools/mcp.md) ### Sources - [MCP Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) - [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) ## Hermes Agent still using the wrong model > Compare effective settings with the running process before editing keys repeatedly. URL: https://hermeswatcher.com/troubleshoot/model-change-not-taking-effect Last reviewed: Oct 19, 2026 ### Compare saved and effective state Record the expected provider and model, the command or interface used, the active profile and what evidence identifies the actual selection. Ask the running system for effective settings rather than trusting a remembered configuration path. The official guide documents hermes config get model and hermes config check for inspecting configuration and stale selections. Check invocation overrides and whether the CLI, desktop session or gateway is reading the same profile. A provider error may prevent the requested model from starting; it is different from a configuration change being ignored. Preserve the exact non-secret error and the requested model identifier before trying a different provider. ### Change one cause at a time If a setting was written to the wrong profile or an unsupported key, correct that specific location. If the running service predates the change, follow the installation's documented reload or restart procedure at a suitable boundary. Start a fresh bounded session and inspect the actual selected provider and model before resuming the original task. Use a task with a short, inspectable result. The model's writing style is weak evidence of identity; rely on configuration diagnostics and available run metadata. Keep a record of old and new effective selections so a later failure can be traced without exposing credentials or full environment dumps. ### Expected result and limits The diagnosis closes when a new attempt records the intended supported provider/model combination and completes its small check. Correct selection does not prove the model is suitable for all tools or tasks. Provider names, identifiers and access rules change, so verify the relevant current provider documentation when authentication or model availability remains the actual failure. ### Related tools - [Build a useful GitHub issue review](https://hermeswatcher.com/workflows/github-issue-review.md) - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) ### Sources - [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) - [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ## Hermes Agent task denied when scheduled > Find the blocked operation and execution policy instead of disabling approvals for every unattended task. URL: https://hermeswatcher.com/troubleshoot/unattended-task-permission-denied Last reviewed: Oct 19, 2026 ### Compare the two execution surfaces Capture the denied operation, its timestamp and the task's profile. Compare the working interactive attempt with the scheduled attempt: account, working directory, enabled tools, credentials and permission policy. The current security guide documents separate behavior for dangerous commands in unattended contexts. A task that can ask a person in chat may have no equivalent approval path during a scheduled run. If the command is unnecessary, replace it with a smaller permitted operation that achieves the same authorized result. If the task needs additional account access, repair the specific integration or filesystem permission after establishing ownership. Avoid treating every permission error as an application approval setting; the operating system or remote service may be the source. ### Make the recurring contract explicit Write down which reads and writes the task may perform, which destinations it may touch, and what should happen if the next step exceeds that boundary. For a report generator, saving a draft and recording a blocked delivery can be a useful partial result. For an externally active task, inspect whether anything already changed before retrying. Test the revised procedure in the same execution mode with a harmless input and a permitted destination. The useful evidence is the actual operation completing under the intended policy. Keep the denial and repair explanation with the run so the next maintainer knows why the boundary exists. ### Expected result and limits Do not switch all cron commands to automatic approval merely to make a status indicator green. Approval settings do not replace clear task authorization. This guide describes a diagnostic pattern supported by current security documentation; it does not grant access, approve an external action or prove the safety of a custom script. ### Related tools - [Turn a crowded inbox into a review queue](https://hermeswatcher.com/workflows/inbox-triage.md) - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Scheduled tasks: automate a proven run](https://hermeswatcher.com/tools/scheduling.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) ### Sources - [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) - [Scheduled Tasks](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) ## Hermes Agent terminal can't find files or programs > Check where the command actually runs, then verify paths and dependencies inside that environment. URL: https://hermeswatcher.com/troubleshoot/terminal-cannot-find-files-or-programs Last reviewed: Oct 19, 2026 ### Identify the actual execution environment Record the selected terminal backend, working directory, account and exact failing path or executable. Hermes can execute terminal work locally or through another environment. A file visible in your desktop file manager may be absent from a container or remote host. Start with a read-only identity and directory check inside the same terminal tool that failed. If the file exists there, inspect the literal path, permissions and filename. If it does not, determine whether the workflow intended a mount, a copy or remote retrieval. Do not create an empty replacement file just to silence the error: that can let a later step produce a convincing but meaningless result. ### Check dependencies without changing the whole system For a missing executable, inspect the command resolution and version in that environment. Compare the service's environment with your interactive shell rather than assuming they share a PATH. The tools guide also notes that non-interactive shell startup can behave differently from a normal terminal. Retain the first meaningful error and the smallest command that reproduces it. Install or repair dependencies only through the supported method for that deployment, once the missing component is identified. Keep existing project files and configuration intact. Repeat the original read-only check, then run the smallest useful task before restarting a large workflow. Record where the resulting artifact was actually saved. ### Expected result and limits Success means the intended execution environment can open the required input, resolve the required program and produce an inspectable output. It does not establish that files persist across container replacement or host restart. Backend behavior and installation ownership vary, so consult the current platform and backend documentation before migrating files or changing runtime installation. ### Related tools - [Carry project knowledge into the next session](https://hermeswatcher.com/workflows/project-knowledge.md) - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) ### Sources - [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) - [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) - [Platform Support](https://hermes-agent.nousresearch.com/docs/getting-started/platform-support) ## Hermes Agent install or update failed > Symptom-led fixes for a Hermes install script that errors out, a missing hermes command, Python or permission problems, and updates that leave things half-done. URL: https://hermeswatcher.com/troubleshoot/install-or-update-failed Last reviewed: Oct 20, 2026 ### What you see The install one-liner stops with an error; the install finishes but your shell says hermes: command not found; you get an unsupported Python or uv: command not found message; or hermes update completes but the bot still behaves like the old version, settings seem missing, or git reports a dirty tree. ### Likely causes Most install problems are environmental rather than bugs in Hermes: the launcher exists but your shell can't see it, a prerequisite is missing, or an earlier install left a conflicting copy behind. Update problems usually come from running the wrong update path for your install type, or from a long-running gateway that is still executing the old code after the files on disk changed. - Your shell hasn't reloaded PATH after install (the CLI lives in ~/.local/bin on Linux, macOS and WSL2). - The installer was run with sudo, or an old sudo install left /usr/local/bin/hermes behind. - Missing prerequisites: the POSIX source installer needs git, curl, tar and SHA-256 tools; minimal Linux images may lack libatomic for Node.js. - You are on Docker, Desktop, Termux or Nix, where hermes update is the wrong tool. - A gateway kept running old code, or new config options haven't been migrated. ### Check this first - which hermes and ls ~/.local/bin/hermes: is the launcher there? - hermes doctor: diagnoses config and dependency problems and tells you which update method applies to your install. - Look at the install log under logs/install.log in your Hermes data directory, or rerun the installer with --verbose (or HERMES_INSTALL_VERBOSE=1) to stream everything. - hermes update --check: is the checkout actually behind? - tail -f ~/.hermes/logs/update.log: the update's own log, which survives terminal disconnects. - hermes gateway status after an update. ### Fix Match the fix to the symptom: - command not found: run source ~/.bashrc or source ~/.zshrc, or open a new terminal. If your shell config is unusual, add export PATH="$HOME/.local/bin:$PATH" yourself. - Permission denied during install: don't use sudo with the installer. If you installed with sudo before, remove /usr/local/bin/hermes and rerun the standard installer. - Python version errors: current first-party installs use a pinned Python the installer provides (3.14). Don't swap interpreters inside an installed app or container; rerun the installer or hermes doctor instead. - uv: command not found: install uv with its official script, then reload your shell. - Browser or computer-use downloads failed: the installer prints a retry command; you can also restore them later with hermes pm install agent-browser or hermes pm install cua-driver. - Missing config after update: run hermes config check, then hermes config migrate. - Bot still on old code: hermes gateway restart, or rerun hermes update, which retries interrupted restarts. - Docker installs: docker pull the new image and recreate the container with the same data mount instead of running hermes update. ### If it still fails If an update left you in a worse state, check git status --short to see whether local edits were reapplied, and git stash list for edits that were parked. Local commits on main are saved under refs/hermes-update-backups/. To roll back to an older release after the new gateway has written state.db, stop the gateway, check out the older release and restore a pre-update snapshot or a backup with hermes import. When asking for help, hermes dump prints a copy-pasteable setup summary, and the project's GitHub issues are the place to report installer bugs. ### Related guides - [How to update Hermes Agent safely](https://hermeswatcher.com/learn/updating-hermes-safely.md) - [Hermes Agent terminal can't find files or programs](https://hermeswatcher.com/troubleshoot/terminal-cannot-find-files-or-programs.md) - [Where Hermes Agent runs: host vs work environment](https://hermeswatcher.com/learn/where-hermes-runs.md) ### Related tools - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Desktop: manage conversations and inspect artifacts visually](https://hermeswatcher.com/tools/desktop.md) ### Sources - [Installation (official docs)](https://hermes-agent.nousresearch.com/docs/getting-started/installation/) - [Updating and Uninstalling (official docs)](https://hermes-agent.nousresearch.com/docs/getting-started/updating) - [FAQ and Troubleshooting (official docs)](https://hermes-agent.nousresearch.com/docs/reference/faq) - [NousResearch/hermes-agent on GitHub](https://github.com/NousResearch/hermes-agent) ## Hermes Agent bot not responding in your chat app > What to check when your Hermes bot on Telegram, Discord or another chat app stays silent, replies 'unauthorized', or works in DMs but not in groups. URL: https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding Last reviewed: Oct 29, 2026 ### What you see You message your Hermes bot and nothing comes back. Or it replies that you're unauthorized, or it answers direct messages but ignores a group, or it worked yesterday and stopped after a restart or update. ### Likely causes A silent bot can fail at process health, inbound transport, authorization, trigger or session routing, model or tool execution, or outbound delivery. Check each stage with logs and one harmless private message from an authorized account. An authorization failure can look like an outage, so read the log before reinstalling. Use [messaging platforms](https://hermeswatcher.com/messaging.md) to find the route-specific guide. - The gateway process isn't running, or is stuck in a degraded state. - Your user ID isn't on the platform allowlist and you haven't been paired. The gateway denies unknown users by default. - In Telegram groups, privacy mode is on, or telegram.require_mention is filtering messages that don't mention the bot. - The platform adapter is disabled in config.yaml (platforms.<name>.enabled: false overrides credentials in .env), or the circuit breaker paused it. - The bot token is invalid or revoked, or the same token is being used by another profile's gateway. - Both a user and a system service are installed, causing confusing behaviour. ### Check this first - `hermes gateway status`, then `hermes gateway start` if it isn't running. - tail -50 ~/.hermes/logs/gateway.log (on Linux, journalctl --user -u hermes-gateway -f). - hermes status for a one-screen summary of model, gateway and platforms. - `hermes pairing list` shows pairing state. An allowlist is a list of approved users or chats; a restrictive policy may suppress new DM codes. Do not assume a missing code means that the gateway is down. - For Telegram, confirm your numeric user ID with @userinfobot and compare it to `TELEGRAM_ALLOWED_USERS` in ~/.hermes/.env. - /platform list from any working chat to see whether an adapter is paused. - Email: check `EMAIL_AUTHSERV_ID` against the receiving server's topmost Authentication-Results header and confirm the From domain passed authentication. An allowed address alone does not authenticate the sender. Keep sender authentication enabled. - SMS: `SMS_WEBHOOK_URL` must exactly match the public URL configured in Twilio so signature validation can succeed. Check signature errors without disabling validation. - Slack: check scopes, the event subscription for the conversation type and channel membership. Reinstall the app after changing scopes or events. One-to-one DMs use `message.im`; channels also need their channel events and history scopes. - WhatsApp Cloud API: check the App Secret, exact verify-token match, current public callback URL and `messages` subscription. Keep request signature validation enabled. Read [How to set up Hermes Agent on WhatsApp with the Business Cloud API](https://hermeswatcher.com/learn/hermes-agent-whatsapp-business-cloud-api-setup.md). - BlueBubbles: the server must be able to call the Hermes webhook back. A successful Hermes-to-BlueBubbles REST check does not prove reverse reachability. Inspect webhook registration and the explicit adapter enabled setting, then send one allowed message from another device. - Open WebUI: check `/v1/models` using the profile's bearer key from the Open WebUI server's network. A green connection check or `/health` response alone does not prove model listing or agent replies. See [How to set up Hermes Agent with Open WebUI and the API server](https://hermeswatcher.com/learn/hermes-agent-open-webui-setup.md). ### Fix - Not running or 'Degraded': restart with `hermes gateway restart`, which drains active turns first. - Unauthorized: inspect the relevant allowlist and approved pairings. Add only the intended user's ID, or approve a code that was actually issued with `hermes pairing approve <platform> <code>`. Codes expire after one hour. Explicit allowlists can suppress new prompts; keep allow-all disabled. - Ignored in Telegram groups: turn off Group Privacy via @BotFather (/mybots, Bot Settings, Group Privacy) or make the bot an admin, then remove and re-add the bot, because Telegram caches the privacy state at join time. If require_mention is on, mention the bot or reply to it. - Paused platform: check the log and the provider's status page, then /platform resume <name>; it doesn't resume on its own. - Credentials present but adapter won't start: remove platforms.<name>.enabled: false from config.yaml. - Token problems: replace a revoked or invalid token using the platform's official process, update the active profile's .env and restart the gateway. Give each profile its own bot credentials. Keep tokens out of logs you share, screenshots and Git. - macOS gateway can't find tools or LAN devices: rerun `hermes gateway install` to refresh the launchd service. - WSL disconnects: when systemd is unavailable or unreliable, the FAQ documents foreground `hermes gateway` or tmux as a workaround. tmux can survive terminal disconnection, but cannot survive WSL or host termination. Check WSL startup and host power behavior before relying on it for availability. - Windows crash: Task Scheduler supervises the launcher rather than later gateway crashes. Check `hermes gateway status` and use `hermes gateway start` if the process has stopped. A registered task alone does not establish a running bot. - Discord privileged-intent error: enable Message Content Intent. Server Members Intent is needed for username or role allowlists, rather than every numeric-ID-only setup. Check server-channel mention rules separately from authorization. ### If it still fails Run the gateway in the foreground with `hermes gateway` so you can inspect one message from an authorized account. If nothing appears, check adapter state and inbound transport before assuming the model is at fault. Telegram webhook mode needs a reachable public HTTPS `TELEGRAM_WEBHOOK_URL` and `TELEGRAM_WEBHOOK_SECRET`; polling mode does not. Slack Socket Mode and the WhatsApp bridge need outbound access, while WhatsApp Cloud API needs a public webhook. A webhook is an HTTP callback from another service; a public HTTPS URL is an internet-reachable encrypted address. A tunnel can forward that address to the local listener. Proxy connection errors can sometimes be addressed with `gateway.trust_env: false`, after checking the log and required proxy setup. If messages arrive but replies do not, follow [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md). Inspect the served profile set before creating another gateway or service; current multiplexing may already own the bot. Keep only the intended service topology. If the host is off, asleep, offline or WSL has stopped, Hermes cannot process messages or scheduled jobs. Restarting the app on your phone does not restart the host. Protect credentials during diagnosis and use a single permitted private destination for checks. ### Keep it running The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. ### Official docs Reviewed Oct 29, 2026 against the official Hermes docs. [Official Hermes gateway troubleshooting docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) ### Related guides - [All messaging platforms](https://hermeswatcher.com/messaging.md) - [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) - [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md) - [Hermes Agent profiles: separate agents for separate jobs](https://hermeswatcher.com/learn/profiles-separate-agents.md) - [How to set up Hermes Agent on Telegram](https://hermeswatcher.com/learn/hermes-agent-telegram-setup.md) - [How to set up Hermes Agent on Discord](https://hermeswatcher.com/learn/hermes-agent-discord-setup.md) - [How to set up Hermes Agent on WhatsApp with the Baileys bridge](https://hermeswatcher.com/learn/hermes-agent-whatsapp-setup.md) - [How to set up Hermes Agent on WhatsApp with the Business Cloud API](https://hermeswatcher.com/learn/hermes-agent-whatsapp-business-cloud-api-setup.md) - [How to set up Hermes Agent with Open WebUI and the API server](https://hermeswatcher.com/learn/hermes-agent-open-webui-setup.md) ### Related tools - [Turn a crowded inbox into a review queue](https://hermeswatcher.com/workflows/inbox-triage.md) - [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md) - [Telegram: reach Hermes from a private bot conversation](https://hermeswatcher.com/tools/telegram.md) - [Discord: keep agent conversation scoped to the right people](https://hermeswatcher.com/tools/discord.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) ### Sources - [Messaging Gateway (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) - [Telegram setup (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram) - [FAQ and Troubleshooting (official docs)](https://hermes-agent.nousresearch.com/docs/reference/faq) - [Security (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/security) - [Gateway authorization and pairing policy (pinned source)](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L653-L773) - [Discord setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord) - [Email sender authentication](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/email) - [SMS signature validation](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/sms) - [Slack setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/slack) - [WhatsApp Business Cloud API](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp-cloud) - [BlueBubbles setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/bluebubbles) - [Open WebUI setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/open-webui) - [API server authentication](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server) - [Multi-profile gateway operation](https://hermes-agent.nousresearch.com/docs/user-guide/multi-profile-gateways) ## Hermes Agent forgets things mid-conversation > Why a long Hermes session can lose earlier details after context compression, and how to keep the important parts in view. URL: https://hermeswatcher.com/troubleshoot/forgets-mid-conversation Last reviewed: Oct 20, 2026 ### What you see Deep into a long session, Hermes stops honouring an instruction you gave early on, asks again for a file path you already shared, or contradicts a decision from an hour ago. Sometimes it follows a message saying context was compressed, or you notice the session title gained a #2. ### Likely causes Every model has a fixed context window, so a long session can't keep every word forever. Hermes handles this by compressing: it keeps the start and the most recent turns verbatim and replaces the middle with a summary written by a model. That keeps the session usable, but a summary is lossy, and small details from the middle are the first to go. - Automatic context compression ran. By default it triggers at 50% of the context limit (75% for models under 512K), keeps the first 3 and at least the last 20 messages intact and summarises the middle. Details that lived only in the middle can be lost or blurred in the summary. - The compression model's context window is smaller than your main model's. The docs warn that in this case middle turns are dropped without a summary. - Hermes misdetected the model's context length (common with local servers), so compression fires at the wrong point or requests overflow. - You expected something to be remembered in memory, but memory writes only appear in the prompt from the next session. ### Check this first - /context or /usage: how full is the window, and what limit has Hermes detected? The startup line also shows it. - hermes config get compression.threshold and hermes config get auxiliary.compression.model. - hermes sessions list: a numbered continuation (#2, #3) means compression created a linked session. - Is the forgotten detail a durable fact (belongs in memory or a context file) or session-specific (belongs in the conversation)? ### Fix - Restate the key constraint in a fresh message; recent turns are protected from compression. - Put standing instructions in a context file such as AGENTS.md rather than an early chat message. Context files are loaded every session instead of competing with chat history. - Ask Hermes to search the earlier session: session_search returns the raw original messages, not the summary. - If you use a separate summariser, make sure its context window is at least as large as the main model's, or leave auxiliary.compression.model empty to use the main model. - Fix context detection by setting context_length under model: in config.yaml; for local servers, match the server's own context size. - Tune compression.threshold or compression.protect_last_n if your work needs more verbatim history. compression.* changes apply on the next message, even on a running gateway. - Break long work into separate sessions with /new at natural boundaries, and save conclusions as you go. ### If it still fails If even recent instructions are ignored, the problem is probably not compression: run /status to confirm which model is answering (a fallback provider may have taken over for the turn) and try the same prompt in a fresh session. If you see 'compression could not reduce the rebuilt request', the docs say the server's real window is likely smaller than configured. For very long-running projects, consider an external memory provider or a project record file the agent updates explicitly, so important decisions never depend on chat history alone. ### Related guides - [Hermes Agent sessions: search and resume past work](https://hermeswatcher.com/learn/sessions-and-session-search.md) - [How Hermes Agent memory works (and where it stops)](https://hermeswatcher.com/learn/how-hermes-memory-works.md) - [Hermes Agent memory not carrying over between sessions](https://hermeswatcher.com/troubleshoot/memory-did-not-persist.md) - [Hermes Agent ignoring your project instructions](https://hermeswatcher.com/troubleshoot/project-instructions-not-loaded.md) ### Related tools - [Carry project knowledge into the next session](https://hermeswatcher.com/workflows/project-knowledge.md) - [Persistent memory: retain compact working knowledge](https://hermeswatcher.com/tools/memory.md) - [Context files: give a project durable instructions](https://hermeswatcher.com/tools/context-files.md) - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) ### Sources - [CLI Interface (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/cli) - [Configuration (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) - [Sessions (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/sessions) - [Persistent Memory (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) - [FAQ and Troubleshooting (official docs)](https://hermes-agent.nousresearch.com/docs/reference/faq) ## Hermes Agent rate limits and provider errors > How to read 429s, quota errors, auth failures and stream errors from your model provider, and how retries, credential pools and fallback providers can keep Hermes working. URL: https://hermeswatcher.com/troubleshoot/rate-limits-and-provider-errors Last reviewed: Oct 20, 2026 ### What you see Replies stop with a 429 or rate-limit message, a billing or quota error (402), an auth error (401/403), 'model not found', an HTTP 400 on first run, or a message like 'Could not open a stream to <host> after N attempts'. In messaging apps you may see 'interrupted mid-request' or 'not running or is unreachable'. ### Likely causes These errors come from your model provider, not from Hermes itself, and the status code is the best clue. Some are temporary and worth retrying, some mean you need a different key or more credit, and some will never succeed no matter how often you retry. Hermes treats them differently for that reason, so it helps to know which one you're looking at. - 429: you hit the provider's request or token limits. - 402 or daily quota: billing, credits or plan caps. - 401/403: wrong, expired or mismatched API key, or an OAuth login that needs refreshing. - 400 on first run: usually a model name mismatch or no access to that model; on OpenRouter it can also mean you need credits. - Stream errors: a wrong base_url, a local server that isn't running, or an endpoint rejecting a very large request. - A policy refusal from the provider account itself, which retrying won't fix. ### Check this first - /status: which model and provider actually answered. - hermes config show | head -20, then hermes model to confirm provider and model name. - hermes chat -q "hello" --model <a known-good model> to separate a model problem from a config problem. - hermes auth list <provider>: which credential is active and whether any are cooling down. - logs/agent.log in your Hermes home for the raw error. - hermes doctor if errors persist. ### Fix Hermes already retries before giving up (agent.api_max_retries defaults to 3), and rate-limit waits that name a reset time are capped at 600 seconds per retry. Beyond that: - Occasional 429s: wait and retry with /retry, or switch model with /model. - Sustained 429s: add more keys to a credential pool with hermes auth add <provider>. On a 429 Hermes retries the same key once, then rotates; 402s rotate immediately. Choose a rotation strategy under credential_pool_strategies (fill_first, round_robin, least_used or random). - Provider-wide outages: add a fallback with hermes fallback add, which writes fallback_providers in config.yaml. Each entry needs a provider and a model. Fallback triggers after retries on 429 and 5xx errors, and immediately on 401, 403 and 404. - Key problems: re-run hermes model, or hermes config set OPENROUTER_API_KEY <key> (or your provider's variable), and check ~/.hermes/.env for conflicting keys. - Model not found: pick a valid name from hermes model and set model.default, or use hermes chat --model <name> for one session. - Large-request stream errors: run /compress, or raise the endpoint's request size limit. - Cooldowns stuck after you fixed billing: hermes auth reset <provider>. ### If it still fails Remember that fallback is turn-scoped: each new message starts on the primary again, and fallback fires at most once per turn. If the primary keeps failing you'll bounce every turn, and each switch invalidates the prompt cache, which costs money. In that case switch the default model rather than relying on fallback. Cron jobs pinned to their own provider or model don't fall back at all, so check those separately. For account policy refusals, contact the provider or move to another one. ### Related guides - [Hermes Agent still using the wrong model](https://hermeswatcher.com/troubleshoot/model-change-not-taking-effect.md) - [How to keep Hermes Agent costs down](https://hermeswatcher.com/learn/keeping-costs-under-control.md) - [How to choose a model for Hermes Agent](https://hermeswatcher.com/learn/models-and-effective-configuration.md) ### Related tools - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) ### Sources - [Fallback Providers (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers) - [Credential Pools (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools) - [FAQ and Troubleshooting (official docs)](https://hermes-agent.nousresearch.com/docs/reference/faq) - [Configuration (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) ## Hermes Agent not using your skill > What to check when Hermes ignores a skill you wrote or installed, from file location and frontmatter to platform filters, trust and session timing. URL: https://hermeswatcher.com/troubleshoot/skill-not-being-used Last reviewed: Oct 20, 2026 ### What you see You created or installed a skill, but Hermes does the task its own way, says it has no such skill, or the /skill-name command doesn't autocomplete. Or the skill works in the terminal but not on Telegram. ### Likely causes Hermes doesn't read every skill in full at the start of a session. It sees a compact index of names and descriptions and decides from that whether to open a skill. So a skill can be ignored either because Hermes can't see it at all, or because it can see it but the description doesn't match how you phrased the request. The checks below cover both, starting with the quick ones. - The file is in the wrong place or isn't named SKILL.md, or its YAML frontmatter is malformed. - The skill was added mid-session and the current session hasn't picked it up, or a hub install hasn't taken effect yet. - The description is vague, so the agent doesn't connect it to your request. The agent decides from the index of names and descriptions. - The skill is filtered out: a platforms field excludes your OS, it is hidden on that messaging platform, or requires_toolsets / requires_tools names a toolset that isn't enabled. - A same-named skill elsewhere shadows it (project skills beat local, local beats external_dirs). - It is a project-local skill in a repo you haven't trusted, or it was quarantined by the security scanner. - You're on a different profile; each profile has its own skills folder. ### Check this first - Confirm the path: ~/.hermes/skills/<category>/<skill-name>/SKILL.md (or the profile's own skills folder). - Type / in the CLI and see if the skill appears in autocomplete. - Run hermes skills to check per-platform visibility. - Read the frontmatter: is name set, is description specific, are platforms, requires_toolsets or requires_tools excluding you? - For a repo's .hermes/skills/ or .agents/skills/, have you run hermes skills trust? - hermes -p <profile> if you use more than one profile. ### Fix - Start a new session (/new or /reset) after adding a skill; hub installs can use --now to apply immediately. - Invoke it explicitly with /skill-name <task> to confirm the skill itself works. - Rewrite the description to say what the skill does and when to use it, in the words you'd use when asking. - Remove or adjust restrictive platforms or requires_* fields, or enable the toolset it depends on with hermes tools. - Rename one of two clashing skills so a higher-precedence copy doesn't hide yours. - Trust the repo with hermes skills trust for project-local skills. - For a hub skill, hermes skills check and hermes skills update; hermes skills reset --restore reinstates a bundled skill you broke. ### If it still fails Ask Hermes directly to call skill_view on your skill and summarise it. If it can load it but still skips it, the instructions may be too long or ambiguous; move detail into references/ and keep the procedure short. If skills.write_approval is on, an agent-made edit may be sitting in /skills pending. Finally, remember a skill is guidance, not enforcement: for steps that must happen every time, a scheduled job or explicit slash command is more reliable than hoping the agent recalls it. ### Related guides - [How to write your first Hermes Agent skill](https://hermeswatcher.com/learn/writing-your-first-skill.md) - [Hermes Agent skills vs plugins vs MCP: which to use](https://hermeswatcher.com/learn/skills-plugins-and-mcp.md) - [Hermes Agent ignoring your project instructions](https://hermeswatcher.com/troubleshoot/project-instructions-not-loaded.md) ### Related tools - [Collect content ideas without losing the evidence](https://hermeswatcher.com/workflows/content-research-queue.md) - [Skills: reusable procedures for repeated work](https://hermeswatcher.com/tools/skills.md) - [Plugins: add tools and lifecycle behavior](https://hermeswatcher.com/tools/plugins.md) ### Sources - [Skills System (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) - [Working with Skills (official guide)](https://hermes-agent.nousresearch.com/docs/guides/work-with-skills) - [FAQ and Troubleshooting (official docs)](https://hermes-agent.nousresearch.com/docs/reference/faq) ## Hermes Agent stuck in a tool loop > How to stop a Hermes turn that keeps calling tools or seems frozen, and the documented limits and settings that prevent it happening again. URL: https://hermeswatcher.com/troubleshoot/tool-loop-or-stuck-task Last reviewed: Oct 20, 2026 ### What you see Hermes keeps running the same command or re-reading the same file, polls a background process over and over, or sits on one step with no visible progress. In a messaging app the bot goes quiet mid-task, or a scheduled job never finishes. ### Likely causes An agent turn is a loop of model calls and tool calls that ends when the model decides it's done. If it never reaches that point, or a single tool call never returns, the turn appears stuck. Usually the agent is either waiting on something outside its control or retrying a goal it can't satisfy. - The goal is ambiguous or unachievable, so the model keeps trying variations. - A command is waiting for input it will never get (an interactive prompt, a pager, sudo on the gateway, which has no terminal). - A long-running command or background process is still going, and the agent is waiting on it. - An approval prompt is waiting for an answer; unanswered prompts are denied after the timeout (300 seconds by default). - A subagent is still running in the background, or hit its own iteration limit. - The provider stream has stalled. ### Check this first - Is there a pending approval prompt? In chat, answer with /approve or /deny. - In the CLI, watch the tool progress lines; ~/.hermes/logs/tool_calls.log is used when display.tool_progress is set to log. - Ask the agent to run process(action="list") or check background processes, if it started any. - /status to confirm the model and provider; tail ~/.hermes/logs/gateway.log for gateway turns. - For subagents, check their live transcripts or ask the parent to list its children. ### Fix First, stop the turn: - CLI: Ctrl+C stops the current operation (pressing it twice within 2 seconds forces an exit), or type /stop to cancel the turn and its foreground work. - Messaging: send /stop. Ordinary follow-up messages redirect the turn by default but do not cancel background children; /stop does. - Redirect instead of stopping: with display.busy_input_mode set to steer, your message is injected after the next tool call, which is a gentle way to say 'stop retrying that, try X'. ### Prevent it next time - Cap tool-calling iterations per turn with agent.max_turns in config.yaml or --max-turns <N>. When the budget runs out the agent gets one grace call to wrap up. - Keep terminal.timeout (180 seconds by default) sensible, and run genuinely long jobs in the background so the agent can be notified on completion rather than polling. Hermes already switches to completion notifications if it polls a silent process twice in a row. - Cap subagents with delegation.max_iterations (default 250) and, if needed, delegation.child_timeout_seconds for inactivity. - agent.session_stall_timeout (300 seconds by default) is a notify-only watchdog that tells you when a session stalls. - Avoid interactive commands; ask for non-interactive flags, and don't rely on sudo through the gateway. - Write clearer goals with a stopping condition: 'try at most two approaches, then report what failed'. ### If it still fails If the gateway itself has frozen, its watchdog exits the process when the event loop stalls so the service supervisor restarts it; hermes gateway restart does the same deliberately. Note that a restart does not resume running subagents, so rerun those tasks. If a particular model repeatedly loops on tool calls, test the same prompt in a fresh session with another model; the docs' Nous Portal guide, for example, notes that Hermes-4 models are chat models not suited to agent loops. ### Related guides - [Hermes Agent subagents and delegation explained](https://hermeswatcher.com/learn/subagents-and-delegation.md) - [Hermes Agent scheduled job didn't run](https://hermeswatcher.com/troubleshoot/scheduled-job-missed-run.md) - [Hermes Agent task denied when scheduled](https://hermeswatcher.com/troubleshoot/unattended-task-permission-denied.md) - [Hermes Agent rate limits and provider errors](https://hermeswatcher.com/troubleshoot/rate-limits-and-provider-errors.md) ### Related tools - [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md) - [Build a useful GitHub issue review](https://hermeswatcher.com/workflows/github-issue-review.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) - [Scheduled tasks: automate a proven run](https://hermeswatcher.com/tools/scheduling.md) ### Sources - [CLI Interface (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/cli) - [Configuration (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) - [CLI Commands Reference (official docs)](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) - [Tools and Toolsets (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) - [Subagent Delegation (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/delegation) - [Messaging Gateway (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) - [Run Hermes Agent with Nous Portal (official guide)](https://hermes-agent.nousresearch.com/docs/guides/run-hermes-with-nous-portal) ## Hermes Agent local model won't start or goes silent > Fix the context-window and tool-calling mismatches behind most local model failures with Ollama, llama.cpp, vLLM and LM Studio. URL: https://hermeswatcher.com/troubleshoot/local-model-context-too-small Last reviewed: Oct 20, 2026 ### What you see You point Hermes at a local server and one of these happens: - Hermes refuses to start and says the server's context window is too small. - The startup line shows something like `Context limit: 2048 tokens`. - Replies are empty, an empty-stream error appears, or the turn ends with `Context length exceeded: compression could not reduce the rebuilt request below the safe threshold`. - The model loses track of the conversation after a few turns, or answers incoherently. - Tool calls show up as JSON text in the reply instead of actually running. - Long prompts time out before the first word appears. ### Likely causes Hermes needs at least 64,000 tokens of context for agent work with tools, and rejects smaller windows at startup. The system prompt and tool schemas take up a large share of the window before you've typed anything. The docs specifically note that Hermes' full default toolset can overflow a 32k window and cause an empty-stream error on llama.cpp-family servers. Most local servers then quietly drop older messages instead of raising an error. The second most common cause is a mismatch between what the server actually serves and what Hermes believes it serves. Ollama's model info reports the model's maximum context, not the `num_ctx` you set, and you can't set context length through the OpenAI-compatible API at all. On llama.cpp, parallel slots split the context, so `-c 64000 -np 4` leaves each slot with only 16k. Tool calls that appear as text mean the server's tool-calling support isn't switched on. ### Check this first - What Hermes thinks: the `Context limit` line at startup, or `/usage` during a session. - What Ollama serves: `ollama ps`, in the CONTEXT column. - What llama.cpp serves: `curl http://localhost:8080/props` and look for `n_ctx` under the default generation settings. - What vLLM serves: the `--max-model-len` value it was started with. - Whether the endpoint answers at all: `curl http://localhost:11434/v1/models` (use your own port) should return a JSON list of models. ### Fix First, raise the context on the server, since that's where it's actually decided. For Ollama, start the server with `OLLAMA_CONTEXT_LENGTH=64000 ollama serve`, set the same variable on a systemd-managed service, or bake it into a model with a Modelfile containing `PARAMETER num_ctx 64000`. For llama.cpp, start with `-c 64000` (and don't split it across parallel slots below the minimum). For vLLM, use `--max-model-len`. Next, tell Hermes the same number. Set `model.context_length` in `config.yaml`, for example `context_length: 64000` beneath your `default`, `provider: custom` and `base_url` lines. For a named custom provider, set it per model under `providers:`. On local endpoints, `model.ollama_num_ctx` is also honoured as the window the server really serves. The two numbers must match: if Hermes believes it has more room than the server provides, requests get truncated. - Tool calls appearing as text: add `--jinja` to llama.cpp, `--enable-auto-tool-choice --tool-call-parser hermes` to vLLM, or the right `--tool-call-parser` to SGLang. For Ollama, confirm the model supports tools with `ollama show <model>`. LM Studio needs version 0.3.6 or later and a model with native tool support. - The window really is tight: start with fewer tools, for example `hermes chat -t file,web`, and switch off unused toolsets with `hermes tools`. - Timeouts during long prompts: Hermes already raises the streaming read timeout for local endpoints. If prompts still time out, set `HERMES_STREAM_READ_TIMEOUT=1800` in `~/.hermes/.env`. - Replies cut off mid-sentence: that's usually the server's own output limit, which Hermes doesn't control, or a full context. `/compress` frees up room. ### If it still fails If you see 'The model server rejected this request as too large, but this conversation is only about N tokens', another request is probably holding a single-slot server (LM Studio and Ollama are common examples). The docs name a background memory review from an earlier session as the usual culprit, which shows up as `thread=bg-review` in `logs/agent.log`. Wait a moment and run `/retry`. If it keeps happening with no other Hermes process running, the server loaded the model with a smaller window than Hermes expects. If Hermes runs in WSL2 and the model server runs on Windows, `localhost` won't reach it under WSL's default networking. Enable mirrored networking (`networkingMode=mirrored` in `.wslconfig`, then `wsl --shutdown`), or use the Windows host's address. If none of this helps, test the endpoint in another client to confirm it really is OpenAI-compatible, then run `hermes doctor`. ### Related guides - [How to choose a model for Hermes Agent](https://hermeswatcher.com/learn/models-and-effective-configuration.md) - [Hermes Agent forgets things mid-conversation](https://hermeswatcher.com/troubleshoot/forgets-mid-conversation.md) - [Hermes Agent rate limits and provider errors](https://hermeswatcher.com/troubleshoot/rate-limits-and-provider-errors.md) - [Hermes Agent still using the wrong model](https://hermeswatcher.com/troubleshoot/model-change-not-taking-effect.md) ### Related tools - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) - [Fallback providers: keep working when your main model fails](https://hermeswatcher.com/tools/fallback-providers.md) - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) ### Sources - [AI Providers: Troubleshooting Local Models (official docs)](https://hermes-agent.nousresearch.com/docs/integrations/providers) - [FAQ: Context length exceeded (official docs)](https://hermes-agent.nousresearch.com/docs/reference/faq) - [Run Local LLMs on Mac (official guide)](https://hermes-agent.nousresearch.com/docs/guides/local-llm-on-mac) - [Quickstart: minimum context (official docs)](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) ## Hermes Agent OAuth login stuck or expired > Diagnose expired or revoked subscription logins, MCP OAuth that never returns, and logins that worked but landed in the wrong Hermes home. URL: https://hermeswatcher.com/troubleshoot/oauth-login-expired-or-stuck Last reviewed: Oct 20, 2026 ### What you see - A 're-authentication required' message in the middle of a session, or a startup warning naming `hermes auth add <provider>`. - A subscription login (Nous Portal, Anthropic, Codex, xAI) that worked yesterday and now fails on every request. - An MCP server's browser login that ends on a 'cannot connect' page at `127.0.0.1`, or times out while waiting for the callback. - Logging in from the terminal worked, but the gateway or cron jobs still behave as if you never did. ### Likely causes Hermes refreshes OAuth tokens by itself and retries after a transient 401. A login only becomes dead when the refresh token itself is rejected for good: you changed your password, revoked access, the session expired, or another program using the same login rotated the token first. Hermes then logs one warning naming the fix and takes the credential out of rotation. It doesn't keep retrying on a timer, so the problem stays put until you sign in again. Loopback OAuth flows, used by remote MCP servers and some plugins, redirect your browser to `127.0.0.1` on the machine running the browser. If Hermes is on a server, that listener isn't on your laptop. Finally, tokens are stored under the Hermes home of the user and profile that ran the login, so a gateway running as another user or profile won't see them. ### Check this first - `hermes auth status <provider>` shows the stored login state, and `hermes auth list` shows every credential in the pool. - `hermes status` lists the providers that have credentials, along with gateway state. - For Nous Portal, `hermes portal info` shows whether you're logged in and which provider is actually active. - For a named profile, run the same commands with `-p <profile>`. Each profile has its own credential home. - Look at the startup output. A benched credential prints its remaining cooldown, and a dead one prints the re-login command. ### Fix For a dead subscription login, sign in again with `hermes auth add <provider>`, for example `hermes auth add nous`, `hermes auth add anthropic --type oauth` or `hermes auth add openai-codex`. For Nous Portal, `hermes portal` or re-selecting it in `hermes model` works too. Any quarantine on the old token clears after a successful login. If a credential is only cooling down after a rate-limit or billing error, `hermes auth reset <provider>` clears the cooldown, and `hermes auth refresh <provider>` proves a grant is still alive and returns it to rotation. For an MCP server on a remote host, run `hermes mcp login <server>` in a fresh terminal. Don't add the server by editing `config.yaml` inside a running session: the automatic reload only waits 30 seconds, which isn't long enough for a browser login. When the browser lands on the failed `127.0.0.1` page, copy the full address-bar URL and paste it at the Hermes prompt. Alternatively, open a tunnel from your laptop with `ssh -N -L <port>:127.0.0.1:<port> user@host`, using the port Hermes printed. If the server supports it, `hermes mcp login <server> --flow device` skips the callback entirely. - Device-code and paste-the-code logins (Nous Portal, xAI Grok OAuth, Anthropic, and Codex by default) don't need a tunnel at all. - Codex in an always-on setup: if every Codex entry is dead, sign in again in that same home, for example `hermes -p <profile> auth add openai-codex`. Don't wait for it to fix itself. ### If it still fails If the login succeeds but the gateway still fails, sign in as the same operating-system user the gateway service runs as, for example `sudo -u hermes -i`, so the tokens land in that user's `~/.hermes`. Restart the gateway afterwards with `hermes gateway restart`. For an MCP login that looks successful but whose tool calls later time out, the provider may not support automatic client registration (Google Drive and Atlassian are the documented examples). Create your own OAuth client in the provider's console, add it to the server's config, and run `hermes mcp login` again. If a tunnel fails with 'Address already in use', something on your laptop is already holding that port. Find it with `lsof -iTCP:<port> -sTCP:LISTEN`, stop it, and reopen the tunnel. ### Related guides - [Hermes Agent rate limits and provider errors](https://hermeswatcher.com/troubleshoot/rate-limits-and-provider-errors.md) - [Hermes Agent MCP tool missing or failing](https://hermeswatcher.com/troubleshoot/mcp-tool-missing-or-failing.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) - [Hermes Agent profiles: separate agents for separate jobs](https://hermeswatcher.com/learn/profiles-separate-agents.md) ### Related tools - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) - [MCP: connect external tool servers](https://hermeswatcher.com/tools/mcp.md) - [Fallback providers: keep working when your main model fails](https://hermeswatcher.com/tools/fallback-providers.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) ### Sources - [Credential Pools: error recovery (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools) - [Nous Portal: troubleshooting (official docs)](https://hermes-agent.nousresearch.com/docs/integrations/nous-portal) - [OAuth over SSH and Remote Hosts (official guide)](https://hermes-agent.nousresearch.com/docs/guides/oauth-over-ssh) - [MCP: OAuth-authenticated servers (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) - [CLI Commands Reference: hermes auth (official docs)](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) ## Hermes Agent on Windows: command not found and other fixes > Work through the documented Windows pitfalls for native installs and WSL2, from PATH and encoding to editors, shell scripts and the login-time gateway task. URL: https://hermeswatcher.com/troubleshoot/windows-specific-problems Last reviewed: Oct 20, 2026 ### What you see - `hermes` isn't recognised right after installing. - Chinese, Japanese or Arabic text shows up as `?`, or a `UnicodeEncodeError` mentions `charmap`. - `WinError 193: %1 is not a valid Win32 application` when a tool or hook runs. - `/edit` or `Ctrl-X Ctrl-E` returns an empty buffer or does nothing. - The gateway doesn't come back after you log in again, or keeps disconnecting under WSL2. ### Likely causes Hermes runs natively on Windows 10 and 11, and the native install keeps its data under `%LOCALAPPDATA%\hermes`. WSL2 is a separate install with its own `~/.hermes`, and the two don't share state. Most native problems come from the gaps between Windows and POSIX: the installer adds Hermes to your User PATH, which existing terminals don't see; old consoles don't handle UTF-8; Windows has no shebang support, so a bare script can't be launched directly; and the gateway runs as a Scheduled Task at logon, which group policy can block. Under WSL2, the usual problem is systemd being missing or unreliable. ### Check this first - Which install you're using: native PowerShell or WSL2. Settings and keys in one don't apply to the other. - In a new PowerShell window, `Get-Command hermes` should point under `AppData\Local\hermes\bin`, and `hermes --version` should answer. - `hermes gateway status` combines the Scheduled Task, any Startup-folder launcher and the live process ID. - Terminal commands run through Git Bash, so make sure Git for Windows (with Bash) is installed. The docs note that MinGit is not a replacement. - `hermes doctor` and `hermes pm doctor` cover most dependency and browser-tool problems. ### Fix Command not found: open a new PowerShell window rather than editing `$env:PATH` by hand. Until then, you can run `& "$env:LOCALAPPDATA\hermes\bin\hermes.exe"`. Garbled characters: make sure `HERMES_DISABLE_WINDOWS_UTF8` isn't set, and use Windows Terminal instead of a very old `cmd.exe`. Editor problems: set `EDITOR` at User scope, not just in the current shell. For VS Code, use `code --wait`, because without `--wait` Hermes gets an empty buffer back. - `WinError 193`: call the `.cmd` form of a tool (for example `npx.cmd`) instead of a hardcoded path to a script. For shell hooks, start the `command` with the script file itself so Hermes can choose the interpreter, such as Git Bash for `.sh`. - Installer error 'The assignment expression is not valid': the downloaded script picked up a byte-order mark. Use the plain `irm | iex` form instead. - Gateway not starting at login: reinstall the task with `hermes gateway install`. If the task is registered but never runs, check why with `schtasks /Query /TN Hermes_Gateway /V /FO LIST`. Group policy can block logon triggers. - WSL2 gateway dropping: run it in the foreground with `hermes gateway run`, inside `tmux` so it outlives the terminal, or enable systemd in `/etc/wsl.conf` with `[boot]` and `systemd=true`, then run `wsl --shutdown` and reopen the terminal. ### If it still fails If YAML in a config file or skill suddenly stops parsing after you edited it on Windows, re-save the file as plain UTF-8 without a byte-order mark. Some editors add one, and it breaks folded YAML values. If you're running a model server on Windows while Hermes runs in WSL2, `localhost` won't reach it under WSL's default networking. Enable mirrored networking or use the host's address. To remove and reinstall cleanly, preview first with `hermes uninstall --dry-run`. Don't delete `%LOCALAPPDATA%\hermes` by hand to repair the app: that folder also holds your configuration, credentials and sessions. Make a backup with `hermes backup` before any data-removal option. ### Related guides - [Hermes Agent install or update failed](https://hermeswatcher.com/troubleshoot/install-or-update-failed.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) - [Hermes Agent terminal can't find files or programs](https://hermeswatcher.com/troubleshoot/terminal-cannot-find-files-or-programs.md) - [Where Hermes Agent runs: host vs work environment](https://hermeswatcher.com/learn/where-hermes-runs.md) ### Related tools - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Desktop: manage conversations and inspect artifacts visually](https://hermeswatcher.com/tools/desktop.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Terminal backends: choose where the agent's commands run](https://hermeswatcher.com/tools/terminal-backends.md) ### Sources - [Windows (Native) Guide (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native) - [Windows (WSL2) Guide (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/windows-wsl-quickstart) - [FAQ: WSL gateway and installation issues (official docs)](https://hermes-agent.nousresearch.com/docs/reference/faq) - [Event Hooks: shell hooks on Windows (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks) # FAQ URL: https://hermeswatcher.com/faq ## Getting started ### What is Hermes Agent? Hermes Agent is an open-source AI agent built by Nous Research. You can chat with it in a terminal, a desktop app, or through messaging apps like Telegram and Discord, and it can run commands, edit files, browse the web and use other tools on your behalf. Its main selling point is a learning loop: it keeps curated memory about you and your setup, saves reusable procedures as skills, and can search its own past conversations. Sources: [Hermes Agent README (GitHub)](https://github.com/NousResearch/hermes-agent) ### Is Hermes Agent free, and how do I get the free models? Yes. The software itself is free and open source under the MIT license. What you pay for is the AI model behind it: usage fees from whichever provider you connect, such as OpenRouter or OpenAI, or a Nous Portal plan if you choose that route. For free models, Nous Portal has a $0 Free plan. Sign in with `hermes model` (pick Nous Portal) or `hermes setup --portal`, choose the Free plan in the browser, then pick a model marked as free tier, such as a variant with a `:free` tag. A fresh Hermes Desktop install can also start you on a free tier before you sign in, and `hermes auth upgrade` in a terminal (or `/login` in a chat) signs you in later. If you run a local model on your own hardware, there are no model fees at all. The free tier is rate-limited, so heavy agent use usually needs a paid plan or your own provider key. Sources: [Nous Portal](https://hermes-agent.nousresearch.com/docs/integrations/nous-portal), [Run Nemotron 3 Ultra free in Hermes Agent](https://hermes-agent.nousresearch.com/docs/guides/run-nemotron-3-ultra-free), [Nous free-tier sign-in code (GitHub)](https://github.com/NousResearch/hermes-agent/blob/main/hermes_cli/anon_auth.py) ### Which operating systems does Hermes Agent run on? What about old Macs, Docker or unRAID? The docs list macOS on Apple Silicon, Windows 10 and 11 (native, no WSL required), Linux, WSL2 and Docker as top-priority (Tier 1) platforms. Nix and Android via Termux (aarch64 only) are best-effort Tier 2. The Windows MSIX desktop package needs Windows 11 22H2 or later; the PowerShell installer covers Windows 10. Intel Macs: stable releases build the desktop bundle for Apple Silicon only, so on an Intel Mac install the CLI with the regular installer and run `hermes desktop`. 32-bit Macs are unsupported. Docker hosts such as a NAS or unRAID box can run the official `nousresearch/hermes-agent` image with a data folder mounted at `/opt/data`; update by pulling a new image. Installing through pip/PyPI, Homebrew or the AUR is not supported. Sources: [Platform Support](https://hermes-agent.nousresearch.com/docs/getting-started/platform-support), [Docker](https://hermes-agent.nousresearch.com/docs/user-guide/docker), [Windows (Native) Guide](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native) ### How do I install Hermes Agent? On Linux, macOS or WSL2, run: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash. On native Windows, run iex (irm https://hermes-agent.nousresearch.com/install.ps1) in PowerShell. Desktop app packages are also available for macOS and Windows. Afterwards reload your shell (for example source ~/.bashrc) and type hermes to start chatting. Don't run the installer with sudo; it installs into your user account. Sources: [Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation), [Hermes Agent README (GitHub)](https://github.com/NousResearch/hermes-agent), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### How do I update Hermes Agent and the Desktop app? For a normal installer-based (source) install, run `hermes update`. It moves you to the latest published stable release, refreshes dependencies, syncs bundled skills to every profile and restarts running gateways. `hermes update --check` previews first, and you can also send `/update` from a connected messaging app. Hermes Desktop checks for updates in the background and offers a one-click update (About > Update now, or Update Hermes in the command palette). The app and the backend it talks to update separately; when you're connected to remote gateways, that button updates the backends first and the app last. Other install types update their own way: Docker users pull a new image and recreate the container, Termux uses `pkg upgrade hermes-agent`, and Microsoft Store installs update through the Store. Check your version with `hermes --version`. Sources: [Updating & Uninstalling](https://hermes-agent.nousresearch.com/docs/getting-started/updating), [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop) ### How do I uninstall Hermes Agent? Run hermes uninstall. For source installs, preview what it will do first with hermes uninstall --dry-run. By default it can keep your configuration and data; --full also removes data, and --data removes user data only. Make a backup first, since these are destructive. Desktop and package installs are removed with their own tools, for example Windows Settings for the MSIX/Store app or moving the macOS app to Trash. Sources: [Updating & Uninstalling](https://hermes-agent.nousresearch.com/docs/getting-started/updating) ### Can I move over from OpenClaw? Yes. hermes setup detects ~/.openclaw and offers to migrate, or you can run hermes claw migrate anytime. Add --dry-run to preview, or --preset user-data to skip infrastructure config (no preset imports secrets without --migrate-secrets). It can bring over your SOUL.md persona, MEMORY.md and USER.md entries, user-created skills (into ~/.hermes/skills/openclaw-imports/), command allowlist, messaging settings, allowlisted API keys and, with --workspace-target, AGENTS.md. Sources: [Hermes Agent README (GitHub)](https://github.com/NousResearch/hermes-agent), [Migrate from OpenClaw](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw) ### How do I switch from Claude Code or Codex to Hermes? Start with `hermes import-agent`. It auto-detects `~/.claude` or `~/.codex`, or you can name one: `hermes import-agent claude-code` or `hermes import-agent codex`. It shows a plan before writing anything, and `--dry-run` never touches disk. For Claude Code it maps global CLAUDE.md into memory, Bash permission rules into `command_allowlist` and `approvals.deny`, MCP servers into `mcp_servers`, and skills into `~/.hermes/skills/claude-code-imports/`. Your project instruction files keep working too, because Hermes reads CLAUDE.md and AGENTS.md as context files. You don't have to choose one or the other. Hermes ships `claude-code` and `codex` skills that let it hand coding work to those CLIs, and `hermes acp` puts Hermes inside editors such as VS Code and Zed. Sources: [Import from Other Agents](https://hermes-agent.nousresearch.com/docs/user-guide/import-from-other-agents), [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files), [ACP Host Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/acp) ### Can I run Hermes on my Android phone? There is an official Termux package for 64-bit ARM (aarch64) Android devices. You add a signed APT repository, install it with `pkg install hermes-agent`, then run `hermes setup`. The package bundles Python, Node.js, ffmpeg and the other runtime pieces, so nothing has to compile on the phone. Don't use the desktop `install.sh` there. Check the Termux page before you start: at the time of writing it carries a warning that the Termux package is currently broken and a fix is in progress. Sources: [Android / Termux](https://hermes-agent.nousresearch.com/docs/getting-started/termux), [Platform Support](https://hermes-agent.nousresearch.com/docs/getting-started/platform-support) ### Should I use native Windows or WSL2? Either works. Native Windows needs no WSL, Cygwin or Docker: the PowerShell installer puts Hermes in `%LOCALAPPDATA%\hermes` without admin rights, and the CLI, TUI, messaging gateway, cron, browser tool, MCP servers and web dashboard all run natively. `hermes gateway install` registers a Scheduled Task so the gateway starts at login. WSL2 suits people who want a POSIX environment, for example fork semantics or Linux-style file watchers. The two installs coexist, because WSL keeps its data in `~/.hermes`. Sources: [Windows (Native) Guide](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native), [Windows (WSL2) Guide](https://hermes-agent.nousresearch.com/docs/user-guide/windows-wsl-quickstart) ### What's the best way to start learning Hermes? If you don't want a terminal, install Hermes Desktop: first-run onboarding gets you to a first message quickly, and you can connect Nous Portal (one sign-in for models plus web search, images, voice and a browser) or pick a provider later. If you like terminals, run the installer, then `hermes setup`. Then follow the official Learning Path page, which has reading orders by level (beginner, intermediate, advanced) and by goal: coding assistant, Telegram or Discord bot, automation, a team of bots, or building your own skills. Beginners need about an hour: install, quickstart, CLI basics and configuration. For help, the official channels are the docs (including the FAQ & Troubleshooting page), GitHub issues and the Nous Research Discord. Sources: [Learning Path](https://hermes-agent.nousresearch.com/docs/getting-started/learning-path), [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### Desktop app, CLI, TUI, web dashboard or chat apps: which interface should I use? They are all front ends to the same agent, with the same config, keys, memory, skills and session history, so you can start a session in one and resume it in another. Pick by situation. Hermes Desktop (`hermes desktop`) is the most complete: multiple chat tabs and windows, file browser and previews, Git review and worktrees, Bot Mode, voice, scheduled jobs and settings without YAML. The CLI (`hermes`) and TUI (`hermes --tui`) suit terminal users and servers. The web dashboard (`hermes dashboard`) is a browser admin panel for config, keys, sessions, logs, cron and skills. Messaging apps through the gateway (Telegram, Discord, Slack and many more) are how you reach Hermes from your phone and run it around the clock. A few commands are surface-specific; for example `/handoff` and `/browser connect` are CLI-only, while `/sethome` and `/restart` are messaging-only. Sources: [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop), [TUI](https://hermes-agent.nousresearch.com/docs/user-guide/tui), [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) ### Can I customize the Desktop app's theme, fonts, layout and language? Yes. Settings > Appearance has theme presets plus a live VS Code Marketplace search that converts any color theme into a Desktop theme, a Chat Font (`desktop.font_family`, including readability fonts like OpenDyslexic once installed) and a Terminal Font for the embedded terminal. Most bindings can be remapped in Settings > Keyboard Shortcuts. For layout, the layout editor (titlebar button or Cmd/Ctrl+Shift+\) offers Simple (chat-first) and Advanced modes and saved layouts, and Hide keeps panes like the in-app Browser or Terminal running while collapsed. The in-app browser has a comment mode for annotating live pages. The app's interface language can be switched in-app, and language packs can add or override UI languages. That only changes interface text; to have the agent answer in another language, just ask it to. Desktop plugins can add your own panes, pages and commands. Sources: [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop), [Language Packs](https://hermes-agent.nousresearch.com/docs/user-guide/features/language-packs), [Desktop Plugin SDK](https://hermes-agent.nousresearch.com/docs/developer-guide/desktop-plugin-sdk) ### What should I use Hermes for first? Start with something that recurs and that you'd otherwise do by hand, because that's where memory, skills and scheduling pay off. Good first projects: a morning briefing delivered to your phone (`/blueprint morning-brief`), a news or paper digest, research fanned out to subagents, turning notes into a weekly plan, or an inbox and calendar helper through the Google Workspace skill. The docs' Automation Blueprints and Guides sections have ready recipes, from a daily briefing bot to GitHub PR review, uptime checks and revenue summaries. On a computer, it's also a full coding and file assistant in your terminal or Desktop. Tell it about yourself and your setup early, so it can write useful memory, and correct it when it gets something wrong; that's how it improves. Sources: [Automation Blueprints](https://hermes-agent.nousresearch.com/docs/guides/automation-blueprints), [Daily Briefing Bot](https://hermes-agent.nousresearch.com/docs/guides/daily-briefing-bot), [Learning Path](https://hermes-agent.nousresearch.com/docs/getting-started/learning-path) ### How do I change models in the CLI or the Desktop app? In a terminal, `hermes model` is the full picker: add providers, sign in or enter keys, and set your default model. Inside a chat, `/model` switches between providers you've already set up, for example `/model provider:model`; add `--global` to keep it beyond the current session. In Hermes Desktop the model picker sits in the composer, left of the microphone. A pick there applies to the current chat and follows you to new chats on that device, but doesn't change your saved default; set that in Settings > Model > Main model and click Apply. Each profile has its own default. Switching mid-conversation makes the next message re-read the whole conversation at full price, so on long chats a fresh session on the new model is often cheaper. Sources: [Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models), [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### Can Hermes set itself up and configure things for me? Largely, yes. Describe what you want in chat and it can create scheduled jobs, install and write skills, and walk you through connections such as Google Workspace, whose setup is agent-driven. The bundled `hermes-agent` skill teaches it how Hermes itself is configured and extended. Some steps still need you: signing in to providers (`hermes model` or Desktop's Providers page), creating bot tokens with services like Telegram's @BotFather, approving risky commands, and confirming blueprint jobs before they're scheduled. Those are deliberate checkpoints. After it changes something, confirm it worked: `hermes cron list` for jobs, `hermes skills list` for skills, `hermes doctor` for overall health. Sources: [hermes-agent skill (GitHub)](https://github.com/NousResearch/hermes-agent/blob/main/skills/autonomous-ai-agents/hermes-agent/SKILL.md), [Google Workspace skill](https://hermes-agent.nousresearch.com/docs/user-guide/skills/google-workspace), [Automation Blueprints Catalog](https://hermes-agent.nousresearch.com/docs/reference/automation-blueprints-catalog) ### How do I install a ready-made agent or profile someone else built? If it's published as a profile distribution (a git repository), install it with `hermes profile install github.com/<owner>/<repo> --alias`. It brings the author's SOUL.md, config, skills, cron jobs and MCP connections; your own credentials, memories and sessions stay on your machine. `hermes profile update <name>` pulls the author's next version and keeps your data, and `hermes profile info <name>` shows its manifest. If someone sends you a single `.tar.gz` export instead, run `hermes profile import <file> --name <name>`, or `/import` in chat, or Import profile… in Desktop. API keys are stripped from exports, so sign in again. Read what you're installing first. A profile can schedule jobs and enable tools, so treat one from a stranger like any other third-party code. Sources: [Profile Distributions](https://hermes-agent.nousresearch.com/docs/user-guide/profile-distributions), [Profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles), [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) ## Comparisons ### Is Hermes good for coding, and can it replace Claude Code or Codex? It's a capable coding agent: it reads, edits and runs code in your projects, follows AGENTS.md or CLAUDE.md, gets real type errors from bundled language servers after each edit, can work in isolated git worktrees, and has `/review` to send a second agent over your diff or PR. Desktop adds a Git review pane with commit, push and PR actions. Claude Code and Codex are coding-focused agents from Anthropic and OpenAI, built around their own models. Hermes is a general-purpose personal agent that works with any provider, and adds memory across sessions, scheduled jobs and messaging-app access. How well it codes depends heavily on the model you pick. You don't have to choose. Hermes ships `claude-code` and `codex` skills to delegate work to those CLIs, `hermes import-agent` brings over an existing Claude Code or Codex setup, and `hermes acp` runs Hermes inside editors like VS Code and Zed. Sources: [LSP (semantic diagnostics)](https://hermes-agent.nousresearch.com/docs/user-guide/features/lsp), [Git Worktrees](https://hermes-agent.nousresearch.com/docs/user-guide/git-worktrees), [Import from Other Agents](https://hermes-agent.nousresearch.com/docs/user-guide/import-from-other-agents) ### What can Hermes do that Claude Code, ChatGPT or other assistants can't? The differences are mostly about where it runs and who controls it. Hermes is open source (MIT) and runs on your own machine, a server or a hosted instance, so it can stay on around the clock, run scheduled jobs while you're away, and answer you on Telegram, Discord, Slack and other apps. It works with almost any model provider or a local model, and keeps its own memory, skills and searchable session history on disk you control. You can switch models without losing that. The trade-off is that you run and configure it. Hosted assistants such as ChatGPT handle that for you, and dedicated coding agents like Claude Code and Codex are tuned for their makers' models. Many people use Hermes alongside them; it can even delegate coding to the Claude Code and Codex CLIs. Sources: [Hermes Agent README (GitHub)](https://github.com/NousResearch/hermes-agent), [What is Hermes Agent? (docs home)](https://hermes-agent.nousresearch.com/docs/), [AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers) ## Memory & context ### How does Hermes remember things between sessions? Built-in memory is two small files in `~/.hermes/memories/`: MEMORY.md for the agent's own notes about your environment and lessons learned, and USER.md for your preferences and communication style. The agent edits them with its memory tool. Every session also lands in a searchable history the agent can look back through. Both files are loaded into the system prompt as a frozen snapshot when a session starts, so something saved mid-session shows up in the next session, not the current one. Starting a new session at natural breaks (a finished task, a new topic) is what lets memory pay off. Memory belongs to a profile, not to an app. The CLI, Desktop and your messaging chats on the same profile share the same memory and session history; a different profile (or Bot Mode bot) has its own. Sources: [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory), [Profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles) ### How much can Hermes remember? Is there a limit? Yes, built-in memory is deliberately small. MEMORY.md is capped at 2,200 characters (about 800 tokens) and USER.md at 1,375 characters (about 500 tokens). The limits are memory.memory_char_limit and memory.user_char_limit in config.yaml. Memory doesn't silently drop old entries when full. The write fails and the agent has to consolidate or remove entries to make room. For longer history, it relies on session search. Sources: [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) ### How do I see, correct or reset what Hermes remembers, and does deleting it make it forget for good? The memory files are plain text, so you can open and edit them directly: `~/.hermes/memories/MEMORY.md` and `USER.md` (inside the profile's folder for other profiles). You can also ask the agent to add, patch or remove an entry, or use `/journey` (Desktop's Star Map) to browse, edit or delete learned memories and skills. Deleting an entry removes it from what is loaded into future sessions, but not from everywhere. Past conversations stay in the session history the agent can search (`hermes sessions delete` or `hermes sessions prune` removes them), and an external memory provider may hold its own copy, so check it there too. To stop memory entirely, set `memory.memory_enabled` and `memory.user_profile_enabled` to false in `config.yaml`. To review writes before they land, set `memory.write_approval: true` and use `/memory pending`, `/memory approve` and `/memory reject`. Sources: [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory), [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands), [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) ### I told Hermes to remember something and it forgot. Why? First check the file. Memory only saves when the model actually calls the memory tool, and weaker or small local models sometimes say "saved" without doing it. Other common causes: writes are staged because write_approval is on, you're on a different profile, memory is disabled, or the session that needs it started before the save. Start a fresh session with /new after saving so the updated snapshot loads. Sources: [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) ### Can I use Honcho, Mem0 or another memory service? Yes. External memory providers run alongside the built-in files, never replacing them. RetainDB and ByteRover ship with Hermes; Honcho, Hindsight, Supermemory, Mem0, OpenViking and Holographic install from the plugin catalog with hermes plugins install <name>. Run hermes memory setup to choose and configure one, hermes memory status to check what's active, and hermes memory off to disable it. Sources: [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory), [Memory Providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers) ### Can Hermes search my old conversations? Yes. Every CLI and messaging session is stored in a SQLite database at ~/.hermes/state.db with full-text search, and the agent has a session_search tool to find and scroll through past conversations. Searching costs no extra LLM calls. You can browse sessions yourself with hermes sessions list, and filter it with options such as --source telegram. Sources: [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory), [Sessions](https://hermes-agent.nousresearch.com/docs/user-guide/sessions) ### How do I continue a previous conversation? Use hermes --continue (or -c) to resume the most recent CLI session; in each terminal it prefers that terminal's own last session. Use hermes --resume <id or title> for a specific one, or --resume latest. Session IDs are shown when you exit and in hermes sessions list. Inside a session, /resume <title> works too. Sources: [Sessions](https://hermes-agent.nousresearch.com/docs/user-guide/sessions) ### What are AGENTS.md and other context files? Context files are project instructions Hermes loads automatically. It looks for .hermes.md or HERMES.md, AGENTS.override.md, AGENTS.md, CLAUDE.md and .cursorrules, and loads only the first type it finds. Inside a git repo, AGENTS.md files from the repo root down to your working directory are combined. SOUL.md is separate. It sets the agent's global personality and lives in your Hermes home folder. Sources: [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) ### SOUL.md, USER.md, MEMORY.md or AGENTS.md: which file should I edit, and how should I structure them? `SOUL.md` in your Hermes home is who the agent is (tone, style, personality, standing instructions), and you edit it yourself. `USER.md` (who you are) and `MEMORY.md` (what the agent has learned) live in `~/.hermes/memories/` and are maintained by the agent through its memory tool. `AGENTS.md` or `.hermes.md` in a project holds that project's rules. Keep each one short and on topic. The memory files are capped (about 2,200 characters for MEMORY.md and 1,375 for USER.md), so they suit durable facts, not long procedures; put step-by-step workflows in a skill, which only loads when needed. Project details belong in that project's AGENTS.md, not in SOUL.md. A common mix-up: facts about yourself written into `SOUL.md` never feed `USER.md`. To have them remembered, just tell the agent. For a temporary change of tone, use `/personality` instead of editing files, and start a new session after editing SOUL.md so it loads cleanly. Sources: [Which File Does What?](https://hermes-agent.nousresearch.com/docs/user-guide/which-file-does-what), [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory), [Personality & SOUL.md](https://hermes-agent.nousresearch.com/docs/user-guide/features/personality) ### Why does Hermes lose track in long sessions, and what does “context is over the compression threshold” mean? Long conversations fill the model's context window, so Hermes compresses older history automatically, by default at 50% of the context limit (`compression.threshold`). Run `/context` (or click the context meter in Desktop) to see what is filling the window: system prompt, tool schemas, skills, MCP, memory and the conversation itself. `/context all` adds per-skill and per-toolset costs. The warning “Context is over the compression threshold … but compression is currently blocked” means Hermes wanted to compress but couldn't at that moment, so the session will keep growing until the provider refuses it. Do what it says: `/compress` to retry now, or `/new` to start fresh. Memory and the session history stay searchable after a reset. To prevent it, start a new session when you switch tasks, use `/compress here` to keep the latest exchanges verbatim, and trim MCP servers or toolsets that take a big share. If limits hit surprisingly early, check the context length Hermes detected at startup. Sources: [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands), [Troubleshooting: My Agent Feels Dumber](https://hermes-agent.nousresearch.com/docs/guides/troubleshooting-agent-quality), [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) ### How do I hand Hermes a file, a git diff or a web page in my message? Use an @ reference. `@file:path/to/file.py` injects a file (append `:10-25` for a line range), `@folder:` a directory listing, `@diff` and `@staged` your git changes, `@git:5` the last five commits with patches, and `@url:` a fetched web page. In the interactive CLI, typing @ offers tab completion. References are capped to protect the context window: a warning at 25% of the context length and a refusal at 50%. Sensitive paths are always blocked from `@file:` to avoid exposing credentials. Sources: [Context References](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-references) ### Do profiles share memory, and can two agents share the same memory? No, not by default. Each profile has its own memory, sessions and skills, and the docs warn against running two agents on one profile or Hermes home: both write memory automatically and load each other's writes at session start, so the stored state degrades with every session. There's no conflict resolution between profiles because they never write to the same store. Run one agent per profile. For genuinely shared memory, connect the profiles to one external memory provider. Honcho, for example, keeps one shared user across all profiles in a workspace while each profile keeps its own view. To seed a new profile with existing memories and sessions, `hermes profile create` accepts `--clone-all`. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Memory Providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers), [Profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles) ### Which memory setup should I use: built-in, Honcho, Hindsight, Mem0, Obsidian or something else? Start with built-in memory. It's always on, costs nothing extra, and together with session search covers most personal use. An external provider is additive: it runs alongside MEMORY.md and USER.md, never replacing them, and only one can be active at a time. Add one when you want richer recall across many sessions or memory shared between profiles. The docs cover Honcho, Hindsight, Supermemory, Mem0, OpenViking and Holographic (from the plugin catalog) plus bundled RetainDB and ByteRover, with a comparison table. Run `hermes memory setup` to pick and configure one, `hermes memory status` to check it, and `hermes memory off` to go back. For a knowledge base you can read and edit yourself, an Obsidian vault works well alongside memory: the bundled Obsidian skill lets the agent read, search and write notes there. Keep durable facts in memory and long notes in the vault. Sources: [Memory Providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers), [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory), [Obsidian skill](https://hermes-agent.nousresearch.com/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian) ### When should I start a new session instead of continuing, and how do I clean up old ones? Start a new one (`/new`) whenever you switch tasks or topics. Shorter sessions are cheaper and faster, and a fresh session is when updated memory loads. Nothing useful is lost: past sessions stay searchable by the agent. Continue a session (`hermes --continue`, `/resume`) when you're picking up the same piece of work. Messaging chats are one long-running session that survives restarts, so on Telegram or Discord the reset is up to you; send `/new` at natural breaks. In a Bot Mode bot's own chat, `/new` compacts the conversation instead of forking it. To tidy up, `hermes sessions prune` deletes sessions by filters such as `--older-than 30d` or `--source telegram` (default: older than 90 days; try `--dry-run` first), `hermes sessions archive` hides matching sessions without deleting, and `hermes sessions optimize` reclaims disk space. Sources: [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory), [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands), [Bot Mode](https://hermes-agent.nousresearch.com/docs/user-guide/bot-mode) ### Can Hermes share memory with Claude Code, Codex or other agents? Not through Hermes' built-in memory files, which belong to one profile. The route is a memory service that both agents connect to. Hermes supports several external memory providers, including Honcho, Supermemory and Hindsight; if the other agent has an integration for the same service, point both at the same account or workspace. The Nous team has said on X that Honcho, Supermemory and Hindsight each offer a Claude Code plugin as well as a Hermes provider. Check each service's own docs for the current integrations. A simpler shared store is a folder of notes both agents can read, such as an Obsidian vault, or project rules in AGENTS.md, which Hermes and many coding agents read automatically. Sources: [Memory Providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers), [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files), [Nous Research team reply on X (October 2026)](https://x.com/i/status/2110631161487560973) ## Skills, plugins & MCP ### What are skills? Skills are on-demand instruction documents, each a folder with a SKILL.md file, that teach the agent how to do a particular task. They follow the agentskills.io open standard. The agent only sees a short list of names and descriptions until it actually needs a skill, which keeps token use down. Every installed skill also works as a slash command, such as /github-pr-workflow. Sources: [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) ### Where are skills stored? All skills live in ~/.hermes/skills/. Bundled skills are copied there on install, and hub-installed and agent-created skills land there too. You can also point Hermes at extra external skill directories. Each profile gets its own skills folder, and hermes update adds newly bundled skills to every profile. Sources: [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### How do I find, choose and install skills and plugins? Skills: use `hermes skills browse` or `hermes skills search <query>`, preview with `hermes skills inspect <id>`, then `hermes skills install <id>`, which runs a security scan first. Official optional skills use ids like `official/security/1password`; other sources include skills.sh, GitHub repos and direct SKILL.md URLs. In Hermes Desktop the Skills tab lists the whole optional catalog with one-click Install. `hermes skills check` and `hermes skills update` keep hub skills current. Plugins: `hermes plugins search <term>` searches the curated plugin catalog and `hermes plugins install <name>` installs the reviewed, SHA-pinned version. In Desktop the same catalog lives under Capabilities > Plugins, with Official, Verified and Community tier filters. There's no single must-have list. Hermes already ships dozens of bundled skills (GitHub, Google Workspace, Obsidian, PDF and Office files, research and more), so start with those, then add an official skill or plugin when a specific task needs it. Disable what you don't use with `hermes skills config` and `hermes tools`, since every enabled tool costs context. Sources: [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills), [Plugin Catalog](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugin-catalog), [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) ### Does Hermes write its own skills or plugins, and how do I make it save a lesson reliably? Yes. With its `skill_manage` tool the agent creates, updates and deletes skills, for example after working out a multi-step workflow, finding a fix after dead ends, or being corrected by you. A background review after a session can also suggest or stage skill changes. The docs call this procedural memory. It's a judgment call by the model, so don't rely on it happening silently. To make it explicit, ask ("save this as a skill") or use `/learn` followed by what to learn from: a folder, a URL, notes, or the workflow you just walked it through. It then writes a SKILL.md to the house standards. It can build plugins too, such as Desktop UI plugins in `~/.hermes/desktop-plugins/`, guided by the bundled `hermes-agent` skill, but review plugin code before you enable it because plugins aren't sandboxed. If you'd rather approve skill changes first, turn on `skills.write_approval`. Sources: [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills), [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands), [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop) ### What's the difference between plugins and MCP servers? Plugins are Python packages in ~/.hermes/plugins/ (a plugin.yaml manifest plus code) that add tools, hooks and integrations directly inside Hermes. Install them with hermes plugins install and enable them with hermes plugins enable <name>. MCP servers are separate programs that speak the Model Context Protocol. Hermes connects to them and uses their tools. Choose MCP when a tool already exists as an MCP server, and a plugin when you're building something Hermes-specific. Sources: [Plugins](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins), [MCP (Model Context Protocol)](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) ### How do I connect an MCP server, including a custom one? From the curated catalog: run `hermes mcp` to pick interactively, or `hermes mcp install <name>` to add one; `hermes mcp login <name>` handles servers that need OAuth. In Hermes Desktop, Capabilities > Connectors has the catalog and an add-server form; after installing, start a new chat and ask for it by name. For a custom server, add it under `mcp_servers` in `~/.hermes/config.yaml`. Local servers use `command` and `args`; remote ones use `url` and optional `headers`. For a remote OAuth server you can also run `hermes mcp add --url <url> --auth oauth <name>`. Hermes discovers the tools at startup, and `/reload-mcp` picks up changes. Use the per-server `tools.include` and `tools.exclude` settings to expose only the tools you need. Sources: [MCP (Model Context Protocol)](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp), [Manage Hermes Cloud with MCP](https://hermes-agent.nousresearch.com/docs/guides/manage-hermes-cloud-with-mcp), [Desktop Connectors pages (GitHub)](https://github.com/NousResearch/hermes-agent/tree/main/apps/desktop/src/app/capabilities/connectors) ### Can Claude Code, Cursor or Codex use Hermes as a tool? Yes. `hermes mcp serve` runs Hermes as a stdio MCP server, so other MCP clients can use its messaging side: list conversations, read message history and send messages across all the platforms your gateway has connected. Add it to the client's MCP config with command `hermes` and args `mcp serve`; the client starts and stops the process. It's handy when a coding agent should post to or read from Telegram, Discord or Slack through your existing Hermes setup. Sources: [MCP (Model Context Protocol)](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp), [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) ### Why don’t all my skills show up in Telegram’s command menu? Telegram allows at most 100 bot commands and also limits the menu's total payload size, so a long skill list can overflow it. Run `hermes skills config` to disable skills per platform (it writes `skills.platform_disabled` in `config.yaml`), then restart the gateway with `hermes gateway restart`, because the menu is rebuilt at startup. Skill descriptions are truncated to 40 characters in the Telegram menu. Disabling skills you don't use there helps with both limits. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### How do web search and fetch work, and do I need a paid key? Is DeepSeek supported? The agent's `web_search` and `web_extract` tools run on a backend you choose with `hermes tools` (in Desktop, Capabilities > Tools > Web Search & Scraping). You don't need a paid key: DDGS (DuckDuckGo) needs none and self-hosted SearXNG is free, though both are search-only, and Firecrawl, Exa, Parallel and Tavily have keyless or free options. A Nous Portal plan includes managed search through its Tool Gateway. You can mix providers per capability, for example SearXNG for search and Firecrawl for extraction. For logged-in or interactive pages, the agent uses its browser tools instead. DeepSeek Search & Fetch isn't a built-in backend, but the plugin catalog lists community plugins that add it, such as `deepseek-search-fetch` (`hermes plugins install deepseek-search-fetch`). It needs your own DeepSeek API key and is billed to your DeepSeek balance. Sources: [Web Search & Extract](https://hermes-agent.nousresearch.com/docs/user-guide/features/web-search), [Nous Tool Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway), [deepseek-search-fetch catalog entry (GitHub)](https://github.com/NousResearch/hermes-agent/blob/main/plugin-catalog/deepseek-search-fetch.yaml) ### How do I make Hermes use a specific skill or tool instead of its default? For a skill, call it directly: every installed skill is a slash command (`/<skill-name>`, or `/skill <name>`), which loads it for that message. Naming it in your request also helps, as does attaching skills to scheduled jobs with `--skill`. For tools, change what's available. Web search and extraction run on whatever backend you pick in `hermes tools` (for example SearXNG or DDGS instead of Firecrawl), and the agent can't fall back to an unselected one. Turn off toolsets you don't want with `hermes tools`, or `/tools disable <name>` for the current session. If a preference should always apply, write it into SOUL.md or the project's AGENTS.md ("use the X skill for Y"). Sources: [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills), [Nous Tool Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway), [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) ### How many skills, tools and plugins can I add before performance suffers? Skills scale well. The agent sees only a short index of names and descriptions and loads a skill's full instructions when it needs one, so hundreds of installed skills cost little. Tools are different: core tool schemas are sent on every call. MCP and plugin tools are deferred by default through Tool Search, which lets the model look up and load a tool's schema only when it needs it, but every enabled toolset still adds weight. To see your real cost, run `/context all` (per-skill and per-toolset costs) or `hermes prompt-size` (the fixed prompt sent on every call). Then disable what you don't use with `hermes tools` and `hermes skills config`. Sources: [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills), [Tool Search](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-search), [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) ### Can Hermes see and control my phone? Not out of the box. Hermes' built-in computer use drives desktops (macOS, Windows, Linux), and your phone is normally just a chat client through Telegram, WhatsApp or another messaging app. The plugin catalog does list community plugins for it. `phone-harness` drives an iPhone through iPhone Mirroring on a Mac, an Android phone over adb, or a cloud phone, and `android-emulator` controls a headless Android emulator on Linux. These are community-tier, not maintained by Nous, and act on your real phone and accounts, so read their disclosures first; phone-harness sends each action to Hermes' approval prompt unless you opt in to auto-run. Android users can also run Hermes itself on the phone through the official Termux package (64-bit ARM only). Sources: [Plugin Catalog](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugin-catalog), [phone-harness catalog entry (GitHub)](https://github.com/NousResearch/hermes-agent/blob/main/plugin-catalog/phone-harness.yaml), [Android / Termux](https://hermes-agent.nousresearch.com/docs/getting-started/termux) ### Should I use Composio for app connections? Hermes has no built-in Composio integration, and it isn't in the official MCP or plugin catalogs. If a service offers an MCP server you trust, you can add it like any custom MCP server under `mcp_servers`. What Hermes does provide: hosted connectors (apps such as Gmail reached through the Nous Tool Gateway, managed with `hermes connectors`), a curated MCP catalog with vendor-hosted servers for Atlassian, Notion, Linear, Stripe and others (`hermes mcp install <name>`), the plugin catalog, and bundled skills like Google Workspace and Notion. Prefer the route that grants the least access for the job, and connect only the accounts the agent needs. Sources: [Nous Tool Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway), [MCP (Model Context Protocol)](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp), [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) ## Models, providers & cost ### Which AI models and providers can I use? Hermes works with any OpenAI-compatible API. The docs list OpenRouter, Nous Portal, OpenAI, Anthropic, Google Gemini, z.ai/GLM, Kimi/Moonshot, MiniMax and others, plus local models through Ollama, vLLM, llama.cpp, SGLang and similar servers. Run hermes model to add providers and pick a model. Inside a chat, /model switches between providers you've already set up. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Hermes Agent README (GitHub)](https://github.com/NousResearch/hermes-agent), [AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers) ### What is Nous Portal and do I need it? Nous Portal is Nous Research's paid subscription service. One OAuth login gives you access to 300+ models plus the Tool Gateway, which handles web search, image generation, text-to-speech and a cloud browser without separate accounts. The docs recommend it for newcomers. It's optional. Hermes works with your own provider keys, and you can mix the two per tool. Set it up with hermes setup --portal and check it with hermes portal info. Sources: [Nous Portal](https://hermes-agent.nousresearch.com/docs/integrations/nous-portal), [Hermes Agent README (GitHub)](https://github.com/NousResearch/hermes-agent), [Nous Tool Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway) ### Can I run Hermes with a local model, and which models fit my GPU or Mac? Yes. The easiest route is Local Models: in Hermes Desktop open Settings > Providers > Local Models, or in a terminal run `hermes model` and choose Local models. Hermes installs a pinned llama.cpp runtime, then prices every catalog model against your machine before you download anything: green means it fits your GPU (or Apple unified memory), amber means it spills into system RAM and runs slower, red means it's too big. A star marks the recommendation. Hermes picks the best quantization that fits, never goes below 4-bit, and gives every recommended model at least a 64K context window, which is also the minimum Hermes needs. Nothing leaves your computer once the model is downloaded. You can still point Hermes at your own server instead: run `hermes model`, choose Custom endpoint, and enter an address such as http://localhost:11434/v1 for Ollama (vLLM, llama.cpp server, SGLang and LocalAI work too). Make sure the context length you set matches what the server actually uses. Very small models can struggle with tool calling, for example claiming to save memory without doing it. Sources: [Local Models](https://hermes-agent.nousresearch.com/docs/user-guide/local-models), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) ### How much does it cost to run? Hermes itself costs nothing. Your costs come from model usage with your chosen provider, an optional Nous Portal subscription, and wherever you host it if not on your own computer. Local models have no usage fees. To keep bills down, run hermes prompt-size to see your fixed prompt cost, disable tools and skills you don't use, use /compress, and start new sessions instead of letting chats grow forever. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Hermes Agent README (GitHub)](https://github.com/NousResearch/hermes-agent) ### Does switching models mid-conversation cost extra? It can. The prompt cache key includes the model, so the first message after a `/model` switch re-reads the whole conversation at full input price. On a long session it can be cheaper to start a new session on the right model, or to delegate the task to a subagent, than to switch back and forth. A plain `/model` switch lasts only for the current session unless you add `--global`. `/model` also lists only providers you have already configured; to add new ones, exit and run `hermes model`. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Troubleshooting: My Agent Feels Dumber](https://hermes-agent.nousresearch.com/docs/guides/troubleshooting-agent-quality) ### What happens when my model provider goes down or rate-limits me? Hermes has layers of resilience. A credential pool, meaning several keys for the same provider, is tried first. Then a fallback chain switches to a different provider and model mid-session on rate limits, server overload, auth failures or connection drops, without losing the conversation. Set it up with `hermes fallback`, which reuses the `hermes model` picker and has `add`, `list`, `remove` and `clear` subcommands. Entries are stored under `fallback_providers` in `config.yaml`, and each needs both a `provider` and a `model`. Sources: [Fallback Providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers), [Credential Pools](https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools) ### How do I see what Hermes is costing me? Inside a session, `/usage` shows token usage, an estimated cost breakdown, context window state and, when the provider reports it, remaining credits or quota. `hermes insights` analyses token usage, cost estimates, tool use and activity over the last 30 days, with `--days` and `--source` filters such as `telegram`. For scripts, `hermes usage` prints account limits for `openai-codex`, `anthropic` or `openrouter` without starting a session, and `hermes prompt-size` breaks down the fixed prompt sent on every call. Sources: [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands), [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) ### Why do side tasks add to my bill, and can I give them, subagents and fallbacks their own models? Hermes uses auxiliary models for side jobs such as context compression, session titles, image analysis, web extraction, approval checks, the skills curator and Kanban planning. By default each one runs on your main chat model, which adds meaningful cost on an expensive reasoning model. You can route each job separately. Run `hermes model` and choose Configure auxiliary models, use Settings > Model > Auxiliary models in Desktop, or set keys like `auxiliary.compression.provider` and `auxiliary.compression.model` in `config.yaml`. The post-session memory and skill review has its own slot, `auxiliary.background_review`. Subagents get their model from `delegation.model` and `delegation.provider` (or Settings > Model > Subagents), and the backup model used when your main one fails comes from `hermes fallback add`. A fast, cheap model is usually fine for compression, titles and approvals. Sources: [Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models), [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration), [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) ### Can I use my Claude Pro or Max subscription in Hermes? There are two documented routes. The official plugin `claude-subscription-directsdk` (`hermes plugins install claude-subscription-directsdk`) runs Hermes turns through the official Claude Code CLI on your Pro or Max plan, with no API key; it needs `claude` installed and logged in, and each turn counts against your subscription's Agent SDK allowance. The catalog marks it experimental. Anthropic OAuth in `hermes model` routes as Claude Code against your account, but the docs say it only works on Claude Max with purchased extra-usage credits, and it uses those credits rather than your base allowance. Pro can't use that path; an `ANTHROPIC_API_KEY` is the alternative. Hermes can't promise how Anthropic treats any account. Check your plan's terms and usage settings in your Anthropic account, which govern quota and overage. Sources: [claude-subscription-directsdk catalog entry (GitHub)](https://github.com/NousResearch/hermes-agent/blob/main/plugin-catalog/claude-subscription-directsdk.yaml), [AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers) ### How can I keep token costs down? First find out what's expensive. `/context` breaks down what fills each request (system prompt, tool schemas, skills, MCP, memory, conversation), `hermes prompt-size` shows the fixed cost sent on every call, and `hermes insights` shows usage over the last 30 days. Then trim. Disable toolsets and MCP servers you don't use (`hermes tools`), start a new session with `/new` when you switch tasks instead of letting chats grow, and `/compress` long ones. Move side jobs such as compression, titles and approvals to a cheaper model under auxiliary models, and give subagents a cheaper model with `delegation.model`. Avoid needless mid-chat model switches, which re-read the whole conversation at full price, and watch the cache hit rate in Desktop's status bar; a warm cache makes long sessions much cheaper. Script-only cron jobs (`--no-agent`) run with no model call at all. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands), [Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models) ### Which model is best for Hermes, and for side tasks like compression or the background review? For the main agent, pick a strong tool-calling, agentic model; Hermes runs a fast loop of tool calls, so that matters more than chat polish. The Nous Portal docs suggest examples such as `anthropic/claude-sonnet-4.6` as a general-purpose agentic model, `openai/gpt-5.5-pro` for reasoning, `google/gemini-3-pro-preview` for huge context and `deepseek/deepseek-v4-pro` as a cost-effective coder. They also say Nous' own Hermes 4 chat models are not recommended inside the agent. For side tasks, a fast cheap model is usually enough. The docs suggest a flash-class model for compression, titles, approvals and web extraction. The background review defaults to your main model, which reuses its warm cache; route it with `auxiliary.background_review` if your main model is expensive. Small local models (roughly under 30B) often fumble tool calls, so use a stronger model at least for setup. Rankings change quickly, so test on your own tasks. Sources: [Nous Portal](https://hermes-agent.nousresearch.com/docs/integrations/nous-portal), [Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models), [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) ### Is there a usage or rate limit, and can I tune how Hermes retries? Hermes itself has no usage cap; limits come from your model provider or plan. `/usage` shows token use and, when the provider reports it, remaining quota, and `hermes usage` prints account limits for some providers without starting a session. On transient errors (rate limits, dropped connections, 5xx) Hermes retries each provider `agent.api_max_retries` times (default 3) before moving to your fallback providers, and waits out a rate limit that names its reset. After retries and fallbacks are spent on an outage, `agent.auto_recovery_cycles` (default 5) keeps waiting and retrying; set 0 to turn it off. If you have a fallback configured (`hermes fallback add`) and want to fail over faster, set `api_max_retries` to 0. On the free Nous tier, a session you're watching ends quickly with the time the limit lifts instead of waiting long. Sources: [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration), [Fallback Providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers), [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) ### How do I fix a Nous Portal subscription or billing problem, such as adding VAT details? Billing and account details are managed on Nous Portal itself, not in Hermes. `hermes portal open` opens the subscription management page, and `hermes portal info` shows your login, subscription and routing status. If something is wrong with a charge or the account, contact Nous: after Send diagnostics, Desktop's error card links to Nous Portal Support, and the Nous Research Discord is the community channel the docs point to. Hermes can't change Portal billing settings for you. If Hermes reports a billing failure mid-chat, Desktop's error card names it as billing and offers Switch provider, so you can keep working on another model while it's sorted. Sources: [Nous Portal](https://hermes-agent.nousresearch.com/docs/integrations/nous-portal), [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### How does using my ChatGPT plan in Hermes work? In `hermes model`, choose ChatGPT or Codex Subscription. Hermes signs in with ChatGPT's device-code login (or `hermes auth add openai-codex --browser` for a browser login), stores the credentials in `~/.hermes/auth.json`, uses Codex models, and can import an existing Codex CLI login. The docs say which plan tiers qualify and how Hermes usage counts against your plan's Codex limits are not yet documented, so watch your usage in ChatGPT. Some models return an error such as “not supported when using Codex with a ChatGPT account”; that's a plan entitlement. The Nous team has said on X that a newer “Sign in with ChatGPT” option links your plan to your Nous Portal account under Linked Accounts, with a usage cap you choose, and that the older Codex login still works. Check Nous Portal for the current flow. Sources: [AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers), [Credential Pools](https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools), [Nous Research team reply on X (October 2026)](https://x.com/i/status/2105190156000952580) ## Messaging & the gateway ### What is the messaging gateway? The gateway is a single background process that connects Hermes to all your configured chat platforms, manages their sessions, runs scheduled cron jobs and delivers voice messages. Supported platforms include Telegram, Discord, Slack, WhatsApp, Signal, Email, Matrix, Microsoft Teams, Home Assistant and many more. Set it up with hermes gateway setup, then run it with hermes gateway or as a service with hermes gateway install and hermes gateway start. Sources: [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) ### How do I connect Hermes to Telegram, and can I run separate bots there? Create a bot with @BotFather to get a token, then run `hermes gateway setup` and choose Telegram. It asks for the token and your allowed user IDs. Or add `TELEGRAM_BOT_TOKEN` and `TELEGRAM_ALLOWED_USERS` to `~/.hermes/.env` yourself. Start the gateway with `hermes gateway` and message your bot. In Hermes Desktop, Messaging has a Create with QR card that creates the bot, detects your user ID and restarts the gateway for you. For several separately addressable bots, give each its own profile and its own BotFather token. A bot token can only be used by one profile at a time, and each profile keeps its own memory, skills and sessions. In groups, Telegram's privacy mode hides ordinary messages from bots until you turn it off in BotFather, and `telegram.require_mention: true` makes a bot answer only when mentioned. Sources: [Telegram](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram), [Profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles), [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop) ### How do I connect Discord or Slack? For Discord, create an application and bot token in the Discord developer portal, turn on Message Content Intent (without it Discord refuses the connection), then run hermes gateway setup and pick Discord. Slack uses Socket Mode, which connects over WebSockets so you don't need a public URL. Create a Slack app, enable Socket Mode, and add the tokens through hermes gateway setup. Sources: [Discord](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord), [Slack](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/slack) ### Can I use Hermes on WhatsApp? Yes. The built-in bridge is based on Baileys, which emulates a WhatsApp Web session, so it needs no Meta developer account or public URL. Run hermes whatsapp and scan the QR code with your phone. Because it isn't the official Business API, the docs warn about ban risk, and each WhatsApp number supports one paired session. A separate WhatsApp Cloud API option also exists. Sources: [WhatsApp](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### How do I control who can use my bot? Use allowlists, meaning specific user IDs such as TELEGRAM_ALLOWED_USERS, or DM pairing. With pairing, an unknown user gets an 8-character code and you approve it with hermes pairing approve <platform> <code>. Codes expire after an hour. unauthorized_dm_behavior can be pair, ignore or decline. An open allow-all mode exists but the docs advise against it. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### How do I keep the gateway running in the background? Run hermes gateway install to install it as a user service (systemd on Linux, launchd on macOS), then hermes gateway start, stop, restart and status to manage it. On Linux, sudo hermes gateway install --system installs a boot-time system service. On WSL, where systemd is often unreliable, the docs suggest hermes gateway run in the foreground, inside tmux, or with nohup. Sources: [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### Why doesn’t my Telegram bot see messages in a group? Telegram bots have privacy mode switched on by default, so in groups they don't receive ordinary messages. Turn it off in @BotFather under Bot Settings, Group Privacy, then remove and re-add the bot, because Telegram caches the setting when a bot joins. Promoting the bot to group admin also works. `TELEGRAM_ALLOWED_USERS` still applies in groups. To stop the bot replying to general chatter, set `telegram.require_mention: true`. Sources: [Telegram](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram) ### How do I stop tool logs and reasoning cluttering my chat? Set `display.tool_progress` in `config.yaml`. `off` shows only the final response, `new` shows brief one-liners as new tool calls happen, `all` includes tool results and `verbose` adds full arguments and outputs. For messaging platforms the docs suggest `off` or `new`. Restart the gateway after editing. Setting `display.tool_progress_command: true` enables `/verbose` in the gateway so you can toggle it per session. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### Can Hermes have its own email inbox? Yes. The docs walk through giving the agent a dedicated mailbox with the bundled Himalaya email skill, which drives the `himalaya` CLI over IMAP and SMTP so the agent can read, search, send and organise mail. Create a fresh account rather than handing over your personal inbox, and use an app password if the provider uses 2FA. This is separate from the Email gateway adapter, which lets people chat with Hermes by emailing it. You can run both, ideally on separate accounts. Sources: [Give Your Agent Its Own Email Address](https://hermes-agent.nousresearch.com/docs/guides/agent-email-address), [Email](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/email) ### Can Hermes work with Gmail or Outlook, and how do I connect email safely? There are a few routes. The bundled Google Workspace skill covers Gmail, Calendar, Drive, Sheets and Docs through your own Google OAuth app; ask Hermes to set it up and it walks you through. With a Nous identity, hosted connectors such as Gmail run through the Tool Gateway and are managed with `hermes connectors` or Desktop's Connectors page. For plain IMAP/SMTP mail (Gmail, Outlook and others), the bundled Himalaya skill works with an app password. To be safe, start with a dedicated mailbox for the agent rather than your main inbox, use app passwords or OAuth (never your main password), and keep risky actions behind approvals. Email content is untrusted input, so be careful about letting it act on instructions found in messages. Separately, the Email gateway lets people chat with Hermes by emailing it; Outlook / Microsoft 365 works there over IMAP and SMTP. Sources: [Google Workspace skill](https://hermes-agent.nousresearch.com/docs/user-guide/skills/google-workspace), [Give Your Agent Its Own Email Address](https://hermes-agent.nousresearch.com/docs/guides/agent-email-address), [Email](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/email) ### Is Telegram or Discord easier to connect, and do they get the same features? Telegram is usually the quickest: one token from @BotFather, and Hermes Desktop can even create the bot from a QR code. Discord needs an application in the developer portal with Message Content Intent turned on. Slack uses Socket Mode, so none of them needs a public URL. The core is the same everywhere: one agent with the same memory, skills, tools, slash commands and cron delivery. Differences come from the platforms. Telegram caps bot command menus at 100 entries, Discord can join voice channels for live conversation, and sessions are keyed differently (Slack shares a thread, Discord a channel, while most others are per user). You can run several at once from one gateway; set each up with `hermes gateway setup`. Sources: [Telegram](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram), [Discord](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### Can I move a live session from my computer to my phone? Yes, from the CLI. Run `/sethome` once in the destination chat (for example your Telegram DM with the bot), then in the CLI session run `/handoff telegram`. The gateway picks the session up with its full history, and your CLI exits with a hint for resuming locally later with `/resume`. It works with Telegram, Discord, Slack, WhatsApp, Signal and Matrix, needs the gateway running, and is refused mid-turn, so wait for the current reply to finish. Separately, Desktop and the CLI share sessions with each other, so on your own machines you can simply resume a conversation in another interface. Sources: [Sessions](https://hermes-agent.nousresearch.com/docs/user-guide/sessions), [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) ## Automation & scheduling ### How do I schedule recurring tasks or use automation blueprints? Just ask in plain language, like "every morning at 9am, send me an AI news summary on Telegram," and Hermes creates the cron job itself. You can also use `/cron add "every 2h" "Check server status"` in chat or `hermes cron create` from the shell, optionally attaching skills with `--skill`. Automation blueprints are ready-made jobs with a couple of fields to fill in. Type `/blueprint` to list them and `/blueprint <name>` (for example `/blueprint morning-brief`) to be asked for what it needs, or use the Blueprints tab on the Cron page in Desktop or the dashboard. Nothing is scheduled until you confirm. Agent-backed jobs run inside the gateway, so keep it running. Results can go back to the original chat, to files, or to other configured platforms, and `/cron` or `hermes cron list` manages what you've created. Sources: [Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron), [Automation Blueprints Catalog](https://hermes-agent.nousresearch.com/docs/reference/automation-blueprints-catalog), [Automation Blueprints](https://hermes-agent.nousresearch.com/docs/guides/automation-blueprints) ### Why aren't my scheduled jobs running? Agent-backed cron jobs run inside the gateway, which checks for due jobs every 60 seconds. If the gateway isn't running, those jobs are skipped with a logged reason and fire on the next tick after you start it with `hermes gateway start`; their schedule is not penalised. Script-only (`no_agent`) jobs are the exception and still run from a bare `hermes cron tick`. `hermes cron list` shows each job's status and reason. Hermes also validates a job before running it. Missing API keys, unready skills or unknown delivery targets set its status to blocked_config and send a single alert. Sources: [Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) ### Can Hermes split work across subagents? Yes. The delegate_task tool starts child agents, each with a fresh, isolated conversation and its own terminal session. Only the child's final summary comes back to the main chat. By default up to 10 can run in parallel. You can give subagents a different model, for instance a cheaper one, with delegation.model and delegation.provider in config.yaml. Sources: [Subagent Delegation](https://hermes-agent.nousresearch.com/docs/user-guide/features/delegation), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### Can a scheduled job run without spending any tokens? Yes, in two ways. No-agent mode runs a script from `~/.hermes/scripts/` on a schedule and delivers its stdout verbatim with no LLM call, and empty output means no message. Create one with `hermes cron create` plus `--no-agent` and `--script`, or just describe the watchdog in chat and Hermes sets it up. For agent-backed jobs, a pre-check script can print `{"wakeAgent": false}` as its last line to skip that run without calling the model. Sources: [Script-Only Cron Jobs](https://hermes-agent.nousresearch.com/docs/guides/cron-script-only), [Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) ### Where can scheduled job results be delivered? Set the job's `deliver` target. `origin` goes back to the chat where the job was created (the default on messaging platforms), `local` saves to `~/.hermes/cron/output/` (the CLI default), and a platform name like `telegram` or `discord` uses that platform's home channel. You can also target a specific chat or Telegram topic, list several targets separated by commas, or use `all`. Send `/sethome` in a chat to make it the home channel. The agent's final response is delivered automatically, so the job prompt doesn't need to send anything. Sources: [Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron), [Telegram](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram) ### When should I use the Kanban board instead of subagents? `delegate_task` works like a function call: the parent waits for an anonymous child and gets a summary back. Kanban is a durable work queue in `~/.hermes/kanban.db` where named profiles with their own memory pick up tasks, hand off, recover from crashes and take comments from you. Use subagents for quick answers that feed the current conversation. Use Kanban when work crosses agents, must survive restarts or might need your input. Start with `hermes kanban init`, keep the gateway running because it hosts the dispatcher, and add tasks with `hermes kanban create`. Sources: [Kanban (Multi-Agent Board)](https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban) ### Can GitHub or other services trigger Hermes automatically? Yes, through the webhook adapter. Enable it with `hermes gateway setup` (it listens on port 8644 by default), then define routes in `config.yaml` or create them with `hermes webhook subscribe`, which returns the URL and HMAC secret to give the service. Incoming events become agent prompts, and results can go to Telegram, Discord, Slack or a GitHub comment. `--deliver-only` skips the agent and forwards the rendered message at zero LLM cost, and `--script` can filter or reshape payloads first. Sources: [Webhooks](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/webhooks), [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) ### What happens if I message Hermes while it's busy, and can I redirect it mid-task? On messaging platforms, a message sent while the agent is working redirects the current turn by default: running tools finish safely and your correction is picked up at the next step. `/stop` is the hard stop. `/busy` (or `display.busy_input_mode` in `config.yaml`) changes that. `queue` holds each follow-up and runs it as its own turn, in arrival order, once the current task finishes. `steer` slips it into the current run after the next tool call. In the CLI, `/steer` and `/queue` (or `/q`) do the same thing one message at a time. In Hermes Desktop, queued messages appear above the composer, where you can edit, send or delete them. The queue lives on the gateway, so it survives an app or gateway restart. Sources: [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/), [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands), [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop) ### Profiles, bots, subagents and Kanban: what's the difference and when do I use each? A profile is a separate agent with its own config, keys, memory, sessions, skills and cron jobs (`hermes profile create <name>`). A Bot Mode bot is simply a profile shown in Desktop's Bots roster with an avatar, a permanent Bot Chat and its own routines. A messaging bot is a platform account (such as a Telegram bot) connected to a profile. A subagent is a temporary child started by `delegate_task` for one job, with a fresh conversation; only its summary comes back. Use it for quick parallel research or side work inside the current conversation. Kanban is a durable task board shared across profiles. Use it when work spans several named agents, must survive restarts, or needs your review between steps. Rule of thumb: one assistant, profiles for separate roles, subagents for quick fan-out, Kanban for pipelines. Sources: [Profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles), [Bot Mode](https://hermes-agent.nousresearch.com/docs/user-guide/bot-mode), [Kanban (Multi-Agent Board)](https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban) ### How do I set up Kanban, and why isn't it in my Desktop sidebar? Create the board once with `hermes kanban init` and keep the gateway running, since it hosts the dispatcher that hands tasks to profiles. Add tasks with `hermes kanban create`, `/kanban` in chat, or the board UI. In Hermes Desktop the Kanban board is a bundled plugin that ships switched off, so it doesn't appear until you enable it in Capabilities > Plugins; it then adds a Kanban page and sidebar entry. The web dashboard (`hermes dashboard`) has a Kanban tab too. The board is only a view. For an agent to create and route tasks from chat, enable the `kanban` toolset on the profile that orchestrates work, for example `hermes -p planner tools enable kanban`, and start a new chat. Leave it off on profiles that only talk to people; workers get their task tools automatically. Sources: [Kanban (Multi-Agent Board)](https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban), [Kanban tutorial](https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban-tutorial), [Desktop Kanban plugin source (GitHub)](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/plugins/kanban/plugin.tsx) ### How do I set up a team of bots that work together? The easiest way is Bot Mode in Hermes Desktop, on by default as the Bots tab. Click New Agent, give it a name, title and description, and optionally its own model, SOUL.md, skills, toolsets and MCP servers. Each bot is a profile, so it also works from the CLI (`hermes -p <bot> chat`). Bots can message each other with @mentions (`@researcher have a look at this`), you can open group chats where several bots deliberate, and each bot can have recurring routines. Group bots into sections to keep the roster tidy. For structured pipelines with handoffs and review steps, put the work on the Kanban board. The docs' learning path has a "team of specialist bots" reading order: Desktop, Profiles, Bot Mode, Cron, then Multi-connection Desktop. Sources: [Bot Mode](https://hermes-agent.nousresearch.com/docs/user-guide/bot-mode), [Learning Path](https://hermes-agent.nousresearch.com/docs/getting-started/learning-path), [Kanban (Multi-Agent Board)](https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban) ### Can agents on two different machines or Hermes instances talk to each other? Yes, in two ways. Bot-to-bot: register the other gateway as a peer with `hermes peer add <name> --url http://host:port --key <API_SERVER_KEY>` (the remote side runs the `api_server` platform), then `hermes peer dm <peer> "message"`. Bots learn about registered peers automatically, so they can message cross-machine teammates themselves. A2A: the Agent2Agent plugin lets your Hermes call other A2A agents as tools and receive tasks over HTTP, including from non-Hermes frameworks. Enable it with `hermes gateway setup` and turn on the outbound tools with `hermes tools enable a2a --platform cli`. Hermes Desktop can also connect to several machines at once, so bots on different hosts appear in one roster. For agents on the same machine, use subagents or Kanban instead. Sources: [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands), [A2A (Agent-to-Agent)](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/a2a), [Connecting Desktop to Many Hermes Instances](https://hermes-agent.nousresearch.com/docs/user-guide/multi-connection-desktop) ### How does Hermes handle subagent failures and two subagents editing the same files? Failures are never silent. A failed subagent reports a one-line reason in the CLI and in chat (even with tool progress hidden), and the parent gets `status: "failed"` with the error so it can retry or reroute. Children have no wall-clock timeout by default, but a stalled one (no activity for 450 seconds, or 1,200 inside a tool) is interrupted and reported. By default subagents share the parent's working folder, which is fine for reading but risky for parallel edits. Set `delegation.worktree_isolation: true` and each child works in its own git worktree and branch, which the parent can review and merge. That works for git repos on the local terminal backend. A restart doesn't resume a running subagent. For work that must survive restarts or hand off between agents, use Kanban or a cron job. Sources: [Subagent Delegation](https://hermes-agent.nousresearch.com/docs/user-guide/features/delegation), [Kanban (Multi-Agent Board)](https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban) ### Can several Hermes sessions work on the same repo at once? Yes, if each one gets its own checkout. Two agents editing the same working folder can overwrite each other's changes, so the docs recommend git worktrees: start with `hermes --worktree` (`-w`), create one mid-session with `/worktree new <name>`, or in Desktop use New worktree on a project (Cmd/Ctrl+Shift+B). For subagents, `delegation.worktree_isolation: true` gives each child its own worktree. Each worktree also gets its own checkpoint history for `/rollback`. Shared files outside git (a notes folder, a spreadsheet) have no such protection, so give each agent its own file or coordinate through Kanban. Sources: [Git Worktrees](https://hermes-agent.nousresearch.com/docs/user-guide/git-worktrees), [Subagent Delegation](https://hermes-agent.nousresearch.com/docs/user-guide/features/delegation), [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop) ### What's the difference between /council and /moa? Only `/moa` exists in Hermes; there is no `/council` command in the current release. `/moa <prompt>` runs one prompt through your default Mixture of Agents preset and then switches back to your normal model. A MoA preset sends your conversation to several reference models for their views, and an aggregator model writes the answer and does the tool calls; the aggregator is billed for the whole run. Create presets with `hermes moa configure`, list them with `hermes moa list`, and select one like any model (it appears under a Mixture of Agents provider) to use it for a whole session. If you want several distinct agents to discuss something, Bot Mode group chats in Hermes Desktop are the closest built-in equivalent. Sources: [Mixture of Agents](https://hermes-agent.nousresearch.com/docs/user-guide/features/mixture-of-agents), [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands), [Bot Mode](https://hermes-agent.nousresearch.com/docs/user-guide/bot-mode) ### What do `hermes pause` and `/restart` do to work already in progress? `hermes pause` is an emergency stop for new work: no cron jobs fire, no Kanban tasks are dispatched and no new gateway turns start (CLI, TUI and Desktop turns included) until `hermes resume`. Turns already running finish; nothing in flight is killed, and held cron work catches up after you resume. `/pause` and `/pause off` do the same from a chat. `/restart` (in a messaging chat) restarts the gateway gracefully: it waits for active turns to finish first (up to `agent.restart_after_turn_timeout`, 30 minutes by default), then confirms in your chat when it's back. Other stops, such as `hermes gateway stop` or an update, interrupt running chat turns immediately by default (`agent.restart_drain_timeout: 0`). Queued messages are kept and run after the restart. Sources: [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands), [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration), [Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) ## Security & permissions ### Is my data sent anywhere? Does Hermes collect telemetry? According to the FAQ, Hermes doesn't collect telemetry, usage data or analytics. API calls go only to the model provider you configure, and your conversations, memory and skills are stored locally in ~/.hermes/. Keep in mind that whatever you send to a cloud model provider is subject to that provider's policies. If you enable an external memory provider, Hermes masks recognisable secrets before sending data to it. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Memory Providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers) ### Will Hermes run dangerous commands without asking? Not by default. Commands are checked against dangerous patterns, and approvals.mode controls what happens: smart (default) uses a helper model to auto-approve low-risk commands, deny clearly dangerous ones and ask you about the rest; manual always asks; off disables checks. A hardline blocklist, covering things like filesystem wipes and fork bombs, can't be overridden even in YOLO mode. Cron jobs deny dangerous commands by default. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ### What is YOLO mode? YOLO mode skips dangerous-command approval prompts for the current session. Turn it on with hermes --yolo, the /yolo toggle, or HERMES_YOLO_MODE=1. The status bar shows a warning while it's active. The hardline blocklist still applies. The docs recommend YOLO only for trusted commands in disposable environments. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ### How do I stop being asked to approve the same command? Choose "always" when approving, and Hermes saves the pattern to command_allowlist in ~/.hermes/config.yaml, approving it silently from then on. Entries can be exact commands, shell-style globs like podman *, or rule keys shown in the prompt. To block commands outright, add your own rules under approvals.deny. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ### Can I sandbox the agent so it can't touch my machine? Yes. Change terminal.backend in config.yaml. The default is local, but docker runs commands in a hardened container, ssh runs them on a remote server, and singularity, modal, daytona and vercel_sandbox offer other isolated or cloud environments. For file edits there is also an optional write sandbox (HERMES_WRITE_SAFE_ROOT) and a list of protected paths that are always blocked. Sources: [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools), [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ### Can I let Hermes run freely but forbid specific commands? Yes, with `approvals.deny` in `config.yaml`: a list of glob patterns, such as `git push --force*`, that block matching terminal commands unconditionally. They're checked before `--yolo`, `/yolo` or `approvals.mode: off`, match case-insensitively, see through simple quoting tricks and apply to every terminal backend. Changes take effect without restarting. Always quote the patterns in YAML. The docs stress this is a command policy, not a sandbox, so use an isolated backend for real containment. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ### Does Hermes protect against prompt injection in project files? Partly. Context files such as `AGENTS.md` and `.cursorrules` are scanned before they enter the system prompt, looking for instructions to ignore earlier instructions, hidden HTML comments, attempts to read secrets, credential exfiltration via `curl` and invisible Unicode. A flagged project file is not loaded. The docs call these checks heuristics, not semantic intent detection. Your own `SOUL.md` in your Hermes home only gets a warning, not a block. Separately, the command checker flags `curl` or `wget` uploads of secrets and hidden Unicode in commands. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ### Can I keep API keys in 1Password or Bitwarden instead of the .env file? Yes. At startup Hermes can pull keys from Bitwarden Secrets Manager, 1Password (`op://` references through the `op` CLI) or any CLI vault via a command helper. Only the secret manager's bootstrap token stays in `.env`, and everything else can rotate centrally. Configure sources under `secrets` in `config.yaml`. By default a value already in your `.env` or shell wins unless the source sets `override_existing: true`, which Bitwarden does by default. Sources: [Secrets](https://hermes-agent.nousresearch.com/docs/user-guide/secrets/), [1Password](https://hermes-agent.nousresearch.com/docs/user-guide/secrets/onepassword), [Bitwarden](https://hermes-agent.nousresearch.com/docs/user-guide/secrets/bitwarden) ### Can I undo file changes the agent made? Yes, if checkpoints are on. They're opt-in: start with `hermes chat --checkpoints` or set `checkpoints.enabled: true`. Hermes then snapshots your files into a shadow git store under `~/.hermes/checkpoints/` before file writes, patches and destructive commands such as `rm` or `mv`, without touching your project's own `.git`. In a session, `/rollback` lists checkpoints and `/rollback` with a number restores one while keeping your hand-edits; add `--all` for a full restore, or use `/rollback diff` to preview. `hermes checkpoints` shows storage use. Sources: [Checkpoints and /rollback](https://hermes-agent.nousresearch.com/docs/user-guide/checkpoints-and-rollback) ### How can I tell if a third-party skill or plugin is safe before installing it? Check where it comes from. Skills: built-in and `official/...` skills are fully trusted, a few well-known registries are "trusted", and everything else is community. Every hub install runs a security scan; a dangerous verdict is blocked even with `--force`. Preview first with `hermes skills inspect <id>`, and re-scan later with `hermes skills audit`. Plugins: catalog entries are human-reviewed, pinned to an exact commit and scanned at admission, and tagged Official, Verified or Community. Raw git URLs are flagged as unreviewed. The docs are blunt that catalog listing isn't a code audit, and plugins (especially Desktop plugins) aren't sandboxed, so read the code and the disclosure for anything with broad access. `hermes security audit` checks your environment, plugin requirements and pinned MCP servers against known vulnerabilities. If in doubt, try new things in a separate profile with a sandboxed terminal backend. Sources: [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills), [Plugin Catalog](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugin-catalog), [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) ### How much access does Hermes (and Hermes Desktop) have to my computer, and can I restrict it? On the default `local` terminal backend, the agent can do what your user account can: run commands, read and write files. Profiles don't sandbox it. Guardrails are on by default: dangerous commands need approval, a hardline blocklist can't be overridden, writes to credential files such as `~/.ssh` and `.env` are blocked, and secrets are redacted from output. Computer use (clicking and typing in apps) also goes through approvals. To tighten it: set `approvals.mode: manual` to confirm every command, add `approvals.deny` rules, restrict file writes with `HERMES_WRITE_SAFE_ROOT`, and move command execution off your machine with `terminal.backend: docker` or `ssh`. In Desktop, Settings > Workspace can limit which folders it scans for repositories. Tools run on whichever backend Desktop is connected to. Connect it to a remote gateway and the commands, files and computer use happen on that machine, not yours. Sources: [Running Hermes on a Personal or Work Machine](https://hermes-agent.nousresearch.com/docs/guides/secure-hermes-on-a-work-machine), [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security), [Computer Use](https://hermes-agent.nousresearch.com/docs/user-guide/features/computer-use) ### How do I let family members or coworkers use my agent while keeping their data separate? Give each person their own profile (`hermes profile create <name>`). A profile has its own memory, sessions, skills, keys and cron jobs, and each gets its own messaging bot, since a bot token can only belong to one profile. If several people share one bot, lock it down with allowlists or DM pairing (`hermes pairing approve <platform> <code>`). Most platforms keep a separate session per user, but they share the profile's memory and tools, so don't share a bot that has access to your private accounts. Profiles separate data, not machines: on the default local backend every profile can still reach your files. For real isolation between people, use a sandboxed terminal backend (Docker or SSH) or separate hosts. Sources: [Profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles), [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### What happens to my data when I use models through Nous Portal? Hermes itself sends no telemetry; your conversations, memory and skills stay on your machine, and requests go only to the provider you choose. Once you send a request through Nous Portal, the Nous Research privacy policy applies. That policy (last updated September 28, 2026) says Nous collects prompts and outputs as workflow data and shares them with the third-party model providers that serve each model, under those providers' terms. It offers an opt-in Privacy Mode under which Nous says it won't store your inference payloads or use them for training, with exceptions for operational metadata and security or legal needs, and it applies only from when you turn it on. No retention period is stated for inference content. Separately, Hermes warns before you pick discounted data-training model tiers (names ending in `-contributor`), where the vendor may train on your prompts. Sources: [Nous Research Privacy Policy](https://portal.nousresearch.com/privacy), [Is my data sent anywhere? (FAQ)](https://hermes-agent.nousresearch.com/docs/reference/faq), [Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models) ### How does Hermes handle passwords, logins and payment details? Through its built-in vault (Passwords & Logins). The first time the agent hits a sign-in page with no saved login, it asks you in a masked prompt; the password is encrypted on your machine, bound to that site, and filled into the page without the model ever seeing it. 1Password and Bitwarden CLIs are picked up automatically if installed and signed in. Cards and addresses work the same way (Settings > Passwords & Logins, or `hermes vault add`), and every card fill asks you first. Unattended runs such as cron and webhooks can't confirm, so they can't spend. Two-factor codes are generated from a saved authenticator key or typed by you into a prompt. The vault protects against filling the wrong site, not against a compromised one: once a password is in a page, that site has it. On a hosted gateway, you can also take over the Bot Screen and type sensitive steps yourself. Sources: [Passwords & Logins](https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-vault), [Bot Screen](https://hermes-agent.nousresearch.com/docs/user-guide/features/bot-screen) ### If I approve a plan, is Hermes bound to it, and will it ask before going beyond it? A plan is guidance, not an enforced contract. `/plan` writes an implementation plan to `.hermes/plans/` without executing anything, and the agent will usually follow it, but nothing technically stops a model from straying. What is enforced are the controls around actions: dangerous commands need approval, `approvals.mode: manual` makes it ask for every command, `approvals.deny` blocks patterns outright, and checkpoints (`hermes chat --checkpoints`) let you `/rollback` file changes. To keep it on track, ask it to check back with you before anything outside the plan; it has a clarify tool for questions. In Desktop's Git review pane, the Last turn view shows exactly what changed. Sources: [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands), [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security), [Checkpoints and /rollback](https://hermes-agent.nousresearch.com/docs/user-guide/checkpoints-and-rollback) ### Are third-party “Hermes” apps affiliated with Nous Research? Treat any app as unofficial unless the official docs or the NousResearch GitHub link to it. The official distributions are the installer scripts and Hermes Desktop from hermes-agent.nousresearch.com, the Microsoft Store and MSIX packages, the `nousresearch/hermes-agent` Docker image, the Termux package and the NousResearch/hermes-agent repository. Community projects can be useful; the plugin catalog even lists community mobile adapters. But they're built by their authors, not Nous, and a client that connects to your agent can see your conversations and possibly your tools. Before connecting one, check who publishes it, read what access it needs, and prefer apps that connect through Hermes' own authenticated gateway rather than asking for your API keys. Sources: [Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation), [Platform Support](https://hermes-agent.nousresearch.com/docs/getting-started/platform-support), [Plugin Catalog](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugin-catalog) ### How do I connect work tools like Outlook, Jira or an ERP without over-granting access? Prefer official, scoped connections. The MCP catalog includes vendor-hosted servers (Atlassian for Jira and Confluence, plus Linear, Notion and others) that sign in with OAuth (`hermes mcp install <name>`), and each MCP server can expose only chosen tools with `tools.include` or `tools.exclude`. Use a service account or read-only token where the system offers one. On a work machine, follow the docs' hardening guide: manual approvals, your own deny rules, a write sandbox, and running commands in Docker or over SSH. Keep secrets in a manager such as 1Password or Bitwarden rather than `.env`. Systems without an MCP server or plugin can still be reached through scripts or APIs, but then access is whatever that credential allows, so keep it narrow and check your company's policy first. Sources: [Running Hermes on a Personal or Work Machine](https://hermes-agent.nousresearch.com/docs/guides/secure-hermes-on-a-work-machine), [MCP (Model Context Protocol)](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp), [Secrets](https://hermes-agent.nousresearch.com/docs/user-guide/secrets/) ### If I connect several accounts (say work and home Gmail), which one does Hermes use? With hosted connectors you can connect two or more accounts of one app, each with a short name such as `home` and `work`. There is no default: when several named accounts exist, the agent must say which one, and a call that leaves it out fails with the list of valid names. Results report the account they ran under. Name, rename and remove accounts in Desktop's Connectors page, `/connectors` in the TUI, `hermes connectors` in a shell, or on Nous Portal. The agent may name a new account but never removes one. Skills that use their own credentials, such as Google Workspace or Himalaya, use whatever account you set up for them. Sources: [Nous Tool Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway), [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) ## Running & deploying ### What are terminal backends? A terminal backend decides where the agent's shell commands actually run. Hermes has seven: local, docker, ssh, singularity, modal, daytona and vercel_sandbox. Set one with terminal.backend in config.yaml or hermes config set terminal.backend <name>. The README notes that Daytona and Modal can hibernate when idle, so a cloud environment costs very little between sessions. Sources: [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools), [Hermes Agent README (GitHub)](https://github.com/NousResearch/hermes-agent) ### Can I run Hermes on a cheap VPS and talk to it from my phone? Yes, that's a common setup. The README mentions running it on a $5 VPS. Install it on the server, connect a chat app with hermes gateway setup, and keep the gateway running as a service (hermes gateway install, or sudo hermes gateway install --system for a boot-time service on Linux). Then chat with it from Telegram or another platform while it works on the server. Sources: [Hermes Agent README (GitHub)](https://github.com/NousResearch/hermes-agent), [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) ### How do I run Hermes in Docker? Mount a data folder and run the setup wizard once: docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup. Then start a long-running gateway with docker run -d --name hermes --restart unless-stopped -v ~/.hermes:/opt/data nousresearch/hermes-agent gateway run. Docker installs don't support hermes update. To upgrade, pull a new image and recreate the container with the same data mount. Sources: [Docker](https://hermes-agent.nousresearch.com/docs/user-guide/docker), [Platform Support](https://hermes-agent.nousresearch.com/docs/getting-started/platform-support), [Updating & Uninstalling](https://hermes-agent.nousresearch.com/docs/getting-started/updating) ### Can I run more than one agent on the same machine? Yes, with profiles. Each profile is a separate Hermes home with its own config, keys, memory, sessions, skills and cron jobs. hermes profile create coder creates one and also gives you a coder command, so you can run coder chat or coder gateway start. Profiles don't share memory, and two profiles can't use the same bot token, so give each one its own bot. Sources: [Profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### How do I move Hermes, or a single profile or bot, to another computer? For a whole setup, run `hermes backup` on the old machine. It creates `~/hermes-backup-<timestamp>.zip` with config, credentials, memories, skills, sessions and profiles (not the app itself, browser profiles or caches). Install Hermes on the new machine, copy the zip over, run `hermes import <file>`, then `hermes setup` to check your keys. Review the backup's skipped-file report before you wipe the old machine. To move or share one profile (a Bot Mode bot is a profile), run `hermes profile export work -o work.tar.gz` and on the other side `hermes profile import work.tar.gz --name work`. In Desktop the same thing is Export profile… and Import profile… in the command palette, and `/export` and `/import` work in chat. Profile exports strip API keys and logins, so sign in again on the new machine. Going to Docker instead? The official image keeps all user data in one folder mounted at `/opt/data`, and the image itself holds no state. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop), [Docker](https://hermes-agent.nousresearch.com/docs/user-guide/docker) ### Can I talk to Hermes with my voice, and can it make phone calls? Yes. In the CLI, turn on `/voice on` and press Ctrl+B to record; Hermes detects silence and replies. In Hermes Desktop, the microphone does dictation and the voice button starts a spoken conversation. On Telegram and Discord it can send spoken replies, and on Discord it can join a voice channel. Desktop also offers a full-duplex mode: set Settings > Voice > Voice Chat Mode to GPT-Live (`voice.voice_chat_mode: gpt-live`). It uses OpenAI's `gpt-live-1`, needs your own OpenAI key, is billed by OpenAI per minute of session time, and hands real work to your normal Hermes model. Configure speech-to-text and text-to-speech providers with `hermes tools`; a Nous Portal plan can supply text-to-speech. Phone calls aren't built in, but the official optional Telephony skill (`hermes skills install official/productivity/telephony`) covers Twilio numbers, SMS and AI outbound calls with your own Twilio account. Sources: [Voice Mode](https://hermes-agent.nousresearch.com/docs/user-guide/features/voice-mode), [Telephony skill](https://hermes-agent.nousresearch.com/docs/user-guide/skills/optional/productivity/productivity-telephony) ### Is there a web interface for managing Hermes? Yes. `hermes dashboard` starts a local web server and opens `http://127.0.0.1:9119`. From there you can manage config, API keys, MCP servers, messaging pairing, webhooks, the gateway, memory, sessions, logs, analytics, cron jobs and skills instead of editing YAML. `--port` changes the port and `--no-open` skips opening the browser. It binds to localhost by default. If you bind it elsewhere with `--host`, a public bind always requires an auth provider, either a password or OAuth. Sources: [Hermes Web Dashboard](https://hermes-agent.nousresearch.com/docs/user-guide/features/web-dashboard) ### Can I use Hermes inside VS Code, Zed or JetBrains? Yes, through ACP (Agent Client Protocol). `hermes acp` runs Hermes as an ACP server over stdio, and editors can show its chat, tool activity, file diffs, terminal commands and approval prompts. In VS Code, install the ACP Client extension and pick Hermes Agent. In Zed, add a custom agent server with command `hermes` and args `acp`. JetBrains works through an ACP-compatible plugin. ACP sessions keep your provider setup, memory and skills but leave out messaging delivery and cron management. `hermes acp --check` verifies the install. Sources: [ACP Host Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/acp) ### Is there an official Hermes mobile app for iOS or Android? Not yet. The current release has no official iOS or Android app; there's no mobile app in the official repository and none in the docs. The Nous team has said on X that one is in the works, without a public date. Today, the supported way to use Hermes from your phone is the messaging gateway: run Hermes on a computer, server or Hermes Cloud and chat with it on Telegram, Discord, WhatsApp, Signal, Slack and other apps. You can even move a live CLI session to your phone with `/handoff`. Android users can also run Hermes itself on the phone through the official Termux package (64-bit ARM). Be wary of third-party apps claiming to be the official one. Sources: [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/), [Android / Termux](https://hermes-agent.nousresearch.com/docs/getting-started/termux), [Nous Research team reply on X (October 2026)](https://x.com/i/status/2112630315088851035) ### Can Hermes Desktop connect to a remote agent on a VPS, NAS or Hermes Cloud without running the agent locally? Yes. Desktop can attach to a backend on another machine and act as the client: your sessions, memory and tools all live on that host. Go to Settings > Gateways. Hermes Cloud lets you sign in and pick an agent with nothing to paste; Remote gateway takes the URL of a backend you run; SSH opens a tunnel to a Hermes install for you. For your own server, run `hermes serve` there (the headless backend; `hermes dashboard` works too) bound to a reachable address, for example `hermes serve --host 0.0.0.0 --port 9119`. A non-loopback bind requires sign-in: use a username and password only on a trusted network or VPN such as Tailscale, and OAuth through Nous Portal (`hermes dashboard register`) for anything reachable from the internet. Then enter `http://<host>:9119` in Desktop and sign in. Without a local runtime the app offers to connect or install, and `hermes desktop --ignore-existing` skips an installed one so no local backend starts. The messaging gateway on the server is a separate process you keep running yourself. Sources: [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop), [Connecting Desktop to Many Hermes Instances](https://hermes-agent.nousresearch.com/docs/user-guide/multi-connection-desktop), [Hermes Web Dashboard](https://hermes-agent.nousresearch.com/docs/user-guide/features/web-dashboard) ### What is Bot Screen, where does it run, and how heavy is it? Bot Screen gives each bot its own desktop on a headless Linux gateway host (a server, cloud VM or Hermes Cloud), which the bot's computer use and browser act on, streamed live into Hermes Desktop. Your Mac or PC is only the viewer, and the bot keeps working when you close the app. It isn't offered when the gateway itself runs on macOS or Windows, which already have a real display. It's off by default. Start it from the Screen pane in Desktop or with `hermes computer-use screen start` on the host; `hermes computer-use screen status` shows whether the needed TigerVNC and Xfce packages are installed, and `hermes computer-use screen install` adds them. Unused screens stop after 30 minutes. Plan for about 1.1–1.5 GB of RAM per open screen with a browser: the desktop is cheap, the browser is the cost. 4 GB runs it and 8 GB is comfortable for takeovers. With a Docker or SSH terminal backend, the screen runs inside that sandbox. Sources: [Bot Screen](https://hermes-agent.nousresearch.com/docs/user-guide/features/bot-screen), [Computer Use](https://hermes-agent.nousresearch.com/docs/user-guide/features/computer-use) ### How do I watch the agent, or take over for a login, 2FA or CAPTCHA, and does it keep going afterwards? When the bot hits a step it shouldn't do itself (a login, a 2FA prompt, a CAPTCHA, a payment), it says so in chat and ends its turn. On a hosted gateway with Bot Screen, open the bot's Screen, click Take over, do the step, then click Hand back and tell it to continue. While you hold control its computer-use and browser tools are refused; on hand-back it re-captures the screen and carries on in the same conversation, with the session you just signed in to. The browser profile persists per bot, so the login usually sticks for later runs. On your own computer you can simply watch: set `browser.headed: true` for a visible browser. For many sites the vault can fill saved logins and generate 2FA codes without a takeover. Sources: [Bot Screen](https://hermes-agent.nousresearch.com/docs/user-guide/features/bot-screen), [Passwords & Logins](https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-vault), [Browser Automation](https://hermes-agent.nousresearch.com/docs/user-guide/features/browser) ### Can a cloud or VPS agent control my local computer, and why does Desktop act differently on a remote gateway? Tools run where the backend runs. With Desktop connected to a cloud or VPS gateway, terminal commands, file edits, computer use and the browser all happen on that remote machine, not on your PC. That's why a remote agent can't click around your local apps or read your local files. A few things are tied to the machine running the app, so they behave differently remotely: Open containing folder only works for local sessions (use Reveal in filetree), artifacts download through the gateway, logs for a failed turn live on the remote host, and settings, sessions and memory follow the gateway you're connected to. To have an agent act on your computer, run Hermes on it, either as Desktop's local gateway or as a second registered gateway, and switch between gateways in the Sessions sidebar. Sources: [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop), [Computer Use](https://hermes-agent.nousresearch.com/docs/user-guide/features/computer-use), [Connecting Desktop to Many Hermes Instances](https://hermes-agent.nousresearch.com/docs/user-guide/multi-connection-desktop) ### What is Hermes Cloud, how is it priced, and is storage persistent? Hermes Cloud is Nous Research's hosted Hermes Agent: an always-on agent on a dedicated cloud instance with its own workspace and dashboard, managed from the agents page in Nous Portal. Hermes Desktop connects to it from Settings > Gateways > Hermes Cloud. According to the Cloud page, instances are billed daily from your Nous credit based on actual use (compute plus storage), stopped instances pay only storage, and model and tool use is billed separately. Deploying needs at least $2 in credits or an active subscription; current instance sizes and prices are listed in Nous Portal. Storage is persistent: files, memory and configuration are kept whether the agent is running or stopped, and disks never shrink. The Nous team has said on X that each instance has roughly a 12 GB persistent volume at `/opt/data` holding the Hermes home; check the Portal for current sizes. Sources: [Hermes Cloud (Nous Portal)](https://portal.nousresearch.com/cloud), [Manage Hermes Cloud with MCP](https://hermes-agent.nousresearch.com/docs/guides/manage-hermes-cloud-with-mcp), [Nous Research team reply on X (October 2026)](https://x.com/i/status/2088915047300952377) ### How do I back up my Hermes setup? Run `hermes backup`. It writes `~/hermes-backup-<timestamp>.zip` with your config, credentials, memories, skills, sessions and profiles, and it's safe to run while Hermes is working. Restore with `hermes import <file>`. Check its report of files that failed to copy, and store the zip somewhere private, since it contains your keys. `hermes backup --quick` saves only selected state files. Updates take a quick snapshot automatically; `hermes update --backup`, or `updates.pre_update_backup: full`, makes a full one before each update. For a VM or Docker host, back up the Hermes data folder itself (`/opt/data` in the official image), or snapshot the whole VM with your provider's tools. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Updating & Uninstalling](https://hermes-agent.nousresearch.com/docs/getting-started/updating), [Docker](https://hermes-agent.nousresearch.com/docs/user-guide/docker) ## Research & knowledge work ### Can Hermes work with an Obsidian vault or my own markdown notes? Yes. The bundled Obsidian skill lets the agent read, search, create and edit notes and add wikilinks. Set `OBSIDIAN_VAULT_PATH` in your `.env` to the vault's folder (otherwise it tries `~/Documents/Obsidian Vault`). Any folder of markdown files works the same way through the file tools. A useful pattern: have it take notes in the vault as it works, then in a later session ask it to continue a topic, and it searches the vault. Keep short durable facts (like where the vault is) in memory and longer material in notes. The bundled `llm-wiki` skill builds and queries an interlinked markdown knowledge base, and the plugin catalog lists a community dashboard plugin for browsing a vault. Sources: [Obsidian skill](https://hermes-agent.nousresearch.com/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian), [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory), [LLM Wiki skill](https://hermes-agent.nousresearch.com/docs/user-guide/skills/bundled/research/research-llm-wiki) ### Can Hermes read ebooks, PDFs and scanned documents? Are big files loaded whole? Yes. Its file reader converts Word, Excel, PDF, EPUB, RTF, OpenDocument and older Office files to text (PDF, EPUB and the others need a converter that installs on first use). Files are read in pages, not loaded whole, and documents over 50 MB are refused. PDF conversion reads only the text layer, so scanned pages come out empty. When a big share of pages has no text, Hermes warns and lists the empty page ranges, then can render a few pages as images for its vision tool, or follow the bundled `pdf` skill's OCR guide (marker-pdf) for many pages. For long books, ask for focused work (a chapter, a summary per section) rather than everything at once, so the context window isn't flooded. Sources: [Document Extraction](https://hermes-agent.nousresearch.com/docs/user-guide/features/document-extraction), [PDF skill OCR guide (GitHub)](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/pdf/references/ocr-extraction.md) ### Can Hermes use Firefox or my own Chrome profile for browsing? Chrome-family, yes. Set `browser.use_real_profile: true` and Hermes copies your active Chrome, Edge, Brave or Chromium profile (cookies and logins) into a separate snapshot and browses with it, so you stay signed in; `browser.real_profile_pin: "Profile 2"` picks a specific profile. In Desktop it's a toggle under Capabilities > Tools > Browser. Your live profile is never opened directly. Or connect to a browser you launched yourself with a debug port: run `/browser connect` in the CLI. Chrome 136 and later need a separate `--user-data-dir` for this. Firefox isn't supported for real-profile browsing; with Firefox as your default you get a fresh browser and a message saying so. The Camofox option is Firefox-based, but it's a separate self-hosted anti-detection browser, not your own Firefox. Sources: [Browser Automation](https://hermes-agent.nousresearch.com/docs/user-guide/features/browser) ## Troubleshooting ### I installed it but get “hermes: command not found”. What now? Your shell hasn't picked up the updated PATH yet. Run source ~/.bashrc (or source ~/.zshrc), or open a new terminal. The installer puts the hermes command in ~/.local/bin. If it still fails, check with which hermes, and add export PATH="$HOME/.local/bin:$PATH" to your shell config if needed. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### My bot isn't replying to messages. How do I fix it? Check the gateway is running with hermes gateway status and start it with hermes gateway start. Then look at the end of ~/.hermes/logs/gateway.log for errors, and make sure your user ID is on the allowlist or approved through pairing. On Discord, a disabled Message Content Intent stops the bot from connecting at all. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Discord](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord) ### How do I diagnose problems? Run hermes doctor to check config and dependencies. hermes doctor --fix tries to repair what it can. hermes logs views and filters agent, gateway and error logs, and hermes debug share uploads a debug report and prints a link you can give to helpers. Inside a session, /status shows the active model and provider. Sources: [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### Where can I get help or report a bug? Search or open an issue on GitHub at github.com/NousResearch/hermes-agent/issues, or ask in the Nous Research Discord. When filing a bug, include your OS, Python version, hermes --version output, and the full error message. The official docs at hermes-agent.nousresearch.com/docs include an FAQ and troubleshooting page that covers many common problems. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Hermes Agent README (GitHub)](https://github.com/NousResearch/hermes-agent) ### Why can’t Hermes find node, nvm or pyenv in its terminal? Hermes builds each session's shell environment from a bash login shell, which doesn't read `~/.bashrc` by itself. Hermes sources `~/.bashrc` automatically, but tools set up in `~/.zshrc` or a standalone init file can stay invisible, especially under systemd. List the extra files under `terminal.shell_init_files` in `config.yaml`, for example `~/.zshrc` or `~/.nvm/nvm.sh`. Setting that list replaces the default `~/.bashrc` auto-source, so include it too if you need both. On macOS, if the gateway can't find tools you installed later, rerun `hermes gateway install` to re-capture your PATH. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ### Hermes seems less capable than before. What should I check? The docs give a checklist. First confirm the model with `/status` or `/model`: a `/model` switch is session-only by default, and model changes from the dashboard apply only to new sessions. Next check context pressure with `/usage` or `/context`, and run `/compress` or `/new` if the session is long. Then check the context length shown at startup and set `model.context_length` if it's wrong. Finally, remember memory is a frozen snapshot, so something saved mid-session only appears in the next session. Sources: [Troubleshooting: My Agent Feels Dumber](https://hermes-agent.nousresearch.com/docs/guides/troubleshooting-agent-quality) ### My local model server errors out or goes quiet on long chats. What’s wrong? Usually the context length Hermes assumes doesn't match the server. Set `model.context_length`, or a per-model `context_length` under `providers`, to the window your server really uses, such as llama.cpp's `--ctx-size`. Otherwise Hermes may stop with a message that compression couldn't shrink the request enough. On single-slot servers like Ollama or LM Studio, a too-large rejection can mean a background memory review is holding the slot, so wait and `/retry`. For timeouts on very large contexts, set `HERMES_STREAM_READ_TIMEOUT=1800` in `.env`. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Local LLM on Mac](https://hermes-agent.nousresearch.com/docs/guides/local-llm-on-mac) ### Is it safe to update Hermes, and can I roll back if an update breaks something? Updates are designed to be safe. `hermes update` follows the stable release channel by default, `hermes update --check` previews it, a quick snapshot of each profile's state is taken first, and if critical files fail to load after the update it rolls the code back automatically. Afterwards run `hermes doctor` and `hermes --version`. For extra safety, `hermes update --backup` makes a full backup first. To roll back, stop the gateway, check out the older release (a source install that followed `main` can return to the latest release with `hermes update --set-channel stable`), then restore the pre-update snapshot with `/snapshot restore <id>` or the full backup with `hermes import`. Running an old release on a database a newer one has upgraded is refused, so restore the data too. Desktop app, Docker, Store and Nix installs roll back through their own packaging (for Nix, `nix profile rollback`). Sources: [Updating & Uninstalling](https://hermes-agent.nousresearch.com/docs/getting-started/updating), [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) ### Why is my model rejected with errors like 401, “model not supported” or no provider configured? “No inference provider configured” means Hermes has nothing to talk to yet: run `hermes setup` or `hermes model` and sign in or add a key. A 401 or invalid-key error means the credential is missing, expired or for the wrong provider (an OpenAI key won't work on OpenRouter); re-enter it with `hermes model` and check `~/.hermes/.env` for conflicting entries. “Model not found” or a 400 on the first run usually means the model id doesn't exist on that provider, or your plan or credits don't cover it. Messages like “model is not supported when using Codex with a ChatGPT account” are plan entitlements. Pick a model the provider actually lists in `hermes model`. `/status` shows the active model and provider, and `hermes doctor` checks the setup. Remember `/model` only lists providers you've already configured. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Credential Pools](https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools) ### Why is Hermes slow or laggy, and should I reinstall? Reinstalling rarely helps. Slowness usually comes from the model (large reasoning models and busy providers are slow), a long session, or a heavy prompt with many tools. First make sure you're on the latest version (`hermes --version`, `hermes update`). Then try a faster model, start a fresh session with `/new` (or `/compress` a long one), and disable toolsets and MCP servers you don't use. In Desktop, turn on tokens per second in the status bar to see whether the model itself is slow. For local models, make sure the model fits in GPU memory, since spilling into system RAM is much slower. If it's still slow, `hermes doctor` and `hermes logs` help find the cause, and `hermes debug share` produces a report you can give to helpers. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop), [Local Models](https://hermes-agent.nousresearch.com/docs/user-guide/local-models) ### Updates on Windows fail or take a very long time. How do I fix that? Windows locks files that running programs are using, so close Hermes Desktop windows and other Hermes processes before updating, and follow any diagnostic naming a specific process; don't kill every Python process. `hermes update --plan`, the update log and `hermes pm status` show what failed, and the log is in the profile's `logs/update.log`. If security software quarantined updater files, repair the installation and review the quarantine report rather than turning protection off. The Nous team has said on X that failures are often Windows file permissions (“Access is denied” in Hermes' tools folder) and that Smart App Control can block a locally built Desktop app. If you'd rather avoid local builds, the MSIX package (Windows 11 22H2 or later) or the Microsoft Store version ships prebuilt and updates through the app or the Store. Sources: [Updating & Uninstalling](https://hermes-agent.nousresearch.com/docs/getting-started/updating), [Windows (Native) Guide](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native), [Nous Research team reply on X (October 2026)](https://x.com/i/status/2104876510335131712) ### Do I have to restart the gateway after changing settings? Sometimes. Many settings apply without a restart: `model.context_length` and `compression.*` take effect on the next message, `approvals.deny` changes apply immediately, and some session settings apply to the next new session. In a session, `/reload` picks up new keys from `.env`, `/reload-mcp` reloads MCP servers and `/reload-skills` rescans skills. Display settings like `display.tool_progress`, Telegram command-menu changes, platform credentials and unloading plugin code need a restart. Use `hermes gateway restart`, or `/restart` from a chat, which waits for active turns to finish. Desktop's Messaging page shows a Restart now banner whenever a credential change needs one. Sources: [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) # Glossary URL: https://hermeswatcher.com/glossary ## .env file The file in your Hermes home (~/.hermes/.env) that stores API keys and tokens such as TELEGRAM_BOT_TOKEN. It holds credentials, not memory. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq), [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) ## /goal A standing goal Hermes keeps working toward across turns. After each turn a judge model decides whether it's done, and if not Hermes continues, up to a budget of 20 turns by default (`goals.max_turns`). Sources: [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) ## /steer A slash command that hands the running agent a note after its next tool call, changing direction without interrupting the task or starting a new turn. Sources: [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) ## ACP (Agent Client Protocol) A JSON-RPC-over-stdio protocol spoken by editors such as VS Code, Zed and JetBrains. `hermes acp` runs Hermes as an ACP server so it can work inside those editors. Sources: [ACP Host Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/acp), [Programmatic Integration](https://hermes-agent.nousresearch.com/docs/developer-guide/programmatic-integration) ## AGENTS.md The main project context file describing structure, conventions and instructions. Inside a git repo, AGENTS.md files from the root down to the working directory are merged. Sources: [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) ## API server A mode that exposes Hermes as an OpenAI-compatible HTTP endpoint so other chat frontends can use it as a backend. Sources: [API Server](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server) ## approvals.deny A user-editable list of glob patterns for terminal commands that are always blocked, even in YOLO mode or with approvals turned off. It's the configurable counterpart to the hardline blocklist. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ## Auxiliary models Models used for side tasks such as vision, context compression, session titles and approval checks. They default to your main chat model and can be overridden per task under `auxiliary` in `config.yaml` or through `hermes model`. Sources: [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) ## Baileys bridge Hermes' built-in WhatsApp connection, which emulates a WhatsApp Web session paired by QR code rather than using the official Business API. Sources: [WhatsApp](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp) ## Bot Chat A profile's canonical chat session with its own bot. The `bot-chat` cron delivery target posts output into it as an incoming message so the bot acts on it, costing one full agent turn per delivery. Sources: [Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) ## Checkpoints / rollback An opt-in feature (hermes chat --checkpoints) that snapshots your project before destructive operations so you can restore it with /rollback. Sources: [Checkpoints and /rollback](https://hermes-agent.nousresearch.com/docs/user-guide/checkpoints-and-rollback) ## command_allowlist The config.yaml list of command patterns you've permanently approved, so Hermes runs them without asking. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ## config.yaml The main settings file in your Hermes home. It holds the model, terminal backend, memory, approvals, MCP servers, display options and more, and you can edit it directly or use hermes config set. Sources: [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ## Context compression Automatic summarising of older conversation history once a session passes a share of the model's context window. You can also trigger it yourself with /compress. Sources: [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ## Context file injection scanning A check that scans `AGENTS.md`, `.cursorrules` and similar files for prompt-injection patterns before they enter the system prompt. A flagged project file is not loaded and a warning is shown instead. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ## Context files Project instruction files Hermes loads automatically, such as .hermes.md, AGENTS.md, CLAUDE.md or .cursorrules. Only the first matching type is used per session. Sources: [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) ## Context references Inline @ syntax such as `@file:`, `@folder:`, `@diff`, `@staged`, `@git:` and `@url:` that pulls file contents, git changes or web pages straight into a message. Sources: [Context References](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-references) ## Credential pool Several API keys for the same provider that Hermes rotates between when one hits a rate limit or quota. Sources: [Credential Pools](https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools) ## Cron job A scheduled task, one-off or recurring, that runs in a fresh agent session and delivers results to a chat or file. It's managed through /cron, hermes cron or plain-language requests. Sources: [Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) ## cronjob_manage The single tool Hermes uses to create, pause, edit, trigger and remove scheduled jobs when you ask in plain language. Sources: [Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) ## Curator A background maintenance pass that tracks how agent-created skills are used, moves unused ones from active to stale to archived, and never auto-deletes them. Sources: [Curator](https://hermes-agent.nousresearch.com/docs/user-guide/features/curator) ## Custom endpoint A provider option (provider: custom) for any OpenAI-compatible server, commonly used for local models through Ollama, vLLM or llama.cpp. Sources: [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ## Dangerous command approval The safety check that pauses risky shell commands for your approval. approvals.mode sets it to smart, manual or off. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ## delegate_task / subagent The tool that spawns child agents with isolated context for side tasks or parallel work. Only each child's final summary returns to the main chat. Sources: [Subagent Delegation](https://hermes-agent.nousresearch.com/docs/user-guide/features/delegation) ## Delivery target The `deliver` setting that decides where a cron job's output goes: `origin`, `local`, a platform's home channel, a specific chat or topic, a comma-separated list, or `all`. Sources: [Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) ## DM pairing A way to authorise new chat users: an unknown user gets an 8-character code, which the owner approves with hermes pairing approve. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ## execute_code A tool that lets the agent write a Python script that calls Hermes tools programmatically, collapsing many steps into one turn. Sources: [Code Execution](https://hermes-agent.nousresearch.com/docs/user-guide/features/code-execution) ## External memory provider A plugin-based memory service, such as Honcho, Mem0, Hindsight, Supermemory, RetainDB or ByteRover, that adds deeper recall alongside the built-in memory files. Set it up with hermes memory setup. Sources: [Memory Providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers) ## Fallback providers Backup provider and model pairs Hermes switches to automatically when your main model fails. Sources: [Fallback Providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers) ## Frozen snapshot How memory is loaded: it's read once into the system prompt when a session starts and doesn't change mid-session. That preserves the prompt cache but means new memories appear in the next session. Sources: [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) ## Hardline blocklist An always-on list of catastrophic commands, such as filesystem wipes and fork bombs, that Hermes refuses even in YOLO mode. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ## Hermes Agent An open-source (MIT) AI agent from Nous Research that runs in your terminal, a desktop app or chat apps, uses tools for you, and learns over time through memory and skills. Sources: [Hermes Agent README (GitHub)](https://github.com/NousResearch/hermes-agent) ## Hermes Desktop The native desktop app for macOS, Windows and Linux. It drives the same agent, config and sessions as the CLI. Sources: [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop) ## Hermes home (HERMES_HOME) The data folder where Hermes keeps config, keys, memory, skills and sessions. It's ~/.hermes on Linux and macOS, and the HERMES_HOME environment variable points Hermes at a different one. Sources: [Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ## Home channel The default chat on a platform where cron results and notifications land. Set it by sending `/sethome` in that chat or with variables such as `TELEGRAM_HOME_CHANNEL`. Sources: [Telegram](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram), [Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) ## Honcho An external memory provider from Plastic Labs that builds a model of the user across sessions and profiles. It's installed with hermes plugins install honcho and runs on Honcho Cloud or self-hosted. Sources: [Memory Providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers), [Hermes Agent README (GitHub)](https://github.com/NousResearch/hermes-agent) ## Kanban board A durable task board in `~/.hermes/kanban.db`, shared across your profiles, where named agents pick up, hand off and complete tasks. Agents work it through `kanban_*` tools, while you use `hermes kanban`, `/kanban` or the dashboard. Sources: [Kanban (Multi-Agent Board)](https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban) ## Kanban dispatcher The loop that promotes ready Kanban tasks, claims them and spawns the assigned profile as a worker, reclaiming crashed or stale workers along the way. It runs inside the gateway by default and ticks every 60 seconds. Sources: [Kanban (Multi-Agent Board)](https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban) ## MCP (Model Context Protocol) An open protocol for external tool servers. Hermes connects to MCP servers listed under mcp_servers in config.yaml and uses their tools like built-in ones. Sources: [MCP (Model Context Protocol)](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) ## MCP server mode Running `hermes mcp serve` turns Hermes itself into a stdio MCP server, so clients such as Claude Code or Cursor can list conversations, read history and send messages across its connected platforms. Sources: [MCP (Model Context Protocol)](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) ## Memory tool The tool the agent uses to add, patch or remove memory entries. A memory only persists if the model actually calls it. Sources: [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) ## MEMORY.md The agent's own notes file in ~/.hermes/memories/, covering environment facts, conventions and lessons learned. It's capped at 2,200 characters by default and loaded at the start of every session. Sources: [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) ## Messaging gateway The single background process that connects Hermes to Telegram, Discord, Slack, WhatsApp and other platforms, and also runs cron jobs. Sources: [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) ## Mixture of Agents (MoA) A virtual `moa` provider whose named presets appear as selectable models. Reference models analyse the turn first, then an aggregator model writes the reply and makes tool calls, and the aggregator's provider is billed for the run. Sources: [Mixture of Agents](https://hermes-agent.nousresearch.com/docs/user-guide/features/mixture-of-agents) ## No-agent mode A cron option that runs a script on a schedule and delivers its output verbatim, with no LLM involved. Sources: [Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) ## Nous Portal Nous Research's subscription service, giving one login to 300+ models plus the Tool Gateway. It's set up with hermes setup --portal. Sources: [Nous Portal](https://hermes-agent.nousresearch.com/docs/integrations/nous-portal) ## Nous Research The AI research company that builds and maintains Hermes Agent and runs the Nous Portal subscription service. Sources: [Hermes Agent README (GitHub)](https://github.com/NousResearch/hermes-agent), [Nous Portal](https://hermes-agent.nousresearch.com/docs/integrations/nous-portal) ## Plugin A Python package in ~/.hermes/plugins/ with a plugin.yaml manifest that adds custom tools, hooks or integrations without changing Hermes' core code. Sources: [Plugins](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins) ## Profile A separate Hermes home under ~/.hermes/profiles/ with its own config, keys, memory, sessions and skills, letting you run several independent agents. Sources: [Profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles) ## Progressive disclosure Hermes' token-saving way of loading skills: the agent first sees only names and descriptions, and opens a skill's full content only when needed. Sources: [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) ## Prompt caching Reuse of an unchanged conversation prefix so repeated input is billed more cheaply. Hermes enables it automatically for Claude models via Anthropic or OpenRouter and avoids rebuilding the system prompt mid-conversation, while a `/model` switch resets the cache. Sources: [Context Compression and Caching](https://hermes-agent.nousresearch.com/docs/developer-guide/context-compression-and-caching), [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) ## Secret sources External secret managers (Bitwarden Secrets Manager, 1Password, or a command helper for other vaults) that inject API keys at startup, so only a bootstrap token sits in `.env`. They're configured under `secrets` in `config.yaml`. Sources: [Secrets](https://hermes-agent.nousresearch.com/docs/user-guide/secrets/) ## Session One stored conversation with its full message history, from the CLI or any chat platform. Sessions are kept in ~/.hermes/state.db. Sources: [Sessions](https://hermes-agent.nousresearch.com/docs/user-guide/sessions) ## session_search The agent's tool for searching and scrolling through past conversations stored in state.db. It costs no extra LLM calls. Sources: [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory), [Sessions](https://hermes-agent.nousresearch.com/docs/user-guide/sessions) ## Skill A folder with a SKILL.md file containing on-demand instructions for a task, compatible with the agentskills.io standard. Skills live in ~/.hermes/skills/ and work as slash commands. Sources: [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) ## skill_manage The tool the agent uses to create, update and delete its own skills. The docs call this its procedural memory. Sources: [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) ## SKILL.md The required main file of a skill, holding its name, description and step-by-step instructions. It can be accompanied by references, templates, scripts and assets. Sources: [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) ## Skills Hub The browsable catalog of installable skills from official, skills.sh, GitHub and other sources, managed with hermes skills browse, search and install. Sources: [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) ## Smart approval mode The default approval mode, where a helper model auto-approves low-risk commands, denies clearly dangerous ones and asks you about uncertain cases. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ## SOUL.md A global persona file in your Hermes home that defines the agent's identity and tone. It's the first thing in the system prompt. Sources: [Personality & SOUL.md](https://hermes-agent.nousresearch.com/docs/user-guide/features/personality), [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) ## state.db The SQLite database in your Hermes home that stores session metadata and message history with full-text search. Sources: [Sessions](https://hermes-agent.nousresearch.com/docs/user-guide/sessions), [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) ## Telegram privacy mode A Telegram bot setting, on by default, that hides ordinary group messages from bots. Turn it off in @BotFather and re-add the bot, or make the bot a group admin, so Hermes can see group chat. Sources: [Telegram](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram) ## Terminal backend Where the agent's shell commands run: local, docker, ssh, singularity, modal, daytona or vercel_sandbox. It's set with terminal.backend. Sources: [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) ## Tool A single action the agent can take, such as running a terminal command, reading a file, searching the web or saving memory. Sources: [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) ## Tool Gateway Part of a paid Nous Portal subscription that handles web search, image generation, text-to-speech and cloud browsing without separate vendor accounts. Sources: [Nous Tool Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway) ## Tool Search An opt-in feature that loads tool schemas only when relevant, saving context when many MCP or plugin tools are attached. Sources: [Tool Search](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-search) ## Toolset A named bundle of related tools, for example file or terminal, that you switch on or off together with hermes tools. Sources: [Toolsets Reference](https://hermes-agent.nousresearch.com/docs/reference/toolsets-reference), [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) ## TUI Hermes' modern terminal user interface, launched with hermes --tui, which the docs recommend for interactive use. Sources: [TUI](https://hermes-agent.nousresearch.com/docs/user-guide/tui) ## User allowlist A list of platform user IDs, such as TELEGRAM_ALLOWED_USERS, that are allowed to talk to your bot. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security), [Telegram](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram) ## USER.md The user-profile memory file in ~/.hermes/memories/ for your preferences and communication style. It's capped at 1,375 characters by default. Sources: [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) ## wakeAgent gate A way for a cron job's pre-check script to skip the agent: if the script's last stdout line is `{"wakeAgent": false}`, that run spends no LLM tokens. Leaving it out means the agent runs as usual. Sources: [Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) ## Webhook adapter The gateway component that runs an HTTP server (port 8644 by default), validates HMAC signatures on POSTs from services like GitHub or Stripe and turns them into agent runs. Routes come from `config.yaml` or `hermes webhook subscribe`. Sources: [Webhooks](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/webhooks) ## Website blocklist The `security.website_blocklist` setting lists domains the agent may not reach. It's enforced across `web_search`, `web_extract`, `browser_navigate` and every other URL-capable tool. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) ## Write approval An optional setting (memory.write_approval, and skills.write_approval for skills) that holds the agent's writes for your review. You manage them with commands like /memory pending and /memory approve. Sources: [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory), [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) ## YOLO mode A per-session switch (--yolo or /yolo) that skips approval prompts. The hardline blocklist still applies. Sources: [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) # CLI cheat sheet URL: https://hermeswatcher.com/cheatsheet ## Install & update - `curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash`: Install on Linux, macOS or WSL2 - `iex (irm https://hermes-agent.nousresearch.com/install.ps1)`: Install on native Windows (PowerShell) - `hermes update`: Update a source install to the latest stable release - `hermes update --check`: Show how far behind your channel you are, without updating - `hermes --version`: Show the installed version - `hermes uninstall --dry-run`: Preview uninstall; plain hermes uninstall keeps your data, --full removes everything ## Everyday chat - `hermes`: Start an interactive session (classic CLI) - `hermes --tui`: Start the newer TUI - `hermes chat -q "..."`: Seed a session with a prompt - `hermes -z "..."`: Scripted one-shot that prints only the final reply - `hermes --yolo`: Auto-approve actions (skips approval prompts). Skips every safety prompt: use only in a sandbox. - `!<command>`: Run a shell command from the prompt without a model turn - `Alt+Enter / Ctrl+J`: Insert a newline in the input - `Ctrl+C`: Clear the draft, or interrupt the agent on an empty prompt ## Slash commands in chat - `/help`: Show available commands - `/new`: Start a fresh session (alias /reset) - `/model [model-name]`: Show or change the model - `/undo`: Remove the last user/assistant exchange - `/context [all]`: Show a breakdown of context-window usage - `/usage`: Show token usage and cost - `/personality <name>`: Apply a personality overlay (e.g. concise, pirate; none clears) - `/bg <prompt>`: Run a prompt in a background session - `/btw <question>`: Ask a side question without interrupting - `/rollback`: List or restore filesystem checkpoints - `/quit`: Exit the CLI (alias /exit) ## Models & config - `hermes model`: Interactive provider and model picker - `hermes setup`: Full setup wizard - `hermes setup --portal`: One-shot Nous Portal login plus Tool Gateway - `hermes config set <key> <value>`: Set a value; dotted keys go to config.yaml, UPPER_SNAKE keys to .env - `hermes config get <key>`: Print one value (secrets masked unless --raw) - `hermes config check`: Find missing options after an update - `hermes config set terminal.backend docker`: Run agent commands inside Docker instead of locally - `hermes auth add <provider> --api-key <key>`: Add a key to a provider's credential pool ## Sessions - `hermes --continue`: Resume the most recent session (short: -c) - `hermes --resume <id|title|latest>`: Resume a specific session (short: -r) - `hermes sessions list`: List sessions with title, preview and last-active time - `hermes sessions rename <id> <title>`: Rename a session - `hermes sessions export --format md --session-id <id>`: Export one session as markdown (bulk exports need a filter) - `hermes sessions prune --dry-run`: Preview deleting old ended sessions (90-day default cutoff) ## Memory - `hermes memory setup`: Configure an external memory provider - `hermes journey`: Timeline of learned skills and memories (aliases: learning, memory-graph) - `/memory pending`: List staged memory writes awaiting approval - `/memory approve all`: Apply staged memory writes (or approve <id>) - `/refine`: Run the memory/skill review now ## Skills - `hermes skills browse`: Browse hub skills - `hermes skills inspect <id>`: Preview a skill before installing - `hermes skills install <id>`: Install a skill (with security scan) - `hermes skills list`: List installed skills - `hermes skills update`: Reinstall changed hub skills - `hermes -s <skill>`: Preload a skill for the session - `/<skill-name> [args]`: Load an installed skill and add your instruction - `/learn <source>`: Turn a file, URL, workflow or notes into a skill - `/reload-skills`: Rescan skills and refresh their slash commands ## Tools & MCP - `hermes tools`: Configure enabled tools per platform (interactive) - `hermes chat --toolsets "web,terminal"`: Enable specific toolsets for a run - `/tools`: List available tools in the CLI - `hermes mcp`: Interactive MCP server picker - `hermes mcp install <name>`: Install a catalog MCP server (e.g. deepwiki) - `hermes mcp serve`: Run Hermes as an MCP server - `/reload-mcp`: Reload MCP servers after config changes - `hermes acp`: Run Hermes as an ACP server for editor integration ## Gateway & messaging - `hermes gateway setup`: Configure messaging platforms interactively - `hermes gateway`: Run the gateway in the foreground - `hermes gateway install`: Install as a user service (systemd on Linux, launchd on macOS) - `hermes gateway start`: Start the background service (also stop, restart) - `hermes gateway status`: Check gateway service status - `hermes pairing list`: View pending and approved users - `hermes pairing approve <platform> <code>`: Approve a DM pairing code - `/sethome`: In a chat: mark it as the home channel for deliveries - `/approve`: In a chat: approve a pending dangerous command (/deny rejects) ## Scheduling (cron) - `hermes cron create "every 2h" "Check server status"`: Create a recurring job - `hermes cron list`: Show scheduled jobs - `hermes cron edit <job_id> --schedule "every 4h"`: Change a job's schedule - `hermes cron pause <job_id>`: Pause a job (resume to restart) - `hermes cron run <job_id>`: Trigger a job on the next tick - `hermes cron remove <job_id>`: Delete a job - `/cron add "in 30m" "Remind me to check the build"`: Create a one-shot job from chat - `hermes pause`: Global emergency stop for cron, kanban dispatch and gateway turns (hermes resume to undo) ## Profiles - `hermes profile create <name>`: Create an isolated profile and its <name> command alias - `hermes profile create <name> --clone`: Copy config, .env, SOUL.md, skills and memory from the current profile - `hermes profile list`: List profiles and their status - `hermes profile use <name>`: Set the sticky default profile ("default" switches back) - `hermes -p <name> chat`: Target a profile for one command - `hermes profile export <name>`: Pack a profile into a .tar.gz archive (credentials stripped; -o sets the path) ## Diagnostics - `hermes doctor`: Diagnose config and dependency issues (--fix attempts repairs) - `hermes status --full`: Print every status section (--deep runs slower checks) - `hermes logs -f`: Follow the agent log (names: agent, errors, gateway, mcp, ...) - `hermes dump`: Print a copy-pasteable setup summary for support - `hermes insights`: Token, cost and activity analytics - `hermes backup`: Back up the Hermes home directory to a zip ## Files and folders - `~/.hermes/`: Hermes home and default profile; override with HERMES_HOME - `~/.hermes/config.yaml`: Main non-secret settings: model, terminal backend, memory, skills, compression, display, MCP servers - `~/.hermes/.env`: API keys and other secrets - `~/.hermes/auth.json`: OAuth credentials (e.g. Nous Portal) - `~/.hermes/SOUL.md`: Primary agent identity, loaded first in the system prompt - `~/.hermes/memories/MEMORY.md`: Agent's own notes; ~2,200 character limit - `~/.hermes/memories/USER.md`: Your user profile; ~1,375 character limit - `~/.hermes/skills/<category>/<skill>/SKILL.md`: Installed and agent-created skills - `~/.hermes/state.db`: SQLite session database (messages, FTS5 search index) for CLI, TUI and gateway - `~/.hermes/sessions/`: Gateway session files and /save snapshots (sessions/saved/) - `~/.hermes/cron/jobs.json`: Scheduled job definitions; run output in ~/.hermes/cron/output/ - `~/.hermes/logs/`: Logs such as errors.log and gateway.log, with secrets redacted - `~/.hermes/profiles/<name>/`: A named profile's own config, .env, memories, skills, sessions and cron - `~/.hermes/hermes-agent/`: Source checkout from the POSIX install script - `~/.local/bin/hermes`: CLI entry point (POSIX script install); profile aliases also live in ~/.local/bin/ - `%LOCALAPPDATA%\hermes\`: Windows source-install data directory (code in hermes-agent\, CLI in bin\) - `<repo>/.hermes/skills/`: Project-local skills (must be trusted first) Note: Reflects the official Hermes Agent docs and GitHub README as read on 2026-10-20. The latest stable release at that time was v0.22.2 (Oct 15, 2026), with nightly canary builds on top. Commands and flags change quickly between releases, so check with hermes <command> --help. ## Sources - [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) - [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) - [CLI Guide](https://hermes-agent.nousresearch.com/docs/user-guide/cli) - [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) - [Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation/) - [Updating & Uninstalling](https://hermes-agent.nousresearch.com/docs/getting-started/updating) - [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) - [Sessions](https://hermes-agent.nousresearch.com/docs/user-guide/sessions) - [Profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles) - [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) - [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) - [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) - [MCP Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) - [Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) - [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) - [NousResearch/hermes-agent README](https://github.com/NousResearch/hermes-agent)