Deploy and Host hermes-railway-template on Railway

hermes-railway-template is a Railway-ready deployment for Hermes Agent, configured as a worker service with persistent state. It builds Hermes from a pinned upstream tag or commit, bootstraps Hermes on first run using Railway Variables, then reuses saved configuration and state from a mounted volume. The template supports Telegram, Discord, or Slack and works with OpenRouter, OpenAI-compatible providers, or Anthropic.

About Hosting hermes-railway-template

Hosting hermes-railway-template on Railway centers on a worker-first runtime with persistent storage. During setup, you deploy the service as a worker, mount a volume at /data, set HERMES_GIT_REF to a pinned Hermes Agent tag or commit, and provide required environment variables for both an inference provider and at least one messaging platform.

On startup, the entrypoint initializes Hermes under /data/.hermes, writes runtime environment values from Railway Variables into ${HERMES_HOME}/.env, creates ${HERMES_HOME}/config.yaml if missing, and records a first-run marker at ${HERMES_HOME}/.initialized. On subsequent boots, the persisted Hermes home is reused while runtime variables are refreshed from Railway. The container then starts the Hermes messaging gateway as a Railway worker, giving you a stable bot deployment that can survive restarts and redeploys while keeping credentials and access controls managed through Railway Variables.

Common Use Cases

• Deploying an AI chat gateway bot to Telegram, Discord, or Slack
• Running Hermes with persistent state across Railway redeploys
• Quickly standing up a worker-based agent service backed by OpenRouter, OpenAI-compatible APIs, or Anthropic

Dependencies for hermes-railway-template Hosting

• Railway worker service with a persistent volume mounted at /data
• HERMES_GIT_REF set to a specific Hermes Agent upstream tag or commit SHA
• Runtime variables for one inference provider:
  • OPENROUTER_API_KEY, or
  • OPENAI_BASE_URL plus OPENAI_API_KEY, or
  • ANTHROPIC_API_KEY
• Runtime variables for at least one messaging platform:
  • Telegram: TELEGRAM_BOT_TOKEN
  • Discord: DISCORD_BOT_TOKEN
  • Slack: SLACK_BOT_TOKEN and SLACK_APP_TOKEN
• Strongly recommended allowlists:
  • TELEGRAM_ALLOWED_USERS
  • DISCORD_ALLOWED_USERS
  • SLACK_ALLOWED_USERS

Deployment Dependencies

• Railway Volumes (persistent storage): https://docs.railway.com/guides/volumes
• Railway Variables (secrets and config): https://docs.railway.com/guides/variables
• Railway SSH (manual Hermes commands after deploy): https://docs.railway.com/cli/ssh
• Hermes Agent docs (runtime variables and behavior): https://github.com/NousResearch/hermes-agent/blob/main/README.md

Implementation Details

Required template defaults:

HERMES_HOME=/data/.hermes
HOME=/data

Hermes terminal sessions default to /data/workspace through ${HERMES_HOME}/config.yaml, not through a persisted MESSAGING_CWD variable. If an older deployment still has MESSAGING_CWD, the entrypoint migrates it into config.yaml and unsets it before starting Hermes.

Example Railway variables:

HERMES_GIT_REF="v2026.5.16"
OPENROUTER_API_KEY=""
TELEGRAM_BOT_TOKEN=""
TELEGRAM_ALLOWED_USERS=""

Optional provider variables may be used instead of OpenRouter:

OPENAI_BASE_URL=""
OPENAI_API_KEY=""
ANTHROPIC_API_KEY=""
HERMES_INFERENCE_PROVIDER=""

On startup, scripts/entrypoint.sh validates provider and platform variables, writes selected runtime variables to ${HERMES_HOME}/.env, creates ${HERMES_HOME}/config.yaml if missing, migrates legacy terminal cwd settings, persists ${HERMES_HOME}/.initialized, warns when no allowlist is configured, and starts hermes gateway.

For updates, do not run hermes update inside the Railway deployment. Instead, change HERMES_GIT_REF to a pinned upstream tag or commit SHA and redeploy the service. If upstream introduced new config options, use Railway SSH after redeploy to run manual Hermes commands such as hermes config migrate.

Why Deploy Hermes on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Hermes on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.