environment

Original source / Raw SKILL.md

---
name: environment
description: This skill should be used when the user asks "what's the config", "show me the configuration", "what variables are set", "environment config", "service config", "railway config", or wants to add/set/delete variables, change build/deploy settings, scale replicas, connect repos, or delete services.
allowed-tools: Bash(railway:*)
---

# Environment Configuration

Query, stage, and apply configuration changes for Railway environments.

## Quick Actions

**When user asks "what's the config" or "show configuration":**

Run `railway status --json` to get the environment ID, then **always** query the full config:
```bash
bash <<'SCRIPT'
scripts/railway-api.sh \
  'query envConfig($envId: String!) {
    environment(id: $envId) { id config }
  }' \
  '{"envId": "ENV_ID_FROM_STATUS"}'
SCRIPT
```
Present: source (repo/image), build settings, deploy settings, variables per service.

**When user asks "what variables" or "show env vars":**
Use the same environment config query above - it includes variables per service and shared variables.

For **rendered** (resolved) variable values: `railway variables --json`

For mutations (add/change/delete), see sections below.

## Shell Escaping

**CRITICAL:** When running GraphQL queries via bash, you MUST wrap in heredoc to prevent shell escaping issues:

```bash
bash <<'SCRIPT'
scripts/railway-api.sh 'query ...' '{"var": "value"}'
SCRIPT
```

Without the heredoc wrapper, multi-line commands break and exclamation marks in GraphQL non-null types get escaped, causing query failures.

## When to Use

- User wants to create a new environment
- User wants to duplicate an environment (e.g., "copy production to staging")
- User wants to switch to a different environment
- User asks about current build/deploy settings, variables, replicas, health checks, domains
- User asks to change service source (Docker image, branch, commit, root directory)
- User wants to connect a service to a GitHub repo
- User wants to deploy from a GitHub repo (create empty service first via `new` skill, then use this)
- User asks to change build or start command
- User wants to add/update/delete environment variables
- User wants to change replica count or configure health checks
- User asks to delete a service, volume, or bucket
- User says "apply changes", "commit changes", "deploy changes"
- Auto-fixing build errors detected in logs

## Create Environment

Create a new environment in the linked project:

```bash
railway environment new <name>
```

Duplicate an existing environment:

```bash
railway environment new staging --duplicate production
```

With service-specific variables:

```bash
railway environment new staging --duplicate production --service-variable api PORT=3001
```

## Switch Environment

Link a different environment to the current directory:

```bash
railway environment <name>
```

Or by ID:

```bash
railway environment <environment-id>
```

## Get Context

**JSON output** - project/environment IDs:
```bash
railway status --json
```

Extract:
- `project.id` - for service lookup
- `environment.id` - for mutations

**Plain output** - linked service name:
```bash
railway status
```

Shows `Service: <name>` line with the currently linked service. Use the `projectServices` query below to resolve the name to an ID.

### Resolve Service ID

If user specifies a service by name, query project services:

```graphql
query projectServices($projectId: String!) {
  project(id: $projectId) {
    services {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}
```

Match the service name (case-insensitive) to get the service ID.

## Query Configuration

Fetch current environment configuration and staged changes.

```graphql
query environmentConfig($environmentId: String!) {
  environment(id: $environmentId) {
    id
    config(decryptVariables: false)
    serviceInstances {
      edges {
        node {
          id
          serviceId
        }
      }
    }
  }
  environmentStagedChanges(environmentId: $environmentId) {
    id
    patch(decryptVariables: false)
  }
}
```

Example:

```bash
bash <<'SCRIPT'
scripts/railway-api.sh \
  'query envConfig($envId: String!) {
    environment(id: $envId) { id config(decryptVariables: false) }
    environmentStagedChanges(environmentId: $envId) { id patch(decryptVariables: false) }
  }' \
  '{"envId": "ENV_ID"}'
SCRIPT
```

### Response Structure

The `config` field contains current configuration:

```json
{
  "services": {
    "<serviceId>": {
      "source": { "repo": "...", "branch": "main" },
      "build": { "buildCommand": "npm run build", "builder": "NIXPACKS" },
      "deploy": {
        "startCommand": "npm start",
        "multiRegionConfig": { "us-west2": { "numReplicas": 1 } }
      },
      "variables": { "NODE_ENV": { "value": "production" } },
      "networking": { "serviceDomains": {}, "customDomains": {} }
    }
  },
  "sharedVariables": { "DATABASE_URL": { "value": "..." } }
}
```

The `patch` field in `environmentStagedChanges` contains pending changes. The effective configuration is the base `config` merged with the staged `patch`.

