Deploy and Host Hermes Agent on Railway

Hermes Agent is an autonomous AI agent by Nous Research that runs continuously on your server and communicates through messaging channels such as Telegram, Discord, Slack, Email, Mattermost, Matrix, and WhatsApp.

This Railway template includes a custom administration dashboard focused on a simple setup and operational workflow.

About Hosting Hermes Agent

The deployment runs two components in one Railway container:

• A Starlette-based Admin Dashboard exposed through Railway's public domain.
• The Hermes gateway, managed by the dashboard as a subprocess.

A persistent Railway Volume mounted at /data stores:

• Provider API keys and channel credentials.
• Hermes configuration.
• Sessions and memories.
• Skills and workspace data.
• Pairing requests and approved users.

The dashboard updates config.yaml non-destructively, preserving unrelated Hermes settings that may have been added outside the dashboard.

Common Use Cases

• Autonomous Support Bot — provide continuous assistance through Telegram, Discord, Slack, and other supported channels.
• Persistent AI Coding Partner — connect Hermes with GitHub and development tools while controlling it from a messaging application.
• Private AI Gateway — provide approved-user-only access to selected LLMs for a family, team, or organization.
• Multi-Provider Agent — register multiple LLM providers and switch the active provider without rebuilding the service.

Requirements

• A Railway account.
• At least one supported LLM provider API key.
• At least one messaging channel credential or bot token.
• A Railway Volume mounted at /data.

Recommended Services

• OpenRouter — unified access to many LLM models.
• Telegram BotFather — the quickest way to create a messaging bot.
• Hermes Agent — the upstream autonomous agent framework.

Deployment Guide

1. Get an LLM Provider API Key

OpenRouter is a convenient starting option:

1. Register at OpenRouter.
2. Create a key from OpenRouter Keys.
3. Optionally browse available models.

The dashboard also supports direct keys for:

• OpenAI
• Claude / Anthropic
• Google Gemini
• xAI / Grok
• NVIDIA NIM
• DeepSeek
• DashScope
• GLM / Z.AI
• Kimi
• MiniMax
• Hugging Face

Each provider option includes a link to its official API key page.

2. Set Up a Telegram Bot

1. Message @BotFather.
2. Send /newbot and follow the instructions.
3. Copy the generated Bot Token.
4. Find your Telegram user ID through @userinfobot.

Telegram is recommended for the initial deployment because it is fast to configure and easy to test.

3. Deploy to Railway

1. Deploy the Hermes Agent template.

2. Add a Railway Volume and mount it at:

   /data
   

3. Configure at least:

   ADMIN_USERNAME
   ADMIN_PASSWORD
   

4. Generate a public Railway domain for the service.

5. Open the domain and login through the Hermes Admin Login page.

Do not use the default example password for a public deployment.

4. Complete the Initial Setup

The initial setup is intentionally strict to prevent invalid configurations.

Provider

1. Select an LLM provider.
2. Follow the provided link to create an API key.
3. Paste the API key.
4. Click Load Models.
5. Click the model field to open the searchable model dropdown, or type a model ID manually.
6. Click Test Connection.

The wizard cannot continue until the provider connection succeeds.

Messaging Channel

1. Enable at least one channel.
2. Enter all required credentials.
3. Click Test Channels.

Every enabled channel must pass its connection test before the wizard can continue.

Review and Start

1. Review the selected provider, model, and channels.
2. Run System Diagnostics.
3. Click Save & Start.

Managing an Existing Installation

After initial setup, the Setup page displays a safe configuration summary instead of exposing the full form.

Use:

• Add Provider to register another provider without changing channels.
• Add Channel to add a channel without reconfiguring the active provider.
• Manage Providers to remove inactive or incomplete providers.
• Manage Channels to remove channels.

Only one provider can be active at a time. A provider can only be activated if both its API key and model are configured.

For safety:

• The active provider cannot be removed until another provider is activated.
• The final configured channel cannot be removed until another channel is added.
• Removing a channel restarts the gateway automatically when necessary.

Provider Switching

Open Status and use the provider switch.

Provider changes apply to new sessions. Existing sessions retain their current model unless the gateway is restarted. When appropriate, the dashboard offers the choice to restart immediately or later.

Status, Diagnostics, and Logs

The Status page shows:

• Gateway state and uptime.
• Active model.
• Pending pairing requests.
• Registered providers.
• Configured channels.

The Diagnostics panel checks:

• Hermes executable and version.
• Writable persistent storage.
• Provider, model, and channel configuration.
• Gateway state.
• Available disk space.

The Logs page displays gateway output for monitoring and troubleshooting.

User Pairing

The Users page is always accessible, but it remains empty until a configured messaging channel receives a request.

After Save & Start reports that the gateway is running, message the bot. When an unauthorized user sends a direct message, Hermes replies with a pairing code and creates a pending request in the dashboard.

1. Open Users.
2. Review the platform, username, and user ID.
3. Click Approve or Deny.

The dashboard supports the current hashed pairing format used by Hermes, so the owner does not need to open a Railway Console or run hermes pairing approve manually.

Approved access can be revoked later from the same page. If Allow all users is enabled, pairing approval is skipped.

Environment Variables

Provider keys, messaging credentials, models, and optional tool integrations are configured through the dashboard rather than Railway variables.

For stable sessions across password changes or multiple replicas, set ADMIN_SESSION_SECRET to a long random value.

Persistent Storage

The /data volume is required for production use. Without it, redeploying or restarting onto a new container may remove:

• API keys and bot tokens.
• Approved users and pairing data.
• Sessions, memories, and skills.
• Hermes configuration.

Back up the Railway Volume before performing a major migration.

Health Check

Railway uses:

/health

A healthy dashboard returns a response similar to:

{"status":"ok","gateway":"running"}

The gateway value may be stopped before initial configuration.

Why Deploy Hermes Agent on Railway?

Railway provides container builds, public HTTPS domains, environment variables, health checks, restart policies, logs, and persistent volumes in one platform.

This template packages those capabilities with a focused Hermes dashboard so the agent can be configured and operated without manually editing environment or YAML files.