Railway To Createos

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:

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:

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 → CreateOS environment variable mapping:

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 repo's id — that is the vcsRepoId.

3. Call CheckProjectUniqueName({uniqueName}) to validate the proposed project name. uniqueName must match ^[a-zA-Z0-9-]+$, 4–32 chars.

4. Call CreateProject with the nested source/settings shape. Two valid patterns — pick one:

   Pattern A — Build AI (recommended default). Use this when the Railway project uses Nixpacks auto-detection or when you cannot confidently derive exact commands from config files. CreateOS auto-detects from the repo:

   CreateProject({
     "uniqueName": "<derived from Railway service name>",
     "displayName": "<human-friendly name>",
     "type": "vcs",
     "source": {
       "vcsName": "github",
       "vcsInstallationId": "<from step 1>",
       "vcsRepoId": "<from step 2>"
     },
     "settings": {
       "useBuildAI": true,
       "runtime": "<see runtime mapping below — required>",
       "port": 3000
     }
   })
   

   Pattern B — Explicit commands. Use this when railway.json / railway.toml gives you concrete buildCommand and startCommand. All command fields, when included, must be non-empty strings — omit fields entirely rather than passing "" (empty strings cause a 400):

   CreateProject({
     "uniqueName": "<derived from Railway service name>",
     "displayName": "<human-friendly name>",
     "type": "vcs",
     "source": {
       "vcsName": "github",
       "vcsInstallationId": "<from step 1>",
       "vcsRepoId": "<from step 2>"
     },
     "settings": {
       "framework": "<see mapping table below — omit if no slug fits>",
       "runtime": "<see runtime mapping below>",
       "port": 3000,
       "directoryPath": ".",
       "installCommand": "<from railway.json installCommand or package.json>",
       "buildCommand": "<from railway.json buildCommand>",
       "runCommand": "<from railway.json startCommand>",
       "buildDir": "<output directory if applicable>"
     }
   })
   

   Required-in-practice fields:

   • port — always include. Railway injects PORT automatically; CreateOS requires it declared. Default to 3000 for Node, 8000 for Python, 8080 for Go. Use whatever the app actually listens on.
   • runtime — always include.
   • Either useBuildAI: true OR a complete command set (installCommand + buildCommand + runCommand). Mixing partial commands with useBuildAI: false causes a 400.

4b. Call CreateProjectEnvironment(project_id, body) to create the production environment. All five body fields are required:

CreateProjectEnvironment(project_id, {
  "displayName": "Production",
  "uniqueName": "production",
  "description": "Production environment migrated from Railway",
  "branch": "main",
  "isAutoPromoteEnabled": true,
  "settings": { "runEnvs": {} },
  "resources": { "cpu": 200, "memory": 500, "replicas": 1 }
})

Resource limits: cpu 200–500 millicores, memory 500–1024 MB, replicas 1–3.

Framework mapping (settings.framework):

Runtime mapping (settings.runtime):

If the user's config pins an unsupported version, surface this and ask whether to upgrade to the nearest supported runtime.

Step 5: Migrate environment variables

This is the highest-risk step. Handle with care.

1. Ask the user to paste their Railway variable list (names only, NOT values) or output of railway variables.
2. Show the list and confirm which variables to migrate. Filter out Railway-injected variables that do NOT need migration (see variable mapping table in Step 3).
3. For each remaining variable, ask the user to provide the value (do NOT log or persist these values in the skill output).
4. Call UpdateProjectEnvironmentEnvironmentVariables to set them on the production environment.
5. Remind the user to mark sensitive values (API keys, tokens, database URLs) as sensitive in the CreateOS dashboard for encryption at rest.
6. If the Railway project used service-to-service private networking (e.g., a worker connecting to Postgres via *.railway.internal), flag that these hostnames must be replaced with the new CreateOS managed database connection strings or external database URLs.

Step 6: Handle Railway-specific patterns in code

