Hermes Agent Docker on cheap VPS + Telegram bot in 2026: gateway, pairing, and security runbook

Hermes Agent (NousResearch/hermes-agent) is built to run on a $5 VPS, not only on a laptop. The official Docker image nousresearch/hermes-agent stores all state under a host-mounted ~/.hermes:/opt/data directory, and the gateway process connects Telegram, Discord, Slack, and other platforms from one background service. This runbook walks through Docker install on a budget VPS, Telegram bot creation, allowlist security, and a persistent docker compose deployment. Official references: Docker user guide, messaging gateway, and the team Telegram assistant guide.

If you are comparing agent harnesses on Apple hardware, read Hermes Agent vs OpenClaw on macOS and Mac mini M4. After long Telegram sessions inflate context, tune memory and tokens with Hermes trajectory_compressor on Mac mini M4. Those articles cover local staging; this page focuses on Linux VPS plus Docker for 24/7 Telegram.

Disclosure: MacHTML offers optional cloud Mac mini rental for staging agent configs; this guide focuses on Linux VPS and Docker and does not require a Mac.

Why Docker on a cheap VPS

Hermes needs a process that stays online while you sleep. A laptop closes the lid; a cheap VPS (often 1–2 vCPU, 2–4 GB RAM, $4–$6/month) can run gateway run around the clock without tying up your personal machine.

Docker adds three practical wins for operators who deploy weekly, not once. First, reproducible installs: pull nousresearch/hermes-agent:latest instead of debugging Python 3.11, Node, and distro-specific packages on every fresh VPS. Second, isolated upgrades: replace the container image while keeping ~/.hermes on the host—sessions, memories, and API keys survive the swap. Third, an optional command sandbox: set TERMINAL_BACKEND=docker so agent shell tools execute inside a separate sandbox container, not directly on the host kernel.

Telegram is the fastest channel to validate the stack end to end. Create a bot with @BotFather, drop the token into ~/.hermes/.env, add your numeric user id to TELEGRAM_ALLOWED_USERS, and message the bot within seconds. The gateway default policy denies unknown users; do not enable GATEWAY_ALLOW_ALL_USERS=true on any bot that can run terminal commands.

A VPS also gives you a stable public IP and predictable uptime for cron-driven tasks. Hermes ticks cron every 60 seconds inside the gateway; if the host reboots, restart: unless-stopped in Compose brings the gateway back without manual intervention.

Compared with running Hermes on a home NAS or Raspberry Pi, a small cloud VM usually has better outbound connectivity to Telegram APIs and LLM providers, plus provider snapshots for disaster recovery. Bind-mount ~/.hermes and snapshot that directory before major upgrades.

If you operate from mainland China, choose a region with stable egress to Telegram and your LLM endpoints, or plan a proxy path. The official image pulls from Docker Hub; domestic mirror acceleration can help on slow links, but verify image digests when mirroring.

Finally, Docker Compose makes handoffs easy: document one compose file, one data directory, and one pairing workflow so teammates can reproduce production on a staging VPS before promoting config changes.

Architecture: gateway in a container

Internet → Telegram API → VPS:hermes container (gateway run)
                                              ↳ /opt/data  (bind-mount ~/.hermes)
                                                   ├─ .env          (TELEGRAM_BOT_TOKEN, API keys)
                                                   ├─ config.yaml   (terminal, models, cron)
                                                   ├─ sessions/     (per-chat history)
                                                   └─ memories/     (curated long-term memory)

The gateway is one long-lived process that multiplexes messaging platforms. It routes each Telegram chat through a session store under /opt/data/sessions/, dispatches work to the agent loop, and persists curated long-term memory under /opt/data/memories/. All of that state lives on the host because you bind-mount ~/.hermes:/opt/data.

Never mount the same /opt/data into two gateway containers. Session files are not safe for concurrent writers; running duplicate gateways against one data directory causes corruption and duplicate message handling. One compose service named hermes with command: gateway run is the production pattern.

Port 8642 exposes an optional OpenAI-compatible API and health endpoint. You can omit publishing it if you only use Telegram. When enabled, set API_SERVER_ENABLED=true, bind carefully, and protect the endpoint with a strong API_SERVER_KEY plus firewall rules.

VPS sizing and cost

Gateway RAM is the main constraint once Telegram traffic is steady. The agent container holds model context; sandbox containers add overhead when terminal.backend: docker is enabled. Disk grows with session history, downloaded skills, and memory files—plan headroom before cron jobs accumulate logs.

The table below maps four common profiles. Start at Recommended if you expect shell tools or more than one admin; use Budget lab only for short pairing tests, then resize before going live.

