Hermes Agent — Railway Template

Deploy Hermes Agent on Railway with a web-based admin dashboard for configuration, gateway management, and user pairing.

Hermes Agent is an autonomous AI agent by Nous Research that lives on your server, connects to your messaging channels (Telegram, Discord, Slack, etc.), and gets more capable the longer it runs.

Community deployments

For Dockhold, see the community template, maintained separately by the Dockhold team.

Features

• Admin Dashboard — dark-themed setup wizard at /setup to configure providers, channels, tools, and manage the gateway
• Full Hermes Dashboard — the native Hermes web UI (Chat, Keys, Skills, Kanban, Analytics, Console) is proxied at /, behind the same login
• One-Page Setup — provider dropdown, checkbox-based channel/tool toggles — no config files to edit
• Gateway Management — start, stop, restart the Hermes gateway from the browser, with automatic restart if it crashes
• Live Status — gateway state, uptime, model, pending pairing requests, and detected chat-history storage problems
• Live Logs — streaming gateway log viewer
• User Pairing — approve or deny users who message your bot, remove pairing approvals, and see when a separate access rule still grants a user access
• Password-Protected — one cookie-based login guards both the setup wizard and the Hermes dashboard
• Reset Config — one-click reset to start fresh
• Backup & Restore — create a background backup, see its progress after reload, download the prepared zip of Hermes-home data (config, credentials, chat history, skills, and supported provider files), or remove an individual backup after confirmation. The download is available for 6 hours while the container stays up; download it before redeploying. It is not encrypted; a safety snapshot is taken automatically before every restore. External memory services and Hindsight's embedded PostgreSQL data are outside this zip.

Getting Started

The easiest way to get started:

1. Choose an LLM provider

For ChatGPT, deploy first, then select ChatGPT (OAuth) in Setup and authorize your account; no OpenAI API key is needed. For an API-key provider, OpenRouter offers free models:

1. Register for free at OpenRouter
2. Create an API key from your OpenRouter dashboard
3. Pick a free model from the model list sorted by price (e.g. google/gemma-3-1b-it:free, meta-llama/llama-3.1-8b-instruct:free)

2. Set Up a Telegram Bot (fastest channel)

Hermes also has a browser Chat tab. To connect a messaging channel, Telegram is the quickest to set up:

1. Open Telegram and message @BotFather
2. Send /newbot, follow the prompts, and copy the Bot Token
3. Send a message to your new bot — it will appear as a pairing request in the admin dashboard
4. To find your Telegram user ID, message @userinfobot

3. Deploy to Railway

1. Click the Deploy on Railway button above
2. Set the ADMIN_PASSWORD environment variable (or a random one will be generated and printed to deploy logs)
3. Attach a volume mounted at /data (persists config across redeploys)
4. Open your app URL — log in with username admin and your password

4. Configure in the Admin Dashboard

1. LLM Provider — select ChatGPT (OAuth) and connect your account, or choose an API-key provider such as OpenRouter; then choose or enter its model
2. Messaging Channel — check Telegram, paste the Bot Token from BotFather
3. Click Save & Start — the gateway will start and your bot goes live

5. Start Chatting

Message your Telegram bot. If you're a new user, a pairing request will appear in the admin dashboard under Users — click Approve, and you're in.

Environment Variables

All other configuration (LLM provider, model, channels, tools) is managed through the admin dashboard.

Supported Providers

Selectable from the setup wizard's dropdown:

ChatGPT (OAuth), OpenRouter, Anthropic (Claude), Google AI Studio, xAI (API key or SuperGrok OAuth), DeepSeek, Qwen Cloud (DashScope), GLM / Z.AI, Kimi, MiniMax (global and China), NVIDIA NIM, Fireworks AI, NovitaAI, Atlas Cloud, Arcee AI, Step Plan, GMI Cloud, Hugging Face, GitHub Copilot, OpenCode Zen, OpenCode Go, Kilo Code, Ollama Cloud, Actual Computer, AWS Bedrock, Azure Foundry, 9Router, OmniRoute, and any OpenAI-compatible Custom Endpoint.