Scan for and flag these patterns. Do NOT auto-rewrite unless the user explicitly approves.

Produce a summary of required code changes and ask the user whether they want the skill to generate a migration branch or whether they will handle them manually.

Step 7: Trigger the first deployment

1. Call TriggerLatestDeployment to kick off the first build.
2. Poll GetDeployment status until the build completes or fails.
3. If the build fails:
   • Call GetBuildLogs to retrieve logs.
   • Summarize the failure for the user.
   • Common Railway-to-CreateOS failure causes:
     • Missing PORT declaration — ensure port is set both in code and in the CreateOS project settings.
     • RAILWAY_* variable still referenced in code — remove or replace.
     • Private networking hostname (*.railway.internal) still in config — replace with public URL.
     • Nixpacks build assumed a specific runtime not declared in CreateOS — switch to Pattern A (useBuildAI: true).
     • Volume mount path referenced in code — refactor to external storage.
4. If the build succeeds, report:
   • The CreateOS deployment URL as returned by the API (do NOT construct or guess the URL; use the exact url field from GetDeployment). The default subdomain pattern is https://[project].createos.nodeops.network, but always defer to the API's returned value.
   • Build duration
   • Deployment ID for reference

Step 8: Domain handoff (guided, not automated)

Do NOT cut over DNS automatically. Walk the user through domain migration manually.

1. Ask if they want to configure a custom domain now.
2. If yes, call CreateDomain with their domain.
3. Surface the DNS records they need to configure at their DNS provider (not at Railway).
4. Advise them to:
   • Test the CreateOS deployment thoroughly at the createos.nodeops.network subdomain first.
   • Lower their DNS TTL at the current provider to 300 seconds 24 hours before cutover.
   • Keep the Railway deployment live until the CreateOS deployment is verified.
   • Cut DNS over only when ready.
   • Keep the Railway deployment active for at least 72 hours post-cutover as a fallback.

Step 9: Post-migration checklist

Produce a final report for the user covering:

• All Railway services inventoried and migration plan confirmed
• Database data exported and backed up before migration
• First deployment succeeded on CreateOS
• All environment variables migrated (Railway-injected vars removed/replaced)
• Private networking hostnames replaced with public URLs
• PORT handling verified in code and CreateOS project settings
• Volume dependencies flagged and refactored (if applicable)
• Worker/cron services migrated to separate CreateOS projects or Cronjobs
• Custom domain configured (if requested)
• DNS cutover plan understood
• Concierge support contact shared for complex issues

Share these resources:

• Docs: https://nodeops.network/createos/docs/deploy
• Migration guide: https://nodeops.network/createos/docs/Migrations/Vercel (use as reference; Railway guide coming soon)
• Concierge migration (for projects needing white-glove support): mailto:business@nodeops.xyz

Failure modes and rollback

If the migration fails at any step and the user wants to abort:

1. The CreateOS project can be deleted with DeleteProject — no charges are incurred for a project that never successfully deployed.
2. The user's Railway deployment is untouched throughout this workflow. Nothing in this skill modifies Railway resources.
3. Offer the concierge migration path as a fallback for complex multi-service projects.

What this skill does NOT do

Be explicit with the user about these boundaries:

• Does not modify or delete anything on Railway.
• Does not automatically rewrite application code — only flags patterns that need changing.
• Does not perform DNS cutover — the user must do this intentionally.
• Does not migrate database data — data migration requires separate tooling (pg_dump, redis-cli, etc.).
• Does not migrate Railway team members or access controls.
• Does not support Railway volume migration — volumes must be refactored to external storage.
• Does not handle multi-service projects with private networking automatically — each service is migrated individually and rewired via public URLs.

Resources

• CreateOS MCP tools reference: https://nodeops.network/createos/docs/api-mcp/mcp-operations
• Skill repository: https://github.com/NodeOps-app/skills
• Concierge migration: mailto:business@nodeops.xyz