railway-to-createos

What this skill does

# Railway → CreateOS Migration

This skill migrates a project currently deployed on Railway to CreateOS. It reads the existing Railway configuration, translates it into a CreateOS project, provisions environments and environment variables, and triggers the first deployment — all through the CreateOS MCP server.

---

## When to use this skill

Activate this skill when any of the following is true:

- The user explicitly asks to migrate, move, or deploy from Railway to CreateOS.
- The user expresses intent to leave Railway (pricing, reliability, credit shutdowns, egress costs, EU outages).
- The repository contains a `railway.json`, `railway.toml`, or a `Dockerfile` with Railway-specific environment references (`RAILWAY_*`).
- The user asks for a "Railway alternative" and wants to deploy on CreateOS.

Do NOT use this skill when:

- The user is deploying a fresh project with no prior Railway deployment — use the standard `createos` skill instead.
- The project uses Railway's multi-service canvas with more than 3 services. Surface complexity notes and offer the concierge migration path before proceeding.

---

## Prerequisites

Before running any migration steps, confirm the user has:

1. A CreateOS account — if not, direct them to `https://createos.nodeops.network` to sign in via Email, GitHub, Google, or Wallet.
2. CreateOS MCP connected OR a `CREATEOS_API_KEY` environment variable set.
3. Access to their Railway project's environment variables (export via Railway dashboard or CLI).
4. GitHub repository access for the project (CreateOS deploys from GitHub for VCS projects).

If the user does not have their Railway environment variables accessible, pause the migration and provide these instructions:

> Export your Railway environment variables by running `railway variables` in your project directory (requires Railway CLI), or download them per-service from the Railway dashboard under Variables. Keep this file local and do not commit it.

---

## Railway concepts → CreateOS mapping

Before migrating, understand how Railway's model maps to CreateOS:

| Railway concept | CreateOS equivalent |
|---|---|
| Project | Project |
| Service | Project (one CreateOS project per Railway service is the recommended approach) |
| Environment (Production / Staging) | Project Environment |
| Variables (per service, per environment) | Environment Variables on Project Environment |
| Custom domain (per service) | Domain on Project |
| Volume (persistent storage) | CreateOS does not provide managed volumes — use external storage (S3-compatible or managed DB) |
| Cron service | CreateOS Cronjob (`CreateCronjob` MCP tool) |
| Private networking between services | Not directly supported — services communicate via public URLs or you migrate to a monorepo |

**Important:** Railway's project canvas can run multiple services (web + worker + database) in one project. CreateOS maps each service to its own project. Plan the service split with the user before proceeding.

---

## Migration workflow

Follow these steps in order. Do not skip steps. Report progress to the user after each completed step.

### Step 1: Inventory the Railway project

Read the following files from the repository if they exist:

- `railway.json` or `railway.toml` — build, start, healthcheck, and restart configuration
- `package.json` — detect framework, build scripts, and Node.js version (if Node project)
- `Dockerfile` — if present, Railway may be using Docker-based builds (Railpack or custom)
- `.nvmrc` / `.python-version` / `go.mod` / `Gemfile` — runtime version pins
- Any `.env*` files for reference (do NOT read secrets; only note which keys exist)
- `Procfile` — if present, note web and worker process definitions

Produce a short summary for the user:

```
Detected project:
- Language/Framework: [Node.js 20 / Python 3.11 / Go 1.22 / etc.]
- Build system: [Nixpacks (auto) / Dockerfile / Railpack]
- Build command: [npm run build / pip install -r requirements.txt / etc.]
- Start command: [npm start / gunicorn app:app / ./main / etc.]
- Services detected: [web, worker, postgres, redis — list all]
- Environment variables needed: [count, with names — NOT values]
- Railway-specific features in use: [volumes, cron, private networking, etc.]
```

### Step 2: Plan the service split

Railway projects often contain multiple services (e.g., a web service, a background worker, and a managed Postgres). Confirm with the user which services to migrate and how:

| Railway service type | Migration plan |
|---|---|
| Web service | Migrate to CreateOS VCS project |
| Background worker / queue consumer | Migrate to separate CreateOS VCS project |
| Railway managed Postgres | Migrate to CreateOS managed PostgreSQL or external provider |
| Railway managed Redis | Migrate to CreateOS Valkey (Redis-compatible) |
| Railway managed MySQL | Migrate to CreateOS managed MySQL or external provider |
| Railway managed MongoDB | Use external MongoDB Atlas or self-hosted |
| Cron service | Use CreateOS Cronjob (`CreateCronjob` MCP tool) |
| Volume (persistent disk) | Flag — CreateOS does not provide managed volumes. Use S3-compatible storage or a managed database instead. |

For each managed database service on Railway, advise the user to export data before proceeding:

> **Postgres:** `pg_dump -h $PGHOST -U $PGUSER -d $PGDATABASE > backup.sql`
> **MySQL:** `mysqldump -h $MYSQLHOST -u $MYSQLUSER -p$MYSQLPASSWORD $MYSQLDATABASE > backup.sql`
> **Redis:** `redis-cli -h $REDISHOST SAVE` then copy the dump file.

Do not proceed with migration until the user confirms data is backed up.

### Step 3: Flag incompatibilities before proceeding

Check for Railway-specific features and patterns. If any are present, STOP and confirm with the user how they want to handle each before continuing.

| Railway feature | CreateOS handling |
|---|---|
| `RAILWAY_*` environment variables | These are Railway-injected runtime vars. Replace with CreateOS equivalents or remove. See variable mapping table below. |
| Private networking (`*.railway.internal`) | Services communicate via private hostnames on Railway. On CreateOS, services use public URLs — update any internal service URLs in config. |
| Railway volumes (persistent disk) | CreateOS does not offer managed volumes. Migrate data to S3-compatible storage or a managed database. |
| Multi-service canvas (3+ services) | Each service becomes a separate CreateOS project. Confirm wiring between them via public URLs. |
| Railway managed databases | Migrate data to CreateOS managed databases or external providers. |
| Cron services | Use CreateOS `CreateCronjob` MCP tool. |
| Healthcheck paths | Map to CreateOS health check configuration on the project environment. |
| Custom build args in Dockerfile | Supported — pass as environment variables on the CreateOS project. |
| Nixpacks auto-detection | CreateOS uses `useBuildAI: true` as the equivalent — it auto-detects language, runtime, and build commands. |

**Railway → CreateOS environment variable mapping:**

| Railway variable | CreateOS replacement |
|---|---|
| `RAILWAY_PUBLIC_DOMAIN` | Use the CreateOS deployment URL from `GetDeployment` |
| `RAILWAY_PRIVATE_DOMAIN` | Not applicable — use public URL of the target CreateOS service |
| `RAILWAY_PROJECT_ID` | Not needed — remove |
| `RAILWAY_SERVICE_ID` | Not needed — remove |
| `RAILWAY_ENVIRONMENT` | Replace with `NODE_ENV` or equivalent |
| `PORT` | Set explicitly on the CreateOS project (`port` field); Railway injects this automatically, CreateOS requires it declared |

### Step 4: Create the CreateOS project

Use the CreateOS MCP to create a new VCS-type project for each Railway web/worker service.

1. Call `ListConnectedGithubAccounts` to verify GitHub is connected. The response includes the `installationId` needed for the next call. If no accounts are connected, call `InstallGithubApp` and pause for user action.
2. Call `ListGithubRepositories(installationId)` and confirm the target repo. Capture the rep