---
title: "Deploy Hermes Agent · Quick Start"
description: "Nous Research AI agent with web chat, memory and Telegram/Discord/Slack"
category: "AI/ML"
url: https://railway.com/deploy/hermes-agent-quick-start
---

# Deploy Hermes Agent · Quick Start

Nous Research AI agent with web chat, memory and Telegram/Discord/Slack

**[Deploy Hermes Agent · Quick Start on Railway](https://railway.com/template/hermes-agent-quick-start)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/hermes-agent-quick-start/manifest.json

- **Creator:** withSeismic
- **Category:** AI/ML

## Template content

### hermes

- **Image:** nousresearch/hermes-agent:latest
- **Start command:** `/opt/hermes/docker/entrypoint-dispatch.sh gateway run`
- **Health check:** /api/health
- **Public domain:** Yes

## Documentation

# Deploy and Host Hermes Agent on Railway

Hermes Agent is Nous Research's open-source AI agent. It remembers across sessions, writes and reuses its own skills, runs scheduled jobs, and can talk to you in the browser, from Telegram, Discord or Slack, or through an OpenAI-compatible API. This template runs the official `nousresearch/hermes-agent` image with its web dashboard behind a generated password, and keeps all agent state on a persistent volume.

## About Hosting Hermes Agent

- **Official image, tracking upstream.** Runs `nousresearch/hermes-agent:latest` from Docker Hub. It is not a fork, wrapper or source build.
- **Gateway and dashboard together, supervised.** The image's own s6 supervisor runs the messaging gateway and the web dashboard in one service and restarts either if it crashes.
- **Locked down by default.**
  - The dashboard requires a login, with the password generated at deploy. There is no default password and no sign-up.
  - Unauthenticated requests to the dashboard API and the Chat terminal are refused.
- **Durable.**
  - Memory, skills, sessions, cron jobs, config, provider logins and API keys live in `/opt/data` on a Railway volume, so they survive restarts, redeploys and image upgrades.
  - The session-signing secret is a fixed variable, so you stay logged in across redeploys.
- **Private API server.**
  - The OpenAI-compatible API (`/v1/chat/completions`) listens only on Railway's private network.
  - It needs a generated bearer key, so other services in your project can use Hermes as a model without exposing it to the internet.
- **Safe messaging defaults.**
  - Telegram, Discord and Slack are optional.
  - Strangers who message your bot get a pairing code you must approve. The bot does not answer everyone.
- **Healthchecked.** Railway waits for `/api/health` before it routes traffic to a new deploy.

### Getting started

1. **Deploy the template.**
   - If you have an [OpenRouter](https://openrouter.ai/keys) key, paste it into `OPENROUTER_API_KEY`. That is the quickest way to get a working model.
   - Everything else is optional and can be added later.
2. **Copy your password.** When the deploy turns green, open the `hermes` service → **Variables** and copy `HERMES_DASHBOARD_BASIC_AUTH_PASSWORD`.
3. **Sign in.** Open the service's public URL (Settings → Networking) and log in as `admin` with that password.
4. **Connect a model provider** if you did not set one at deploy. Pick one:
   - **API key:** open **API Keys** in the dashboard and paste an OpenRouter, OpenAI, Anthropic or other provider key.
   - **Nous Portal subscription:** install the [Railway CLI](https://docs.railway.com/cli) and run `railway ssh --service hermes`, then `hermes portal`. Open the link it prints, enter the code, and pick a model.
   - **Custom OpenAI-compatible endpoint:** set `OPENAI_BASE_URL` and `OPENAI_API_KEY` on the service.

   The default model is `anthropic/claude-opus-4.6`, which suits OpenRouter. For other providers, choose a model on the **Models** page or with `/model` in the Chat tab.
5. **Talk to your agent.**
   - Open the **Chat** tab and type a message. It is the full Hermes terminal UI in your browser.
   - If no provider is set yet, Chat shows a *Setup Required* panel offering `/setup`.
6. **Optional: message it from Telegram.**
   - Create a bot with [@BotFather](https://t.me/BotFather) and set `TELEGRAM_BOT_TOKEN` on the service. Railway redeploys automatically.
   - DM your bot. It replies with a pairing code. Approve the code on the dashboard's **Pairing** page, and from then on the bot answers you.
   - To skip pairing, put your numeric Telegram user ID in `TELEGRAM_ALLOWED_USERS`.
   - Discord and Slack work the same way with their own token variables. You can also configure any channel from the dashboard's **Channels** page.

## Common Use Cases

- A personal assistant that remembers you, reachable from your phone through Telegram, Discord or Slack and from any browser.
- Scheduled jobs that run on their own and report back to a chat channel, such as daily digests, monitoring and reminders.
- A coding and research agent that runs shell commands, browses, edits files and builds up reusable skills in its own workspace.
- An OpenAI-compatible agent endpoint for your other Railway services, at `http://hermes.railway.internal:8642/v1` with the `API_SERVER_KEY` bearer token.
- A team bot in a Slack or Discord server, with pairing or allowlists controlling who can use it.

## Dependencies for Hermes Agent Hosting

- A model provider: an API key (OpenRouter, OpenAI, Anthropic and others), a Nous Portal subscription, or an OpenAI-compatible endpoint.
- Optional: bot tokens for Telegram, Discord or Slack.

### Deployment Dependencies

- Hermes Agent source: https://github.com/NousResearch/hermes-agent
- Documentation: https://hermes-agent.nousresearch.com/docs/
- Docker image: https://hub.docker.com/r/nousresearch/hermes-agent
- Docker guide: https://hermes-agent.nousresearch.com/docs/user-guide/docker
- Web dashboard guide: https://hermes-agent.nousresearch.com/docs/user-guide/features/web-dashboard
- Providers: https://hermes-agent.nousresearch.com/docs/integrations/providers
- Nous Portal: https://portal.nousresearch.com
- OpenRouter keys: https://openrouter.ai/keys
- Railway CLI (for `railway ssh`): https://docs.railway.com/cli

### Implementation Details

One service, `hermes`:

- Image: `nousresearch/hermes-agent:latest`
- Start command: `/opt/hermes/docker/entrypoint-dispatch.sh gateway run`. This keeps the image's s6 supervisor as PID 1.
- Volume: mounted at `/opt/data` (`HERMES_HOME`)
- Public domain: port 9119 (dashboard)
- Healthcheck: `/api/health`
- Private network: port 8642 (API server)

| Variable | Default | Purpose |
|---|---|---|
| `HERMES_DASHBOARD_BASIC_AUTH_USERNAME` | `admin` | Dashboard username |
| `HERMES_DASHBOARD_BASIC_AUTH_PASSWORD` | generated, 32 chars | Dashboard password |
| `HERMES_DASHBOARD_BASIC_AUTH_SECRET` | generated, 64 chars | Signs session cookies. Keep it stable so logins survive redeploys |
| `HERMES_DASHBOARD_PUBLIC_URL` | `https://${{RAILWAY_PUBLIC_DOMAIN}}` | Trusted public URL. Update it if you add a custom domain |
| `HERMES_DASHBOARD` | `1` | Runs the dashboard next to the gateway |
| `PORT` | `9119` | Dashboard port (domain and healthcheck) |
| `API_SERVER_ENABLED` / `API_SERVER_HOST` | `true` / `::` | OpenAI-compatible API on the private network |
| `API_SERVER_KEY` | generated, 48 chars | Bearer token for the API server |
| `OPENROUTER_API_KEY` | empty | Optional OpenRouter key |
| `OPENAI_API_KEY` / `OPENAI_BASE_URL` | empty | Optional OpenAI or OpenAI-compatible endpoint |
| `TELEGRAM_BOT_TOKEN` / `TELEGRAM_ALLOWED_USERS` | empty | Optional Telegram bot and allowlist |
| `DISCORD_BOT_TOKEN` / `DISCORD_ALLOWED_USERS` | empty | Optional Discord bot and allowlist |
| `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` / `SLACK_ALLOWED_USERS` | empty | Optional Slack bot (Socket Mode) and allowlist |

**Where settings live:**
- Keys and tokens saved in the dashboard (API Keys or Channels) are written to `/opt/data/.env`. They take precedence over Railway variables with the same name, so change or delete them in the dashboard.
- Model and other settings are in `/opt/data/config.yaml`. Edit them on the Config and Models pages or with `hermes config set` over `railway ssh`.
- Gateway changes take effect after a gateway restart. Use the button on the Channels page, or `hermes gateway restart` over `railway ssh`.

**Upgrades:**
- The service tracks `:latest`. Railway does not pull new images on its own: click **Redeploy** on the service to pick up a new release. Data on the volume is kept.
- To pin a version, change the image to a release tag such as `nousresearch/hermes-agent:v0.23.1`.
- Do not run `hermes update` inside the container. The application tree is read-only, and upgrades come from the image.
- If a release notes a config change, run `railway ssh --service hermes` and then `hermes config migrate`.

**Security notes:**
- The agent can run shell commands inside its container as an unprivileged user. That is its intended design, and it is why the dashboard and API are locked.
- Upstream recommends Nous Portal OAuth rather than a password for dashboards exposed to the internet. To switch, log in to Nous Portal as in step 4, then run `hermes dashboard register` over `railway ssh`. That writes `HERMES_DASHBOARD_OAUTH_CLIENT_ID` for you. Then redeploy. A self-hosted OIDC provider is also supported, via `HERMES_DASHBOARD_OIDC_ISSUER` and `HERMES_DASHBOARD_OIDC_CLIENT_ID`. See the web dashboard guide.
- Dashboard sessions last 12 hours by default (`HERMES_DASHBOARD_BASIC_AUTH_TTL_SECONDS`). To rotate the password, change `HERMES_DASHBOARD_BASIC_AUTH_PASSWORD`. To sign everyone out, change `HERMES_DASHBOARD_BASIC_AUTH_SECRET`.
- The API server has no public domain. Do not add one unless you need it, and keep `API_SERVER_KEY` secret if you do.

Resources: idle memory was about 0.5 GB in testing, with peaks near 0.8 GB while the Chat terminal was starting.

## Why Deploy Hermes Agent 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 Agent 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.
- [Weaviate](https://railway.com/deploy/weaviate-1) — Vector database with hybrid search and an API key-protected API
- [Möbius Personal AI OS](https://railway.com/deploy/mobius-v01-personal-ai-os) — Self-hosted AI agent that builds and runs apps for you, with memory.

Open this page in a browser: https://railway.com/deploy/hermes-agent-quick-start