For complete field reference, see [reference/environment-config.md](references/environment-config.md).

For variable syntax and service wiring patterns, see [reference/variables.md](references/variables.md).

## Get Rendered Variables

The GraphQL queries above return **unrendered** variables - template syntax like `${{shared.DOMAIN}}` is preserved. This is correct for management/editing.

To see **rendered** (resolved) values as they appear at runtime:

```bash
# Current linked service
railway variables --json

# Specific service
railway variables --service <service-name> --json
```

**When to use:**
- Debugging connection issues (see actual URLs/ports)
- Verifying variable resolution is correct
- Viewing Railway-injected values (RAILWAY_*)

## Stage Changes

Stage configuration changes via the `environmentStageChanges` mutation. Use `merge: true` to automatically merge with existing staged changes.

```graphql
mutation stageEnvironmentChanges(
  $environmentId: String!
  $input: EnvironmentConfig!
  $merge: Boolean
) {
  environmentStageChanges(
    environmentId: $environmentId
    input: $input
    merge: $merge
  ) {
    id
  }
}
```

**Important:** Always use variables (not inline input) because service IDs are UUIDs which can't be used as unquoted GraphQL object keys.

Example:

```bash
bash <<'SCRIPT'
scripts/railway-api.sh \
  'mutation stageChanges($environmentId: String!, $input: EnvironmentConfig!, $merge: Boolean) {
    environmentStageChanges(environmentId: $environmentId, input: $input, merge: $merge) { id }
  }' \
  '{"environmentId": "ENV_ID", "input": {"services": {"SERVICE_ID": {"build": {"buildCommand": "npm run build"}}}}, "merge": true}'
SCRIPT
```

### Delete Service

Use `isDeleted: true`:

```bash
bash <<'SCRIPT'
scripts/railway-api.sh \
  'mutation stageChanges($environmentId: String!, $input: EnvironmentConfig!, $merge: Boolean) {
    environmentStageChanges(environmentId: $environmentId, input: $input, merge: $merge) { id }
  }' \
  '{"environmentId": "ENV_ID", "input": {"services": {"SERVICE_ID": {"isDeleted": true}}}, "merge": true}'
SCRIPT
```

## Stage and Apply Immediately

For single changes that should deploy right away, use `environmentPatchCommit` to stage and apply in one call.

```graphql
mutation environmentPatchCommit(
  $environmentId: String!
  $patch: EnvironmentConfig
  $commitMessage: String
) {
  environmentPatchCommit(
    environmentId: $environmentId
    patch: $patch
    commitMessage: $commitMessage
  )
}
```

Example:

```bash
bash <<'SCRIPT'
scripts/railway-api.sh \
  'mutation patchCommit($environmentId: String!, $patch: EnvironmentConfig, $commitMessage: String) {
    environmentPatchCommit(environmentId: $environmentId, patch: $patch, commitMessage: $commitMessage)
  }' \
  '{"environmentId": "ENV_ID", "patch": {"services": {"SERVICE_ID": {"variables": {"API_KEY": {"value": "secret"}}}}}, "commitMessage": "add API_KEY"}'
SCRIPT
```

**When to use:** Single change, no need to batch, user wants immediate deployment.

**When NOT to use:** Multiple related changes to batch, or user says "stage only" / "don't deploy yet".

## Apply Staged Changes

Commit staged changes and trigger deployments.

**Note:** There is no `railway apply` CLI command. Use the mutation below or direct users to the web UI.

### Apply Mutation

**Mutation name: `environmentPatchCommitStaged`**

```graphql
mutation environmentPatchCommitStaged(
  $environmentId: String!
  $message: String
  $skipDeploys: Boolean
) {
  environmentPatchCommitStaged(
    environmentId: $environmentId
    commitMessage: $message
    skipDeploys: $skipDeploys
  )
}
```

Example:

```bash
bash <<'SCRIPT'
scripts/railway-api.sh \
  'mutation commitStaged($environmentId: String!, $message: String) {
    environmentPatchCommitStaged(environmentId: $environmentId, commitMessage: $message)
  }' \
  '{"environmentId": "ENV_ID", "message": "add API_KEY variable"}'
SCRIPT
```

### Parameters

| Field           | Type    | Default | Description                                 |
| --------------- | ------- | ------- | ------------------------------------------- |
| `environmentId` | String! | -       | Environment ID from status                  |
| `message`       | String  | null    | Short description of changes                |
| `skipDeploys`   | Boolean | false   | Skip deploys (only if user explicitly asks) |

### Commit Message

Keep very short - one sentence max. Examples:

