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:

• Create service: railway add --service <name>

• Set rootDirectory to subdirectory path via environment skill

• 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

• User explicitly says "new project" → Use railway init

• User names an existing project → Use railway link

• Directory name matches existing project → Ask: link existing or create new?

• No matching projects → Use railway init

• 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 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:

• railway add --service my-api

• Invoke environment skill to set source.repo and source.branch

• Apply changes to trigger deployment

Configure Based on Project Type

Reference railpack.md for build configuration.

Reference monorepo.md for monorepo patterns.

Static site (Vite, CRA, Astro static):

• Railpack auto-detects common output dirs (dist, build)

• If non-standard output dir: invoke environment skill to set RAILPACK_STATIC_FILE_ROOT

• Do NOT use railway variables CLI - always use the environment skill

Node.js SSR (Next.js, Nuxt, Express):

• Verify start script exists in package.json

• If custom start needed: invoke environment skill to set startCommand

Python (FastAPI, Django, Flask):

• Verify requirements.txt or pyproject.toml exists

• Auto-detected by Railpack, usually no config needed

Go:

• Verify go.mod exists

• Auto-detected, no config needed

Monorepo Configuration

Critical decision: Root directory vs custom commands.

Isolated monorepo (apps don't share code):

• Set Root Directory to the app's subdirectory (e.g., /frontend)

• Only that directory's code is available during build

Shared monorepo (TypeScript workspaces, shared packages):

• Do NOT set root directory

• Set custom build/start commands to filter the package:

• pnpm: pnpm --filter <package> build

• npm: npm run build --workspace=packages/<package>

• yarn: yarn workspace <package> build

• Turborepo: turbo run build --filter=<package>

• Set watch paths to prevent unnecessary rebuilds

See monorepo.md for detailed patterns.

Project Setup Guidance

Analyze the codebase to ensure Railway compatibility.

Analyze Codebase

Check for existing project files:

• package.json → Node.js project

• requirements.txt, pyproject.toml → Python project

• go.mod → Go project

• Cargo.toml → Rust project

• index.html → Static site

• None → Guide scaffolding

Monorepo detection:

• pnpm-workspace.yaml → pnpm workspace (shared monorepo)

• package.json with workspaces field → npm/yarn workspace (shared monorepo)

• turbo.json → Turborepo (shared monorepo)

• Multiple subdirs with separate package.json but no workspace config → isolated monorepo

Scaffolding Hints

If no code exists, suggest minimal patterns from railpack.md:

Static site:

Create an index.html file in the root directory.

Vite React:

npm create vite@latest . -- --template react

Astro:

npm create astro@latest

Python FastAPI:

Create main.py with FastAPI app and requirements.txt with dependencies.

Go:

Create main.go with HTTP server listening on PORT env var.

Databases

For adding databases (Postgres, Redis, MySQL, MongoDB), use the database skill.

The database skill handles:

• Creating database services

• Connection variable references

• Wiring services to databases

Composability

• After service created: Use deploy skill to push code

• For advanced config: Use environment skill (buildCommand, startCommand)

• For domains: Use domain skill

• For status checks: Use status skill

• For service operations (rename, delete, status): Use service skill

Error Handling

CLI Not Installed

Railway CLI not installed. Install with:

  npm install -g @railway/cli

or

  brew install railway

Not Authenticated

Not logged in to Railway. Run: railway login

No Workspaces

No workspaces found. Create one at railway.com or verify authentication.

Project Name Taken

Project name already exists. Either:

- Link to existing: railway link -p <name>

- Use different name: railway init -n <other-name>

Service Name Taken

Service name already exists in this project. Use a different name:

  railway add --service <other-name>

Examples

Create HTML Static Site

User: "create a simple html site and deploy to railway"

1. Check status → not linked

2. railway init -n my-site

3. Guide: create index.html

4. railway add --service my-site

5. No config needed (index.html in root auto-detected)

6. Use deploy skill: railway up

7. Use domain skill for public URL

Create Vite React Service

User: "create a vite react service"

1. Check status → linked (or init/link first)

2. Scaffold: npm create vite@latest frontend -- --template react

3. railway add --service frontend

4. No config needed (Vite dist output auto-detected)

5. Use deploy skill: railway up

Add Python API to Project

User: "add a python api to my project"

1. Check status → linked

2. Guide: create main.py with FastAPI, requirements.txt

3. railway add --service api

4. No config needed (FastAPI auto-detected)

5. Use deploy skill

Link and Add Service

User: "connect to my backend project and add a worker service"

1. railway list --json → find "backend"

2. railway link -p backend

3. railway add --service worker

4. Guide setup based on worker type

Deploy to Railway (Ambiguous)

User: "deploy to railway"

1. railway status → not linked

2. railway list → has projects

3. Directory is "my-app", found project "my-app"

4. Ask: "Found existing project 'my-app'. Link to it or create new?"

5. User: "link"

6. railway link -p my-app

7. Ask: "Create a service for this code?"

Add Service to Isolated Monorepo

User: "create a static site in the frontend directory"

1. Check: /frontend has its own package.json, no workspace config

2. This is isolated monorepo → use root directory

3. railway add --service frontend

4. Invoke environment skill to set rootDirectory: /frontend

5. Set watch paths: /frontend/**

Add Service to TypeScript Monorepo

User: "add a new api package to this turborepo"

1. Check: turbo.json exists, pnpm-workspace.yaml exists

2. This is shared monorepo → use custom commands, NOT root directory

3. Guide: create packages/api with package.json

4. railway add --service api

5. Invoke environment skill to set buildCommand and startCommand (do NOT set rootDirectory)

6. Set watch paths: /packages/api/**, /packages/shared/**

Deploy Existing pnpm Workspace Package

User: "deploy the backend package to railway"

1. Check: pnpm-workspace.yaml exists → shared monorepo

2. railway add --service backend

3. Invoke environment skill to set buildCommand and startCommand

4. Set watch paths for backend + any shared deps

Deploy Subdirectory of Linked Project

User: "create a vite app in my-app directory and deploy to railway"

CWD: ~/projects/my-project/my-app (parent already linked to "my-project")

1. Check status in my-app → not linked

2. Check parent: cd .. && railway status → IS linked to "my-project"

3. DON'T init/link the subdirectory

4. Scaffold: bun create vite my-app --template react-ts

5. cd my-app && bun install

6. railway add --service my-app

7. Invoke environment skill to set rootDirectory: /my-app

8. Deploy from root: railway up