Skip to content

Deploying on Railway

This page shows how to run a node on Railway. Most of it applies to any container platform. Railway either runs the project's published image, ghcr.io/igorrius/ganglion, or builds the Dockerfile from the repository.

Before you start

  • Use a bot token that no other process polls. A second poller causes a 409 error (see Telegram updates).
  • Decide how the agent reaches a model: a CLAUDE_CODE_OAUTH_TOKEN from claude setup-token, or an API key such as OPENROUTER_API_KEY. See Models.
  • Railway containers share the host's kernel. Module builds need Linux 6.2 or later. You can check after the first start.

The image

The image is about 1.2 GB, mostly the Rust toolchain. It runs as the user ganglion (uid 10001) and starts ganglion run --db /data/ganglion.db. Data lives in /data. The claude CLI is included. Build without it with --build-arg CLAUDE_CLI=off.

Create the service

  1. Create a new service from the image ghcr.io/igorrius/ganglion:<version> (Railway pulls it, no build), or from the repository (Railway builds the Dockerfile by itself). With the CLI, from a clone of the repository: railway add -s <service>, then railway up -s <service>. Always name the service in CLI commands, so you do not act on another service by accident.
  2. Add a volume mounted at /data. The image has no VOLUME line on purpose, because Railway refuses one.
  3. Leave the user alone. Railway mounts volumes as root. Do not set RAILWAY_RUN_UID=0: the sandbox and module builds are off for root. The image starts as root only to hand /data to uid 10001 and then drops to that user. Check with ls -ld /data (owner ganglion).
  4. Set variables:
Variable Value
TELEGRAM_BOT_TOKEN your bot's token
CLAUDE_CODE_OAUTH_TOKEN the token from claude setup-token, if you use the claude CLI
OPENROUTER_API_KEY a provider key, if you use that service

A sealed variable resolves to an empty value when another variable refers to it, so set those by value. 5. Memory: give the service about 1 GB while module builds run. Set node.memory_limit in the file (for example 100MiB) to cap the node itself. Builds are separate processes outside that limit. 6. Restart policy: "on failure". The node exits with code 75 for /restart and the platform starts it again.

railway ssh needs an SSH key registered in your Railway account (railway ssh keys add).

Updating the service

Run the service from the image ghcr.io/igorrius/ganglion:<version> with the volume at /data. After that, send /update in your private chat to see the newest release and /update install vX.Y.Z to move to it. The node restarts itself, and the restart policy brings it back. See Updating. A service built from the repository's Dockerfile or from a local checkout reports a build without a release version: switch it to the image once. Pull a newer image only when /update says a release needs one, or to update the Rust toolchain and the claude CLI.

Create ganglion.yaml in the volume

The file is /data/ganglion.yaml. It must be a file inside the volume, not a single-file mount, because the node rewrites it. Create it as the node's user, so the node can rewrite it. A file made by root is root's.

railway ssh
setpriv --reuid=10001 --regid=10001 --clear-groups sh -c 'cat > /data/ganglion.yaml'

Paste the first copy, then press Ctrl-D:

node:
  memory_limit: 100MiB
  tz: Europe/London
telegram:
  token: env:TELEGRAM_BOT_TOKEN
  admin: telegram:user:123456

Add a models section for your provider. See Configuration.

Secrets

Set a module's secret over railway ssh, as the node's user, with the value on standard input:

printf %s "$VALUE" | setpriv --reuid=10001 --regid=10001 --clear-groups \
  ganglion secret set --db /data/ganglion.db --module <module> NAME

The module reads it at its next run with no restart. The key is /data/master.key, made at first start. Back it up with the database, or supply your own GANGLION_MASTER_KEY as a sealed variable before you store the first secret. See Configure.

Telegram by webhook (optional)

Polling needs nothing more. To use a webhook:

  1. Generate a domain for the service (Settings, Networking, or railway domain -s <service>). Prefer one that cannot be guessed from the service's name, and do not publish it: anyone can send requests to a public address.
  2. Add to /data/ganglion.yaml:
http:
  addr: ":8080"
  public_url: https://example.com
telegram:
  updates: webhook

Use the port Railway gives the service (PORT) and your real domain. 3. Restart. /status shows Telegram: webhook.

To go back, set telegram.updates: polling and restart. See Telegram updates.

Check after the first start

railway ssh
uname -r                                  # 6.2 or later
ls -ld /data                              # owner ganglion
setpriv --reuid=10001 --regid=10001 --clear-groups ganglion mcp --db /data/ganglion.db

The log must say sandbox: ready. If it says sandbox: commands are off, the reason names what is missing and nothing can be built. Then send /status in your private chat.

Run every command that touches /data as uid 10001. A command run as root leaves root-owned files (the database's -wal and -shm) that the node cannot open at its next start.

After /update, ganglion <command> run as uid 10001 runs the release the node runs, not the binary the image shipped. Run as root, it stays on the image's binary and prints a line saying which release the node runs.

Deploying from a git worktree

railway up uploads the main checkout, not a worktree. Name the folder: railway up <path> --path-as-root -s <service>.