Deploy and Host Hermes Agent on Railway

Hermes Agent is a self-improving AI agent from Nous Research that can persist knowledge, build skills from experience, and run as a long-lived gateway for chat platforms, APIs, and agent workflows. This template deploys Hermes Agent on Railway using the official Docker image with gateway mode, optional web dashboard, and persistent storage for configuration, API keys, sessions, memories, skills, logs, and runtime state.

About Hosting Hermes Agent

Deploying Hermes Agent on Railway uses the official nousresearch/hermes-agent Docker image. The container should run Hermes in gateway mode using gateway run. When HERMES_DASHBOARD=1 is enabled, the image entrypoint starts the Hermes dashboard as a background side-process before launching the gateway as the long-running foreground process. Railway handles deployments, networking, and public access, while Hermes stores persistent state in /opt/data. A Railway Volume should be mounted at /opt/data so configuration, API keys, sessions, memories, skills, cron jobs, hooks, logs, and customizations survive restarts and redeployments.

Note The Hermes Agent Docker image is large and may take some time to pull during the first deployment.

Architecture Note Hermes Agent stores its persistent runtime state in /opt/data. The dashboard should run inside the same container as the gateway by enabling HERMES_DASHBOARD=1.

Common Use Cases

• Running a long-lived autonomous AI agent on Railway
• Persisting agent memory, sessions, skills, and configuration across redeployments
• Exposing Hermes Gateway for OpenAI-compatible API access and health checks
• Accessing Hermes through the built-in browser-based dashboard
• Connecting Hermes Agent to chat platforms such as Telegram, Discord, Slack, or WhatsApp
• Running a cloud-hosted agent that can continue working independently from your local machine

Dependencies for Hermes Agent Hosting

• Official Hermes Agent Docker image: nousresearch/hermes-agent:latest
• Gateway mode using gateway run
• Built-in dashboard enabled with HERMES_DASHBOARD=1
• Railway Volume mounted at /opt/data for persistent storage
• Gateway API on port 8642
• Dashboard web UI on port 9119
• User-provided model provider API keys or chat platform tokens

Deployment Dependencies

• Hermes Agent Docker image: https://hub.docker.com/r/nousresearch/hermes-agent
• Hermes Agent Docker documentation: https://hermes-agent.nousresearch.com/docs/user-guide/docker
• Hermes Agent documentation: https://hermes-agent.nousresearch.com/docs
• Railway Public Networking: https://docs.railway.com/networking/public-networking
• Railway Volumes: https://docs.railway.com/reference/volumes
• Railway CLI: https://docs.railway.com/guides/cli
• Railway SSH guide: https://docs.railway.com/guides/ssh

Service Setup

This template should use one Railway service from the official Docker image:

nousresearch/hermes-agent:latest

The container must run gateway mode as the main foreground process:

gateway run

When HERMES_DASHBOARD=1 is set, the image entrypoint starts the dashboard in the background and then runs the gateway in the foreground. This keeps the container alive on Railway while still exposing the browser dashboard.

Environment Variables

Recommended environment variables:

API_SERVER_CORS_ORIGINS="*"
API_SERVER_ENABLED="true"
API_SERVER_HOST="0.0.0.0"
API_SERVER_KEY="${{secret(32, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_!~*")}}"
HERMES_DASHBOARD="1"
HERMES_DASHBOARD_HOST="0.0.0.0"
HERMES_DASHBOARD_PORT="9119"

The official Hermes Agent Docker image does not use ADMIN_USERNAME or ADMIN_PASSWORD for dashboard login. It also does not provide a signup flow. The Gateway API should be protected with API_SERVER_KEY. For a public Railway template, generate API_SERVER_KEY with Railway's secret(...) helper instead of hardcoding one shared key, so every deployment receives a unique API key.

Users should configure their own model provider keys or platform tokens depending on how they want to use Hermes Agent, for example OpenAI, Anthropic, Telegram, Discord, Slack, or other supported integrations.

Public Web Access

For browser access, expose the Hermes dashboard port publicly:

9119

The Hermes Gateway API runs on:

8642

If Railway only exposes one public port for this service, expose 9119 for the dashboard. The gateway still runs inside the same container and remains available internally to the dashboard.

Volume Setup

Mount a Railway Volume at:

/opt/data

This is the main persistent data directory for Hermes Agent. It stores configuration, API keys, sessions, memories, installed skills, cron jobs, hooks, logs, and custom UI/CLI skins.

Do not run multiple Hermes Gateway containers against the same data directory at the same time, because Hermes state files are not designed for concurrent writes from multiple gateway containers.

SSH Usage

SSH is optional and mainly useful for diagnostics. Most users should interact with Hermes Agent through the Dashboard, Gateway API, or chat platform integrations.

Prerequisites

Ensure you have the necessary setup in place:

• The Railway CLI installed on your local machine
• Logged in with your Railway account using:

railway login

Usage

You can copy the exact SSH command directly from the Railway dashboard:

1. Navigate to your project in the Railway dashboard.
2. Right-click on the Hermes Agent service you want to inspect.
3. Select Copy SSH Command from the dropdown menu.
4. Paste the command into your local terminal to connect to the running container.

Once connected, you can inspect files in /opt/data, review logs, verify environment variables, or debug the running Hermes service.

Implementation Details

This template uses the official Hermes Agent Docker image:

FROM nousresearch/hermes-agent:latest

The service should run Hermes Gateway as the main process:

gateway run

The dashboard should not be deployed as a separate Railway service. The official Docker image starts the dashboard as a side-process when HERMES_DASHBOARD=1 is set, then runs the gateway as the long-running foreground process. This avoids the common issue where the default container command opens the interactive Hermes TUI and exits on Railway because there is no interactive terminal.

For persistent storage, mount the Railway Volume at /opt/data. The Docker image itself is stateless, so pulling a new image version or redeploying the service should not remove agent state as long as the volume remains attached.

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.