Deploy and Host Mercury Agent Railway on Railway

What is Mercury Agent Railway?

Mercury Agent Railway is a one-click Railway layout for Mercury: 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 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 — product overview
Mercury documentation
mercury-agent (GitHub)
@cosmicstack/mercury-agent (npm)
Telegram BotFather — create TELEGRAM_BOT_TOKEN
Railway volumes guide — attach storage at /data
Railway CLI / shell — optional mercury telegram approve pairing

Implementation Details

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

# 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:

# 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:

# 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.