---
title: "Deploy Hermes Agent by Nous Research"
description: "Template for Hermes Agent by Nous Research"
category: "AI/ML"
url: https://railway.com/deploy/hermes-railway-template
---

# Deploy Hermes Agent by Nous Research

Template for Hermes Agent by Nous Research

**[Deploy Hermes Agent by Nous Research on Railway](https://railway.com/template/hermes-railway-template)**

- **Creator:** lovexbytes's Projects
- **Category:** AI/ML
- **Total deploys:** 3,626

## Template content

### hermes-railway-template

- **Source:** lovexbytes/hermes-railway-template

## Documentation

# Deploy and Host hermes-railway-template on Railway

hermes-railway-template is a Railway-ready deployment for [Hermes Agent](https://github.com/NousResearch/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:

```env
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:

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

Optional provider variables may be used instead of OpenRouter:

```env
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.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.
- [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack

Open this page in a browser: https://railway.com/deploy/hermes-railway-template