- "set build command to fix npm error"
- "add API_KEY variable"
- "increase replicas to 3"

Leave empty if no meaningful description.

### Default Behavior

**Always deploy** unless user explicitly asks to skip. Only set `skipDeploys: true` if user says "apply without deploying", "commit but don't deploy", or "skip deploys".

Returns a workflow ID (string) on success.

## Auto-Apply Behavior

By default, **apply changes immediately**.

### Flow

**Single change:** Use `environmentPatchCommit` to stage and apply in one call.

**Multiple changes or batching:** Use `environmentStageChanges` with `merge: true` for each change, then `environmentPatchCommitStaged` to apply.

### When NOT to Auto-Apply

- User explicitly says "stage only", "don't deploy yet", or similar
- User is making multiple related changes that should deploy together

**When you don't auto-apply, tell the user:**

> Changes staged. Apply them at: https://railway.com/project/{projectId}
> Or ask me to apply them.

Get `projectId` from `railway status --json` → `project.id`

## Error Handling

### Service Not Found

```
Service "foo" not found in project. Available services: api, web, worker
```

### No Staged Changes

```
No patch to apply
```

There are no staged changes to commit. Stage changes first.

### Invalid Configuration

Common issues:

- `buildCommand` and `startCommand` cannot be identical
- `buildCommand` only valid with NIXPACKS builder
- `dockerfilePath` only valid with DOCKERFILE builder

### No Permission

```
You don't have permission to modify this environment. Check your Railway role.
```

### No Linked Project

```
No project linked. Run `railway link` to link a project.
```

## Composability

- **Create service**: Use `service` skill
- **View logs**: Use `deployment` skill
- **Add domains**: Use `domain` skill
- **Deploy local code**: Use `deploy` skill


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/environment-config.md

```markdown
# Environment Config Reference

The `EnvironmentConfig` object is used to configure services, volumes, and shared variables in Railway.

## Structure

```json
{
  "services": {
    "<serviceId>": {
      "source": { ... },
      "build": { ... },
      "deploy": { ... },
      "variables": { ... },
      "networking": { ... }
    }
  },
  "sharedVariables": { ... },
  "volumes": { ... },
  "buckets": { ... }
}
```

Only include fields being changed. The patch is merged with existing config.

## Service Config

### Source
| Field | Type | Description |
|-------|------|-------------|
| `image` | string | Docker image (e.g., `nginx:latest`) |
| `repo` | string | Git repository URL |
| `branch` | string | Git branch to deploy |
| `commitSha` | string | Specific commit SHA |
| `rootDirectory` | string | Root directory (monorepos) |
| `checkSuites` | boolean | Wait for GitHub check suites |
| `autoUpdates.type` | disabled \| patch \| minor | Auto-update policy for Docker images |

### Build
| Field | Type | Description |
|-------|------|-------------|
| `builder` | NIXPACKS \| DOCKERFILE \| RAILPACK | Build system |
| `buildCommand` | string | Command for Nixpacks builds |
| `dockerfilePath` | string | Path to Dockerfile |
| `watchPatterns` | string[] | Patterns to trigger deploys |
| `nixpacksConfigPath` | string | Path to nixpacks config |

### Deploy
| Field | Type | Description |
|-------|------|-------------|
| `startCommand` | string | Container start command |
| `multiRegionConfig` | object | Region → replica config. See [Multi-Region Config](#multi-region-config). |
| `healthcheckPath` | string | Health check endpoint |
| `healthcheckTimeout` | number | Seconds to wait for health |
| `restartPolicyType` | ON_FAILURE \| ALWAYS \| NEVER | Restart behavior |
| `restartPolicyMaxRetries` | number | Max restart attempts |
| `cronSchedule` | string | Cron schedule for cron jobs |
| `sleepApplication` | boolean | Sleep when inactive |

### Variables
| Field | Type | Description |
|-------|------|-------------|
| `value` | string | Variable value |
| `isOptional` | boolean | Allow empty value |

Set to `null` to delete a variable.

For variable references, see [variables.md](variables.md).

### Lifecycle
| Field | Type | Description |
|-------|------|-------------|
| `isDeleted` | boolean | Mark for deletion (requires ADMIN) |
| `isCreated` | boolean | Mark as newly created |

## Multi-Region Config

Controls replica count per region. Structure: region name → `{ numReplicas }` or `null` to remove.

```json
{
  "multiRegionConfig": {
    "us-west2": { "numReplicas": 3 },
    "europe-west4-drams3a": { "numReplicas": 2 }
  }
}
```

### Available Regions

| Name | Location | Aliases |
|------|----------|---------|
| `us-west2` | US West (California) | "us west", "california" |
| `us-east4-eqdc4a` | US East (Virginia) | "us east", "virginia" |
| `europe-west4-drams3a` | EU West (Amsterdam) | "europe", "eu", "amsterdam" |
| `asia-southeast1-eqsg3a` | Southeast Asia (Singapore) | "asia", "singapore" |

### Interpreting User Requests

- "add 3 replicas to europe" → `{ "europe-west4-drams3a": { "numReplicas": 3 } }`
- "add a replica to all regions" → set `numReplicas: 1` for all 4 regions
- "remove from asia" → `{ "asia-southeast1-eqsg3a": null }`
- "increase replicas to 5" (no region specified) → query current config first, update existing region(s)

**Important:** When user doesn't specify a region, query the current `multiRegionConfig` and modify the existing region(s). Don't assume a default region.

## Common Operations

### Set Build Command
```json
{ "services": { "<serviceId>": { "build": { "buildCommand": "npm run build" } } } }
```

### Set Start Command
```json
{ "services": { "<serviceId>": { "deploy": { "startCommand": "node server.js" } } } }
```

### Set Replicas
```json
{ "services": { "<serviceId>": { "deploy": { "multiRegionConfig": { "us-west2": { "numReplicas": 3 } } } } } }
```

### Add Variables
```json
{ "services": { "<serviceId>": { "variables": { "API_KEY": { "value": "xxx" } } } } }
```

### Delete Variable
```json
{ "services": { "<serviceId>": { "variables": { "OLD_VAR": null } } } }
```

### Add Shared Variable
```json
{ "sharedVariables": { "DATABASE_URL": { "value": "postgres://..." } } }
```

### Change Docker Image
```json
{ "services": { "<serviceId>": { "source": { "image": "nginx:latest" } } } }
```

### Connect GitHub Repo
```json
{ "services": { "<serviceId>": { "source": { "repo": "owner/repo", "branch": "main" } } } }
```

### Change Git Branch
```json
{ "services": { "<serviceId>": { "source": { "branch": "develop" } } } }
```

### Set Health Check
```json
{ "services": { "<serviceId>": { "deploy": { "healthcheckPath": "/health", "healthcheckTimeout": 30 } } } }
```

### Change Builder
```json
{ "services": { "<serviceId>": { "build": { "builder": "DOCKERFILE", "dockerfilePath": "./Dockerfile" } } } }
```

### Delete Service
```json
{ "services": { "<serviceId>": { "isDeleted": true } } }
```

### Delete Volume
```json
{ "volumes": { "<volumeId>": { "isDeleted": true } } }
```

### New Service Instance
```json
{ "services": { "<serviceId>": { "isCreated": true, "source": { "image": "nginx" } } } }
```

**Note:** `isCreated: true` is required for new service instances.

```

