Deploy Hermes Agent · Quick Start

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 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 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 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)

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.