How to deploy a Hermes Agent in Docker (and the one-click alternative)

Path 1 — DIY: build the image and run with Docker

Hermes Agent doesn't have a published Docker image, so you build from source. You'll need a Linux host with Docker installed and at least 4 GB of RAM (the image bundles the Python ML stack and a Playwright Chromium for tool use; total ~6–8 GB on disk).

# 1. Build the image (this takes ~10 minutes on a 4-core box)
docker build -t hermes-agent:latest https://github.com/NousResearch/hermes-agent.git#main

# 2. Create a host directory for agent state and config
mkdir -p /opt/hermes/data
chown 1001:1001 /opt/hermes/data

Hermes uses a YAML config file for model and provider selection. Drop a config.yaml into the agent directory:

# /opt/hermes/data/config.yaml
model:
  default: claude-sonnet-4-6
  provider: anthropic
  api_key: ${ANTHROPIC_API_KEY}

channels:
  telegram:
    enabled: true
    token: ${TELEGRAM_BOT_TOKEN}

# 3. Run the container
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e TELEGRAM_BOT_TOKEN=123456:ABC-... \
  -v /opt/hermes/data:/home/hermes/.hermes \
  hermes-agent:latest gateway run

gateway run starts the messaging gateway only — Hermes intentionally exposes no public HTTP endpoint (the dashboard would surface key management, which is unsafe for a multi-tenant host). All traffic flows through the configured messaging channels.

A few things that will trip you up:

• UID mismatch. Hermes runs as UID 1001 inside the container; your host bind-mount needs to be writable by that UID. chown 1001:1001 /opt/hermes/data fixes it.
• The hermes -z one-shot CLI is broken upstream for the custom and openrouter provider paths — it saves your message but never produces an assistant response (KeyError: 'final_response'). Real messaging traffic via gateway run works fine; don't waste time debugging the CLI.
• Camoufox cache. The image ships with ~2 GB of Playwright/Camoufox browser data. You can strip it with rm -rf /tmp/camoufox-* /root/.cache/camoufox in a downstream Dockerfile if disk is tight.

You're also on the hook for HTTPS (Caddy or Nginx in front, if you need any inbound HTTP), restarts (systemd unit or Docker's --restart), log rotation, and provider-key encryption at rest — the YAML above stores them in plaintext.

Path 2 — Managed: one click on VibeOpenClaw

VibeOpenClaw runs Hermes in a managed Docker container with the gnarly bits already solved — UID setup, config seeding, key encryption (AES-256-GCM at rest), bind-mount permissions, log access, automatic restarts. You sign up, pick Hermes as the agent type, paste your provider API key and channel bot tokens, and the container starts in ~30 seconds.

Concretely, the flow is:

1. Sign up at app.vibeopenclaw.com on the Premium plan (Hermes requires Premium — Pro is OpenClaw-only).
2. Add your provider key on the API Keys page (OpenAI, Anthropic, Google, Groq, xAI, Mistral, DeepSeek, Together, Fireworks, Perplexity, OpenRouter, Cohere, and NVIDIA are all first-class).
3. Click New Agent → choose Hermes → pick the model → paste your Telegram/Discord/Slack bot token → Create.

That's it. You don't touch a YAML file, build an image, or chown anything. Resource quotas (4 GB RAM per Hermes agent, up to 3 agents on Premium) are pre-tuned to Hermes's documented requirements.

Which one should you pick?

DIY if you're comfortable operating Docker, want full filesystem access for experimentation, and are running on a box you already have. Managed if you want Hermes running in 30 seconds with sane defaults, encrypted keys, and a single bill instead of (VPS + DNS + SSL + monitoring + your time). The break-even for most people is one or two evenings of debugging.

If you're still deciding between Hermes and OpenClaw entirely, see the OpenClaw vs Hermes comparison.

Sources

• NousResearch/hermes-agent — official repository (178k+ stars as of June 2026), build and config reference.
• Model Context Protocol — the tool-integration standard Hermes uses.
• Docker BuildKit docs — required for the image's --chmod build steps.