Bot Mode turns Hermes Agent into a persistent messaging bot that operates across Telegram, Discord, Slack, WhatsApp, Signal, and 20+ other platforms. Your agents execute real terminal commands, browse the web, read/write files, call APIs, and deliver results — all through the chat interface your team already uses. This guide covers everything from setup to advanced multi-agent coordination.
A Hermes Agent bot is a persistent process that connects to a messaging platform via its adapter. When a user sends a message, the agent receives it, runs its conversation loop with the configured LLM, and can call any available tool — terminal commands, file operations, web searches, browser navigation, cron scheduling, delegation to sub-agents, and more.
The agent runs with the full toolset of a regular Hermes session. It can create cron jobs, spawn sub-agents, write files, execute code, search the web, and navigate browsers — all triggered from a chat message. Results come back as messages in the same conversation.
Bot Mode is not a chatbot. It doesn't just answer questions — it does things. It runs your terminal. It browses the web. It writes files. It schedules cron jobs. It delegates to sub-agents. It's an autonomous worker that happens to communicate through chat.
Hermes connects to 20+ messaging platforms through adapter plugins. Each adapter handles the platform's specific API, message format, and delivery semantics. The full list:
Each adapter is a separate module under gateway/platforms/. New adapters can be added without touching the core — the platform adapter pattern keeps the gateway modular.
The most common setup is a Telegram bot. Here's the workflow:
config.yaml, or store it in ~/.hermes/.env as TELEGRAM_BOT_TOKEN.Once connected, your bot has access to the full Hermes toolset — the same tools available in the CLI. Here's what that means in practice:
Run shell commands, scripts, git operations, builds. The bot drives a real terminal — not a simulated one. Background processes for long-running tasks.
Read files with full content visibility (up to 2000 lines per read), write new files, patch existing ones with targeted edits. Markdown, code, config — any text file.
Search the web, extract page content as clean markdown, crawl sites for specific data. Works with PDF URLs too — pass the PDF link directly.
Drive a real headless browser via Browser Use. Navigate pages, fill forms, click elements, extract DOM text, capture screenshots. Handles login walls (stops and asks).
Execute Python scripts that call Hermes tools programmatically — web search, terminal, file ops, patch, search_files. Up to 50 tool calls per script, 5-minute timeout.
Schedule recurring agent runs from chat. Duration-based ("30m"), "every" phrases ("every 2h"), cron expressions ("0 9 * * *"), or ISO timestamps. Monitor scripts detect changes.
Tools are organized into toolsets — groups that can be enabled/disabled per platform. Current toolsets include browser, terminal, file, search, vision, delegation, cronjob, memory, skills, kanban, todo, tts, video, image_gen, and 20+ more.
The full CLI command surface is available in chat via slash commands. The gateway intercepts and dispatches them. Key commands:
/new — new conversation/resume — resume a session/stop — stop the running agent/queue — view queued messages
/status — agent status/copy — copy last response/paste — paste content/help — command help
/skin — switch CLI skin/tools — manage enabled toolsets/hermes config — config management
/skills — manage skills/cron — manage cron jobs/kanban — manage boards
Hermes supports profiles — multiple fully isolated instances, each with its own HERMES_HOME directory. This means you can run multiple bots on one server without cross-contamination:
hermes -p <profile> to run a specific profile_get_profiles_root() returns Path.home() / ".hermes" / "profiles"This is critical for production: if you run a Telegram bot for your team and a separate Discord bot for another team, they must not share config, keys, or session state. Profiles enforce that isolation.
Bot Mode supports several background operation patterns:
Schedule recurring agent runs. The scheduler ticks every 60 seconds by default. Supports duration, "every" phrases, cron expressions, and ISO timestamps. Catchup window: half the job's period. 3-minute hard interrupt on cron sessions.
Spawn sub-agents with isolated contexts + terminal sessions. Background delegation returns a handle immediately — the result re-enters the conversation later. Batch mode runs multiple sub-agents in parallel (capped by delegation.max_concurrent_children).
Terminal commands with background=true run in the background. The gateway watches for completion and triggers a new agent turn. Control verbosity via display.background_process_notifications.
Bot Mode inherits Hermes' full security model. Key points for production deployments:
os.environ. Fail-closed, never fail-open..env lives only in its secret scope. Under multiplex, os.environ holds the default profile's values — a secondary profile's credentials are never leaked.Run `hermes` or `hermes --tui` for local development. Full terminal UI, keyboard-driven. Good for personal use and testing.
Run `hermes serve` or `hermes dashboard` for a headless backend. Bots spawn detached — they survive app restarts. The messaging gateway (`gateway run`) SURVIVES the app by design.
Native desktop app with embedded chat, terminal pane, and bot roster. Talks to a tui_gateway backend over JSON-RPC. Separate from CLI and dashboard.
Run the gateway as a systemd service or Docker container for always-on bot operations. Fleet update pipeline handles upgrades across multiple instances.
The gateway lifecycle: hermes serve (control plane, desktop-spawned child) dies with the app — by design. The messaging gateway (`gateway run`) SURVIVES the app: the serve backend's `/api/gateway/*` endpoints spawn it detached, so `before-quit`'s backend SIGTERM never reaches it. Bots keep running when the user closes the app.
Research, file management, web lookups, scheduling — all from your phone via Telegram. The agent is available 24/7, remembers context across sessions, and can run long tasks in the background.
Deployed in a Slack/Discord/Telegram channel, handles deployments, monitors, alerts, and incident triage. Team members interact with it naturally — no new UI to learn.
Scheduled cron jobs that publish blog posts, monitor competitors, scrape data, and deliver digests. One agent outlines, several write, one edits, one publishes — all negotiating and coordinating automatically.
An orchestrator bot spawns leaf agents for parallel research, coding, or analysis. Agents coordinate via the A2A protocol, negotiate tasks, and report back — all triggered from chat.