Profile	vCPU	RAM	Disk	Typical monthly	Fit
Minimum	1	2 GB	20 GB	~$4–5	Telegram-only gateway, no dashboard, single user
Recommended	2	4 GB	40 GB	~$6–8	Gateway + TERMINAL_BACKEND=docker sandbox for shell tools
Heavy	2+	8 GB	60 GB	~$12+	Dashboard, cron jobs, large skills tree, multiple admins
Budget lab	1	1 GB	15 GB	~$3–4	Smoke tests and pairing validation only—not production

Step-by-step runbook

1. Install Docker on the VPS — On Ubuntu 22.04 or newer, install docker.io and docker-compose-v2, then add your user to the docker group so compose works without sudo.

   sudo apt update && sudo apt install -y docker.io docker-compose-v2
                   sudo usermod -aG docker $USER
                   newgrp docker

2. Create the persistent data directory — All secrets, sessions, and config live under ~/.hermes on the host; back up this folder before image upgrades.

   mkdir -p ~/.hermes

3. Run the interactive setup wizard once — Pull nousresearch/hermes-agent and mount ~/.hermes:/opt/data so the wizard writes .env and config.yaml into the bind mount.

   docker run -it --rm                   -v ~/.hermes:/opt/data                   nousresearch/hermes-agent setup

4. Create the Telegram bot and allowlist — Use @BotFather for the bot token and @userinfobot for your numeric user id. Default gateway policy denies unknown users—never set GATEWAY_ALLOW_ALL_USERS=true on a bot with terminal access.

   TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
                   TELEGRAM_ALLOWED_USERS=987654321

5. Approve DM pairing codes (optional) — If you skip pre-allowlisting, unknown users receive a one-hour pairing code; approve it from the host with pairing approve.

   docker run --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent pairing approve telegram XKGH5N7P

6. Smoke-test gateway run in the foreground — Start gateway run interactively, send /help to the bot, and confirm slash commands like /model and /compress before going to production.

   docker run --rm -it                   -v ~/.hermes:/opt/data                   nousresearch/hermes-agent gateway run

7. Deploy with Docker Compose (production) — Use restart: unless-stopped, bind-mount ~/.hermes:/opt/data, and cap memory/CPU so a runaway agent cannot exhaust the VPS.

   services:
                     hermes:
                       image: nousresearch/hermes-agent:latest
                       container_name: hermes
                       restart: unless-stopped
                       command: gateway run
                       volumes:
                         - ~/.hermes:/opt/data
                       deploy:
                         resources:
                           limits:
                             memory: 4G
                             cpus: "2.0"

   docker compose up -d
                   docker logs -f hermes

8. Harden terminal access for team bots — Set terminal.backend: docker in config.yaml so shell tools run inside a sandbox container instead of on the host kernel.

   # ~/.hermes/config.yaml excerpt
                   terminal:
                     backend: docker
                     container_cpu: 1
                     container_memory: 5120
                     container_persistent: true

Troubleshooting

Bot never replies; logs show Telegram 401

Regenerate the token in @BotFather, update TELEGRAM_BOT_TOKEN in ~/.hermes/.env, then run docker compose restart hermes. A stale token is the most common cause of silent failures after bot renames or token revocations.

Unauthorized message or endless pairing prompts

Add your personal numeric id—not the bot id—to TELEGRAM_ALLOWED_USERS, or run pairing approve telegram <code>. Confirm only one gateway container mounts ~/.hermes; duplicate gateways can race session files and reject valid users.

Ready for scoped repo access, npm test, and guarded auto-fix? Read Hermes Agent MCP for Claude Opus 4.8: local code sandbox in 2026.

FAQ

Can I run Hermes Docker on a Mac mini instead of a VPS?

Yes—the same docker run and compose patterns work on Docker Desktop or Colima. A VPS is usually cheaper for Telegram-only 24/7 workloads; a Mac mini M4 is better when you need local Apple toolchains or Xcode-adjacent skills. MacHTML cloud Mac staging is optional, not required for this VPS guide.

Do I need to expose port 8642?

No for Telegram-only chat. Enable port 8642 only if you need the OpenAI-compatible API or external health checks—and set API_SERVER_ENABLED=true, API_SERVER_HOST=0.0.0.0, and a strong API_SERVER_KEY (at least eight characters) with firewall rules.

How is this different from OpenClaw Telegram guides?

OpenClaw articles on this site target Node.js gateway installs on cloud Mac hardware. Hermes uses hermes gateway with native Telegram adapters and Docker-first documentation from Nous Research.

What slash commands should I test first?

After the first successful reply, send /status, /model, /compress, and /new. Admins can run gated commands; regular users remain limited to the allowlist configured in gateway settings.