From 3ea887be5adf11a248cd7b5ff53c69c768cac325 Mon Sep 17 00:00:00 2001
From: Vignesh Natarajan <vigneshnatarajan92@gmail.com>
Date: Sat, 24 Jan 2026 15:58:58 -0800
Subject: [PATCH] Docs: add Railway deployment guide

---
 docs/docs.json   | 13 ++++++++
 docs/railway.mdx | 78 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+)
 create mode 100644 docs/railway.mdx

diff --git a/docs/docs.json b/docs/docs.json
index f5e858909..3d1fe0138 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -780,6 +780,18 @@
     {
       "source": "/plugins",
       "destination": "/plugin"
+    },
+    {
+      "source": "/railway/",
+      "destination": "/railway"
+    },
+    {
+      "source": "/install/railway",
+      "destination": "/railway"
+    },
+    {
+      "source": "/install/railway/",
+      "destination": "/railway"
     }
   ],
   "navigation": {
@@ -818,6 +830,7 @@
           "install/ansible",
           "install/nix",
           "install/docker",
+          "railway",
           "install/bun"
         ]
       },
diff --git a/docs/railway.mdx b/docs/railway.mdx
new file mode 100644
index 000000000..e0702fa0f
--- /dev/null
+++ b/docs/railway.mdx
@@ -0,0 +1,78 @@
+---
+title: Deploy on Railway
+---
+
+Deploy Clawdbot on Railway with a one-click template and finish setup in your browser.
+
+## One-click deploy
+
+<a href="https://railway.com/deploy/clawdbot-railway-template" target="_blank" rel="noreferrer">Deploy on Railway</a>
+
+After deploy, open:
+
+- `https://<your-domain>/setup` — setup wizard (password protected)
+- `https://<your-domain>/clawdbot` — Control UI
+
+## What you get
+
+- Hosted Clawdbot Gateway + Control UI
+- Web setup wizard at `/setup` (no terminal commands)
+- Persistent storage via Railway Volume (`/data`) so config/credentials/workspace survive redeploys
+- Backup export at `/setup/export` to migrate off Railway later
+
+## Required Railway settings
+
+### Public Networking
+
+Enable **HTTP Proxy** for the service.
+
+- Port: `8080`
+
+### Volume (required)
+
+Attach a volume mounted at:
+
+- `/data`
+
+### Variables
+
+Set these variables on the service:
+
+- `SETUP_PASSWORD` (required)
+- `CLAWDBOT_STATE_DIR=/data/.clawdbot` (recommended)
+- `CLAWDBOT_WORKSPACE_DIR=/data/workspace` (recommended)
+- `CLAWDBOT_GATEWAY_TOKEN` (recommended; treat as an admin secret)
+
+## Setup flow
+
+1) Visit `https://<your-domain>/setup` and enter your `SETUP_PASSWORD`.
+2) Choose a model/auth provider and paste your key.
+3) (Optional) Add Telegram/Discord/Slack tokens.
+4) Click **Run setup**.
+
+If Telegram DMs are set to pairing, the setup wizard can approve the pairing code.
+
+## Getting chat tokens
+
+### Telegram bot token
+
+1) Message `@BotFather` in Telegram
+2) Run `/newbot`
+3) Copy the token (looks like `123456789:AA...`)
+4) Paste it into `/setup`
+
+### Discord bot token
+
+1) Go to https://discord.com/developers/applications
+2) **New Application** → choose a name
+3) **Bot** → **Add Bot**
+4) Copy the **Bot Token** and paste into `/setup`
+5) Invite the bot to your server (OAuth2 URL Generator; scopes: `bot`, `applications.commands`)
+
+## Backups & migration
+
+Download a backup at:
+
+- `https://<your-domain>/setup/export`
+
+This exports your Clawdbot state + workspace so you can migrate to another host without losing config or memory.