Hermes Agent

Autonomous AI agent from Nous Research, driven from Telegram.

Overview

This template runs Hermes Agent by Nous Research. Hermes is an autonomous agent: you send it a task over Telegram, and it works on it with its own tools rather than answering a single prompt. The template wraps the upstream image with a start command (upstream's default process is an interactive terminal UI that exits without a TTY) and runs the messaging gateway with the web dashboard beside it, state on a persistent volume.

The dashboard is what the service URL serves; Telegram is how you give the agent work.

What you get by hosting it

• An HTTPS URL for the Hermes dashboard, behind a password (username admin), with no port forwarding or tunnel to manage. Upstream refuses to expose the dashboard without one.
• A 1 GiB volume mounted at /data, with HERMES_HOME pointed at /data/.hermes so the agent's state survives restarts and redeploys.
• The gateway token generated for you (64 chars) and stored as a managed secret, so it is never committed anywhere or shown in the manifest.
• Your API keys and bot token held as managed secrets rather than baked into an image.
• Deploys are health-gated against /api/status, so a container that never becomes ready is rolled back rather than left serving errors.

What you need before deploying

• An OpenRouter API key. The agent calls models through OpenRouter.
• A Telegram bot token, created with @BotFather: send /newbot, pick a name and a username ending in bot, and it replies with the token.
• The numeric Telegram user IDs allowed to use the bot, not @usernames. Message @userinfobot and it replies with yours. Comma-separate several. A username here does not match anything, and the bot silently ignores you.

Configuration

Set by the template, not by you: HERMES_HOME=/data/.hermes (state on the volume) and HERMES_DASHBOARD_PORT=8080. The entrypoint binds the dashboard and runs the gateway.

After deploy

1. Wait for the health check on /api/status to pass, then open the service URL to reach the dashboard.
2. Open Telegram and message your bot from one of the user IDs in TELEGRAM_ALLOWED_USERS. Messages from anyone else are ignored.
3. Give the agent a task in the chat. Progress and history are visible in the dashboard.
4. State lives under /data/.hermes, so restarts and redeploys keep the agent's memory. Deleting the volume resets it.

Links

• Documentation: https://hermes-agent.nousresearch.com/docs/
• Upstream: https://github.com/NousResearch/hermes-agent
• Image: docker.io/nousresearch/hermes-agent, pinned to v2026.8.16
• License: MIT (upstream NousResearch/hermes-agent).