Hermes Agent Complete Guide — Everything You Need to Know
Hermes Agent is an autonomous AI agent platform that runs coding agents, orchestrates multi-agent swarms, deploys bots across 20+ messaging platforms, and builds custom plugins and skills. This guide covers everything — from installation to advanced A2A protocol orchestration.
Bot Mode
Run autonomous agents via Telegram, Discord, Slack, WhatsApp, Signal, and 20+ other platforms.
→ Learn more
Plugin Development
Build custom plugins, tools, skills, and integrations — extend Hermes with your own capabilities.
→ Learn more
A2A Protocol
Agent-to-agent communication, discovery, negotiation, and multi-agent swarm coordination.
→ Learn more
Content Publishing & Distribution
Automated content creation, publishing, and distribution across channels using autonomous agents.
→ Learn more
What Is Hermes Agent?
Hermes Agent is a personal AI agent that runs the same agent core across a CLI, a messaging gateway (Telegram, Discord, Slack, and ~20 other platforms), a TUI, and an Electron desktop app. It learns across sessions (memory + skills), delegates to subagents, runs scheduled jobs, and drives a real terminal and browser.
It is extended primarily through plugins and skills, not by growing the core. Two properties shape every design decision: per-conversation prompt caching is sacred, and the core is a narrow waist — capability lives at the edges.
Core Capabilities
Terminal & File Access
Hermes drives a real terminal — runs shell commands, scripts, builds, git operations, language servers. Reads and writes files with full content visibility. Executes code in isolated contexts.
Web & Browser
Web search, page extraction, browser navigation with a real headless browser (Browser Use). Scrapes sites, extracts content, fills forms, clicks elements, captures screenshots.
Subagent Delegation
Spawns isolated sub-agents with their own terminal sessions and toolset. Batch mode runs multiple sub-agents in parallel. Background delegation returns a handle and the result re-enters later.
Cron & Scheduling
Schedule recurring agent runs — duration-based, "every" phrases, cron expressions, or ISO timestamps. Monitor scripts detect changes and suppress runs when nothing changed.
Memory & Skills
Cross-session memory via pluggable backends. Skills are markdown-driven capability packs with scripts, templates, and references. Both persist and improve across conversations.
Kanban & Dispatch
Durable SQLite-backed boards for multi-agent collaboration. Workers spawned per-task with isolated contexts. Dispatcher reclaims stale claims and promotes ready tasks.
Platform Support
Hermes connects to 20+ messaging platforms through adapter plugins. Each adapter handles the platform's specific API, message format, and delivery semantics.
Deployment Options
CLI / TUI
Run locally with `hermes` or `hermes --tui`. Full terminal UI, keyboard-driven, rich display with animated spinners and activity feed.
Gateway (Cloud)
`hermes serve` or `hermes dashboard` — headless backend that spawns bots detached. Survives app restart. Bots keep running when the user closes the desktop app.
Electron Desktop
Native desktop app with embedded chat, terminal pane, and bot roster. Talks to a `tui_gateway` backend over JSON-RPC. Separate from the CLI and dashboard surfaces.
Container / Server
Run the gateway as a systemd service or Docker container for always-on bot operations. Fleet update pipeline handles upgrades across multiple instances.
Model & Provider Support
Hermes is model-agnostic. Every inference backend ships as a plugin under `plugins/model-providers/`. Current built-in providers include OpenAI, Anthropic, Gemini, OpenRouter, Deepseek, NVIDIA, and custom endpoints. Each plugin registers a ProviderProfile at module load.
Smart model routing lets you pin different models for different task types — coding, research, vision, curation, title generation. You can override per-session, per-tool, or per-cron-job.
Security Model
- ✓Per-profile isolation: every profile has its own HERMES_HOME — config, API keys, memory, sessions, skills, gateway, everything. No cross-contamination.
- ✓Token-scoped locks: adapters acquire scoped locks on connect to prevent two profiles from using the same credential simultaneously.
- ✓Secret scoping: multiplex profiles read env vars from their own secret scope — never borrow from the default profile's os.environ. Fail-closed, never fail-open.
- ✓Allowlists & admission: per-platform user/group allowlists, bot policies, and group-level routing rules. Unauthorized senders are rejected cleanly.
- ✓Env var policy: `.env` is for secrets only (API keys, tokens, passwords). All behavioral settings — timeouts, thresholds, feature flags — go in `config.yaml`.
Customization
Skin Engine
Data-driven CLI theming. Skins customize banner colors, spinner faces/verbs/wings, tool prefix, response box, branding text. Built-in skins: default, ares, mono, slate. Users can create custom YAML skins.
Skills System
Built-in skills in `skills/` (shipped and loadable by default) and optional skills in `optional-skills/` (heavier/niche, installed explicitly). Skills have SKILL.md frontmatter, scripts, templates, and references.
Toolsets
Toolsets are groups of tools that can be enabled/disabled per platform. Current toolsets: browser, terminal, file, search, vision, delegation, cronjob, memory, skills, kanban, todo, tts, video, image_gen, and 20+ more.
Ideal For
- ●Individual developers: a CLI agent that drives your terminal, reads files, runs commands, searches the web, and persists across sessions
- ●Small teams: a shared bot in Discord/Slack/Telegram that handles deployments, research, monitoring, and incident triage
- ●Content operations: autonomous agents that research, write, publish, and distribute content — 300+ articles generated this way
- ●Managed services: MSPs and IT consultancies running bots for client monitoring, incident response, security compliance, and cloud cost optimization
- ●Multi-agent swarms: orchestrators spawning leaf agents for parallel research, coding, analysis — coordinating via the A2A protocol
- ●Enterprises: custom plugin development, on-premise model integration, compliance automation, and proprietary system connectors
Getting Started
- 1Install Hermes: `pip install hermes-agent` or clone the repo and set up your Python environment. Configure your model provider and API key in `~/.hermes/config.yaml`.
- 2Choose your interface: CLI for local development, TUI for a richer terminal experience, gateway for cloud-hosted bots, or Electron desktop for a native app.
- 3Connect a platform: set up a Telegram bot, Discord bot, Slack app, or any of the 20+ supported platforms. Configure the adapter in config.yaml with your bot token.
- 4Load skills: install and enable skills for your use case — GitHub workflows, research methods, creative tools, devops procedures. Skills inject domain knowledge into the agent.
- 5Start delegating: ask Hermes to research, code, deploy, monitor, or coordinate. Use delegation for parallel work, cron for scheduled runs, kanban for multi-agent collaboration.
- 6Extend it: build custom plugins, skills, tools, and integrations. The plugin system is the primary extension point — no core changes needed.