9Router and OmniRoute are separately deployed routing gateways, not services bundled into this image. Select either one in the setup wizard and enter the gateway's reachable OpenAI-compatible /v1 URL, its endpoint API key, and a model or combo name. Both can remain configured at the same time; OmniRoute defaults the model field to its auto smart-routing alias.

Every other provider Hermes supports can still be configured from the Hermes Dashboard → Keys tab — the wizard covers the common ones, not the limit.

OpenCode Free: Hermes v2026.9.21 removed the anonymous opencode-free provider because its upstream relay now rejects external anonymous clients. Use OpenCode Zen or OpenCode Go with the corresponding API key instead.

ChatGPT OAuth

Select ChatGPT (OAuth) in /setup, click Connect ChatGPT, open the verification link and enter the one-time code. Return to Setup, choose a model from Hermes' list and click Confirm model. The ready message confirms your selection is saved; Save & Start then applies your other settings and starts Hermes. If device login is disabled, enable it in your ChatGPT security settings or ask your workspace administrator. Model access and usage limits depend on your account.

Hermes owns token storage and refresh under /data/.hermes/auth.json. Keep the persistent /data volume attached across redeploys. Tokens are included in unencrypted backups, so store backups securely. Do not copy the same authorization into concurrently running deployments: refresh tokens rotate. This connection does not import conversations from ChatGPT.

Setup manages the default profile. For named profiles and advanced credential pools, use Hermes Dashboard → Keys. Disconnect removes all saved Codex authorizations in the default profile, including its pool; named profiles borrowing that login must reconnect. Hermes briefly stops to clear in-memory credentials. If ChatGPT is the default provider, the gateway stays stopped until you reconnect or choose another provider. Chats, files, other API keys and independent named-profile credentials are kept.

Models selected in the native dashboard are preserved across gateway restarts and unrelated setup saves. If Setup reports that settings changed, reload the page before saving to avoid replacing newer configuration.

Supported Channels

Telegram, Discord, Slack, WhatsApp, Email, Mattermost, Matrix

Supported Tool Integrations

Parallel (search), Firecrawl (scraping), Keenable (search), Tavily (search), Perplexity (search), FAL (image gen), Browserbase, GitHub, OpenAI Voice (Whisper/TTS), Honcho (memory)

Architecture

Build and startup utilities live in template_helpers/; server.py and start.sh are the application and entrypoint.

One container runs a single public process that fronts two managed Hermes subprocesses:

Railway Container
└── server.py — Starlette + Uvicorn on 0.0.0.0:$PORT   (the only public surface)
    ├── /login, /logout    — cookie login (7-day, httponly)
    ├── /health            — health check (no auth)
    ├── /setup             — this template's setup wizard
    ├── /setup/api/*       — config, status, logs, gateway, pairing, backup, OAuth
    ├── /  and  /*         — reverse-proxied to the native Hermes dashboard
    │
    ├── hermes dashboard   — native Hermes web UI, bound to 127.0.0.1:9119
    └── hermes gateway     — the agent itself (Telegram, Discord, …), auto-restarted

The Hermes dashboard is never exposed directly — it binds loopback and is reachable only through the proxy, so one login covers both UIs. The gateway is supervised: if it crashes or is OOM-killed, server.py restarts it with backoff, giving up only if it fails repeatedly (Railway would not restart it on its own, because server.py is still alive and healthy). If a config save or restore respawns the dashboard while Chat is open, the terminal connection retries automatically.

Hermes uses its managed Python runtime with SQLite 3.53.1, which includes the WAL-reset fix. The image also builds shared SQLite 3.53.4 for Debian's dynamically linked consumers. Build checks exercise session databases, WAL and FTS with the actual application interpreter.

Hermes can serve all live named profiles from this one gateway. The template's /setup page remains the default-pr