Service

Extract:

• project.id - for creating the service
• environment.id - for staging the instance config

Create Service Mutation

mutation serviceCreate($input: ServiceCreateInput!) {
  serviceCreate(input: $input) {
    id
    name
  }
}

ServiceCreateInput Fields

Example: Create empty service

bash <<'SCRIPT'
scripts/railway-api.sh \
  'mutation createService($input: ServiceCreateInput!) {
    serviceCreate(input: $input) { id name }
  }' \
  '{"input": {"projectId": "PROJECT_ID"}}'
SCRIPT

Example: Create service with image

bash <<'SCRIPT'
scripts/railway-api.sh \
  'mutation createService($input: ServiceCreateInput!) {
    serviceCreate(input: $input) { id name }
  }' \
  '{"input": {"projectId": "PROJECT_ID", "name": "my-service", "source": {"image": "nginx:latest"}}}'
SCRIPT

Connecting a GitHub Repo

Do NOT use serviceCreate with source.repo - use staged changes API instead.

Flow:

1. Create empty service: serviceCreate(input: {projectId: "...", name: "my-service"})
2. Use environment skill to configure source via staged changes API
3. Apply to trigger deployment

After Creating: Configure Instance

Use environment skill to configure the service instance:

{
  "services": {
    "<serviceId>": {
      "isCreated": true,
      "source": { "image": "nginx:latest" },
      "variables": {
        "PORT": { "value": "8080" }
      }
    }
  }
}

Critical: Always include isCreated: true for new service instances.

Then use environment skill to apply and deploy.

For variable references, see reference/variables.md.

Check Service Status

railway service status --json

Returns current deployment status for the linked service.

Deployment History

railway deployment list --json --limit 5

Present Status

Show:

• Service: name and current status
• Latest Deployment: status (SUCCESS, FAILED, DEPLOYING, CRASHED, etc.)
• Deployed At: when the current deployment went live
• Recent Deployments: last 3-5 with status and timestamps

Deployment Statuses

Update Service

Update service name or icon via GraphQL API.

Get Service ID

railway status --json

Extract service.id from the response.

Update Name

bash <<'SCRIPT'
scripts/railway-api.sh \
  'mutation updateService($id: String!, $input: ServiceUpdateInput!) {
    serviceUpdate(id: $id, input: $input) { id name }
  }' \
  '{"id": "SERVICE_ID", "input": {"name": "new-name"}}'
SCRIPT

Update Icon

Icons can be image URLs or animated GIFs.

Railway Devicons: Query https://devicons.railway.app/{query} for common developer icons (e.g., github, postgres, redis, nodejs). Browse all at https://devicons.railway.app

bash <<'SCRIPT'
scripts/railway-api.sh \
  'mutation updateService($id: String!, $input: ServiceUpdateInput!) {
    serviceUpdate(id: $id, input: $input) { id icon }
  }' \
  '{"id": "SERVICE_ID", "input": {"icon": "https://devicons.railway.app/github"}}'
SCRIPT

ServiceUpdateInput Fields

Link Service

For agent automation, prefer explicit railway run -p/-e/-s -- ... or a script wrapper with explicit context. Treat interactive linking as a human/manual flow, not the default agent path.

Switch the linked service for the current directory:

railway service link

Or specify directly:

railway service link <service-name>

Fully non-interactive linking is acceptable only when all required flags are provided:

railway link --project <project-id> --environment <env> --service <service> --json

Automation-safe alternatives:

railway run -p <project-id> -e <env> -s <service> -- env | grep RAILWAY_SERVICE

~/agent-skills/scripts/dx-load-railway-auth.sh -- \
  ~/agent-skills/scripts/dx-railway-run.sh -- \
  env | grep RAILWAY_SERVICE

Composability

• Create service with local code: Use new skill (handles scaffolding + creation)
• Configure service: Use environment skill (variables, commands, image, etc.)
• Delete service: Use environment skill with isDeleted: true
• Apply changes: Use environment skill
• View logs: Use deployment skill
• Deploy local code: Use deploy skill

Error Handling

No Service Linked

No service linked.

Human/manual flow:
  railway service link

Agent automation:
  railway run -p <project-id> -e <env> -s <service> -- <command>

No Deployments

Service exists but has no deployments yet. Deploy with `railway up`.

Service Not Found

Service "foo" not found. Check available services with `railway status`.

Project Not Found

User may not be in a linked project. Check railway status.

Permission Denied

User needs at least DEVELOPER role to create services.

Invalid Image

Docker image must be accessible (public or with registry credentials).