---
title: "Deploy Mercury Agent Railway - 1 Click deploy"
description: "Mercury is a persistent AI agent that runs 24/7."
category: "AI/ML"
url: https://railway.com/deploy/mercury-agent-railway
---

# Deploy Mercury Agent Railway - 1 Click deploy

Mercury is a persistent AI agent that runs 24/7.

**[Deploy Mercury Agent Railway - 1 Click deploy on Railway](https://railway.com/template/mercury-agent-railway)**

- **Creator:** 4bade3's Projects
- **Category:** AI/ML
- **Total deploys:** 6

## Template content

### mercury-railway

- **Source:** 4bade3/mercury-railway

## Documentation

# Deploy and Host Mercury Agent Railway on Railway

## What is Mercury Agent Railway?

**Mercury Agent Railway** is a one-click Railway layout for [Mercury](https://mercury.cosmicstack.org): Cosmic Stack’s soul-driven, permission-aware AI agent with dozens of built-in tools, Telegram access, skills, scheduling, and flat-file memory. This template wraps the published [`@cosmicstack/mercury-agent`](https://www.npmjs.com/package/@cosmicstack/mercury-agent) package so Mercury runs headlessly as a Railway worker, with state on a Volume and secrets injected from Railway variables.

## About Hosting Mercury Agent Railway

Running Mercury here means shipping a **Docker** image on **Node 20**, installing Mercury from npm, and starting **`mercury start`** in the foreground (no HTTP service). The template **entrypoint** symlinks `~/.mercury` to **`/data/mercury`**, writes **`mercury.yaml`** from **`MERCURY_OWNER`** so the interactive first-run wizard never blocks the container, seeds **`~/.mercury/.env`** from Railway on every boot, and can enable **Telegram** plus optional **CLI-less pairing** via **`TELEGRAM_BOOTSTRAP_ADMIN_ID`**. You must **attach a Railway Volume** at **`/data`** so memory, soul markdown, skills, cron schedules, and Telegram access survive redeploys. Supply **`DEFAULT_PROVIDER`**, the matching provider API key(s), and **`TELEGRAM_BOT_TOKEN`** for typical headless use. **Do not set a custom start command** that bypasses the image `ENTRYPOINT`, or volume wiring and bootstrapping will not run.

## Common Use Cases

- **Personal AI copilot on Telegram** — chat with Mercury from your phone with tools, uploads, and admin-approved multi-user access.
- **Always-on assistant with memory and cron** — persisted schedules and JSONL memory on a Volume for continuity across restarts.
- **GitHub-aware agent (optional)** — enable repository work with `GITHUB_TOKEN` and related variables when you want Mercury’s GitHub tools.

## Dependencies for Mercury Agent Railway Hosting

- **Railway Volume** mounted at **`/data`** so `/data/mercury` holds `mercury.yaml`, `.env`, `memory/`, `soul/`, `skills/`, `schedules.yaml`, and Telegram state.
- **LLM access** — set **`DEFAULT_PROVIDER`** (`anthropic`, `openai`, `deepseek`, or `grok`) and at least one matching API key (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.).

### Deployment Dependencies

- [Mercury — Cosmic Stack](https://mercury.cosmicstack.org) — product overview
- [Mercury documentation](https://mercury.cosmicstack.org/docs.html)
- [mercury-agent (GitHub)](https://github.com/cosmicstack-labs/mercury-agent)
- [@cosmicstack/mercury-agent (npm)](https://www.npmjs.com/package/@cosmicstack/mercury-agent)
- [Telegram BotFather](https://t.me/BotFather) — create **`TELEGRAM_BOT_TOKEN`**
- [Railway volumes guide](https://docs.railway.com/guides/volumes) — attach storage at **`/data`**
- [Railway CLI / shell](https://docs.railway.com/guides/cli) — optional `mercury telegram approve` pairing

### Implementation Details

The image installs Mercury globally and relies on **`ENTRYPOINT`** + default **`CMD`** so Railway never skips bootstrap:

```dockerfile
# Dockerfile (excerpt)
FROM node:20-alpine
# ...
RUN npm install -g @cosmicstack/mercury-agent@${MERCURY_VERSION}
# ...
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["mercury", "start"]
```

The entrypoint wires the data directory and seeds env on each start:

```sh
# docker-entrypoint.sh (excerpt)
MERCURY_DIR="${MERCURY_DATA_DIR:-/data/mercury}"
HOME_MERCURY="$HOME/.mercury"
mkdir -p "$MERCURY_DIR"
if [ ! -L "$HOME_MERCURY" ]; then
  # ... merge if needed ...
  ln -s "$MERCURY_DIR" "$HOME_MERCURY"
fi
```

`railway.toml` intentionally omits `startCommand` so the Dockerfile entrypoint always runs:

```toml
# railway.toml (excerpt)
[deploy]
# Do not set startCommand here. The Dockerfile ENTRYPOINT must run first ...
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 10
```

## Why Deploy Mercury Agent Railway 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 Mercury Agent Railway 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/mercury-agent-railway