### references/variables.md

```markdown
# Variables Reference

Variables in Railway support references to other services, shared variables, and Railway-provided values.

## Template Syntax

```
${{NAMESPACE.VAR}}
```

| Namespace | Description |
|-----------|-------------|
| `shared` | Shared variables (project-wide) |
| `<serviceName>` | Variables from another service (case-sensitive) |

## Examples

**Reference shared variable:**
```json
{ "value": "${{shared.DOMAIN}}" }
```

**Reference another service's variable:**
```json
{ "value": "${{api.API_KEY}}" }
```

**Combine with text:**
```json
{ "value": "https://${{shared.DOMAIN}}/api" }
```

## Railway-Provided Variables

Railway injects these into every service automatically.

### Networking
| Variable | Description | Example | Availability |
|----------|-------------|---------|--------------|
| `RAILWAY_PUBLIC_DOMAIN` | Public domain | `myapp.up.railway.app` | Only if service has a domain |
| `RAILWAY_PRIVATE_DOMAIN` | Private DNS (internal only) | `myapp.railway.internal` | Always |
| `RAILWAY_TCP_PROXY_DOMAIN` | TCP proxy domain | `roundhouse.proxy.rlwy.net` | Only if TCP proxy enabled |
| `RAILWAY_TCP_PROXY_PORT` | TCP proxy port | `11105` | Only if TCP proxy enabled |

**Note:** `RAILWAY_PUBLIC_DOMAIN` is only available if the service has a domain configured.
Check the service's environment config to verify a domain exists before referencing it.

### Context
| Variable | Description |
|----------|-------------|
| `RAILWAY_PROJECT_ID` | Project ID |
| `RAILWAY_PROJECT_NAME` | Project name |
| `RAILWAY_ENVIRONMENT_ID` | Environment ID |
| `RAILWAY_ENVIRONMENT_NAME` | Environment name |
| `RAILWAY_SERVICE_ID` | Service ID |
| `RAILWAY_SERVICE_NAME` | Service name |
| `RAILWAY_DEPLOYMENT_ID` | Deployment ID |
| `RAILWAY_REPLICA_ID` | Replica ID |
| `RAILWAY_REPLICA_REGION` | Region (e.g., `us-west2`) |

### Volume (if attached)
| Variable | Description |
|----------|-------------|
| `RAILWAY_VOLUME_NAME` | Volume name |
| `RAILWAY_VOLUME_MOUNT_PATH` | Mount path |

### Git (if deployed from GitHub)
| Variable | Description |
|----------|-------------|
| `RAILWAY_GIT_COMMIT_SHA` | Commit SHA |
| `RAILWAY_GIT_BRANCH` | Branch name |
| `RAILWAY_GIT_REPO_NAME` | Repository name |
| `RAILWAY_GIT_REPO_OWNER` | Repository owner |
| `RAILWAY_GIT_AUTHOR` | Commit author |
| `RAILWAY_GIT_COMMIT_MESSAGE` | Commit message |

## Wiring Services Together

### Frontend → Backend (public network)
Use when: Browser makes requests to API (browser can't access private network)

```json
{
  "services": {
    "<frontendId>": {
      "variables": {
        "API_URL": { "value": "https://${{backend.RAILWAY_PUBLIC_DOMAIN}}" }
      }
    }
  }
}
```

### Service → Database (private network)
Use when: Backend connects to database (faster, no egress cost, more secure)

Railway databases auto-generate connection URL variables. Use the private versions:

| Database | Variable Reference |
|----------|-------------------|
| Postgres | `${{Postgres.DATABASE_URL}}` |
| MySQL | `${{MySQL.DATABASE_URL}}` |
| Redis | `${{Redis.REDIS_URL}}` |
| Mongo | `${{Mongo.MONGO_URL}}` |

**Postgres/MySQL example:**
```json
{
  "services": {
    "<apiId>": {
      "variables": {
        "DATABASE_URL": { "value": "${{Postgres.DATABASE_URL}}" }
      }
    }
  }
}
```

**Redis example:**
```json
{
  "services": {
    "<apiId>": {
      "variables": {
        "REDIS_URL": { "value": "${{Redis.REDIS_URL}}" }
      }
    }
  }
}
```

**Mongo example:**
```json
{
  "services": {
    "<apiId>": {
      "variables": {
        "MONGO_URL": { "value": "${{Mongo.MONGO_URL}}" }
      }
    }
  }
}
```

**Note:** Service names are case-sensitive. Match the exact name from your project (e.g., "Postgres", "Redis").

### Service → Service (private network)
Use when: Microservices communicate internally

```json
{
  "services": {
    "<workerServiceId>": {
      "variables": {
        "API_INTERNAL_URL": { "value": "http://${{api.RAILWAY_PRIVATE_DOMAIN}}:${{api.PORT}}" }
      }
    }
  }
}
```

## When to Use Public vs Private

| Use Case | Domain | Reason |
|----------|--------|--------|
| Browser → API | Public | Browser can't access private network |
| Service → Service | Private | Faster, no egress, more secure |
| Service → Database | Private | Databases should never be public |
| External webhook → Service | Public | External services need public access |
| Cron job → API | Private | Internal communication |

```

### scripts/railway-api.sh

```bash
#!/usr/bin/env bash
# Railway GraphQL API helper
# Usage: railway-api.sh '<graphql-query>' ['<variables-json>']

set -e

if ! command -v jq &>/dev/null; then
  echo '{"error": "jq not installed. Install with: brew install jq"}'
  exit 1
fi

CONFIG_FILE="$HOME/.railway/config.json"

if [[ ! -f "$CONFIG_FILE" ]]; then
  echo '{"error": "Railway config not found. Run: railway login"}'
  exit 1
fi

TOKEN=$(jq -r '.user.token' "$CONFIG_FILE")

if [[ -z "$TOKEN" || "$TOKEN" == "null" ]]; then
  echo '{"error": "No Railway token found. Run: railway login"}'
  exit 1
fi

if [[ -z "$1" ]]; then
  echo '{"error": "No query provided"}'
  exit 1
fi

# Build payload with query and optional variables
if [[ -n "$2" ]]; then
  PAYLOAD=$(jq -n --arg q "$1" --argjson v "$2" '{query: $q, variables: $v}')
else
  PAYLOAD=$(jq -n --arg q "$1" '{query: $q}')
fi

curl -s https://backboard.railway.com/graphql/v2 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

```