Railway New

New Project / Service / Database

Create Railway projects, services, and databases with proper configuration.

When to Use

• User says "deploy to railway" (add service if linked, init if not)
• User says "create a railway project", "init", "new project" (explicit new project)
• User says "link to railway", "connect to railway"
• User says "create a service", "add a backend", "new api service"
• User says "create a vite app", "create a react website", "make a python api"
• User says "deploy from github.com/user/repo", "create service from this repo"
• User says "add postgres", "add a database", "add redis", "add mysql", "add mongo"
• User says "connect to postgres", "wire up the database", "connect my api to redis"
• User says "add postgres and connect to the server"
• Setting up code + Railway service together

Prerequisites

Check CLI installed:

command -v railway

If not installed:

Install Railway CLI:

npm install -g @railway/cli

or

brew install railway

Check authenticated:

railway whoami --json

If not authenticated:

Run railway login to authenticate.

Decision Flow

railway status --json (in current dir)
     │
┌────┴────┐
Linked    Not Linked
  │            │
  │       Check parent: cd .. && railway status --json
  │            │
  │       ┌────┴────┐
  │    Parent      Not linked
  │    Linked      anywhere
  │       │            │
  │   Add service   railway list
  │   Set rootDir      │
  │   Deploy       ┌───┴───┐
  │       │      Match?  No match
  │       │        │        │
  │       │      Link    Init new
  └───────┴────────┴────────┘
           │
    User wants service?
           │
     ┌─────┴─────┐
    Yes         No
     │           │
Scaffold code   Done
     │
railway add --service
     │
Configure if needed
     │
Ready to deploy

Check Current State

railway status --json

• If linked: Add a service to the existing project (see below)
• If not linked: Check if a PARENT directory is linked (see below)

When Already Linked

Default behavior: "deploy to railway" = add a service to the linked project.

Do NOT create a new project unless user EXPLICITLY says:

• "new project", "create a project", "init a project"
• "separate project", "different project"

App names like "flappy-bird" or "my-api" are SERVICE names, not project names.

User: "create a vite app called foo and deploy to railway"
Project: Already linked to "my-project"

WRONG: railway init -n foo
RIGHT: railway add --service foo

Parent Directory Linking

Railway CLI walks up the directory tree to find a linked project. If you're in a subdirectory:

cd .. && railway status --json

If parent is linked, you don't need to init/link the subdirectory. Instead:

1. Create service: railway add --service <name>
2. Set rootDirectory to subdirectory path via environment skill
3. Deploy from root: railway up

If no parent is linked, proceed with init or link flow.

Init vs Link Decision

Skip this section if already linked - just add a service instead.

Only use this section when NO project is linked (directly or via parent).

Check User's Projects

The output can be large. Run in a subagent and extract only:

• Project id and name
• Workspace id and name

railway list --json

Decision Logic

1. User explicitly says "new project" → Use railway init
2. User names an existing project → Use railway link
3. Directory name matches existing project → Ask: link existing or create new?
4. No matching projects → Use railway init
5. Ambiguous → Ask user

Create New Project

railway init -n <name>

Options:

• -n, --name - Project name (auto-generated if omitted in non-interactive mode)
• -w, --workspace - Workspace name or ID (required if multiple workspaces exist)

Multiple Workspaces

If the user has multiple workspaces, railway init requires the --workspace flag.

Get workspace IDs from:

railway whoami --json

The workspaces array contains { id, name } for each workspace.

Inferring workspace from user input: If user says "deploy into xxx workspace" or "create project in my-team", match the name against the workspaces array and use the corresponding ID:

# User says: "create a project in my personal workspace"
railway whoami --json | jq '.workspaces[] | select(.name | test("personal"; "i"))'
# Use the matched ID: railway init -n myapp --workspace <matched-id>

Link Existing Project

railway link -p <project>

Options:

• -p, --project - Project name or ID
• -e, --environment - Environment (default: production)
• -s, --service - Service to link
• -t, --team - Team/workspace

Create Service

After project is linked, create a service:

railway add --service <name>

For GitHub repo sources: Create an empty service, then invoke the railway-environment skill to configure the source via staged changes API. Do NOT use railway add --repo - it requires GitHub app integration which often fails.

Flow:

1. railway add --service my-api
2. Invoke railway-environment skill to set source.repo and source.branch
3. Apply changes to trigger deployment