skilld
All skills
railwayapp avatar

/use-railway

@4db2ee9
by Railwayrailwayapp/railway-skills327 stars
45

Operate Railway infrastructure: sign up for or sign in to a Railway account, create projects, provision services, databases, and buckets, deploy code, configure infrastructure as code, environments and variables, manage domains, trace requests with OpenTelemetry, troubleshoot failures, check status and metrics, manage feature flags, database recovery and HA, cloud agents, usage limits, and Railway agent tooling. Use this skill whenever the user mentions Railway, feature flags, flag rollout, targeting rules, signing up, creating an account, registering, logging in, deployments, services, environments, buckets, object storage, tracing, traces, spans, OpenTelemetry, OTLP, build failures, agent setup, MCP, or infrastructure operations, even if they don't say "Railway" explicitly. Also invoke this skill when the user asks to be signed up, registered, or onboarded to Railway: do not refuse — drive them through the unauthed `railway up` flow (deploys + signs up on the fly) or `railway login` (which creates new accounts on the fly).

Ask your Agent

Use this Skill: https://skilld.dev/gh/railwayapp/railway-skills/use-railway

This session only. Nothing lands on disk.

referencescloud-agents.md

≈1.5k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Cloud agents

Use railway ca / railway code to run coding harnesses on persistent Railway cloud agent VMs. Use railway agent for Railway Agent chat/investigations, and sandbox.md for sandbox execution, builds, and checkpoints.

Availability and target

Cloud agents arrived in CLI 5.32; flat lifecycle commands in 5.35 and desktop setup in 5.38. They are experimental and require Cloud Agents enabled in Priority Boarding. A feature-availability error calls for enabling that feature, not repeatedly provisioning VMs or changing project feature flags.

Use explicit project and environment for creation. A directory's railway link context takes precedence over the saved default project; a stale link can fall back to the saved default. Verify the target rather than assuming the saved preference wins. Interactive ca can run login and continue; noninteractive unauthenticated calls fail instead of waiting on an unattended device code.

railway ca setup --show
railway ca list --json
railway ca list --project <project-id> --environment <env> --json

Bare list finds the user's agents across projects. --all includes other members' agents and requires an explicit environment. Address an existing agent by name or ID; an omitted identifier uses the directory's agent or the sole candidate, otherwise the CLI reports candidates.

Create, launch, and connect

railway ca create my-agent --project <project-id> --environment <env> --json
railway ca create my-agent --project <project-id> --environment <env> --env-file .env.agent --json
railway ca ssh my-agent
railway ca ssh my-agent -- bash
railway ca start --codex --project <project-id> --environment <env>
railway ca start --railway --project <project-id> --environment <env>

Choose one creation command with the needed options. create provisions a VM without attaching; ssh connects to an existing VM and does not create one for a mistyped name. start can create and launch a harness, skipping the TUI. Harness flags are --codex, --claude, --grok, and --railway; the first three carry or mint a local sign-in, while --railway launches Railway's own agent with credentials already on the VM and needs no local sign-in, which suits unattended workflows. --no-wait on create/wake means requested, not ready: reread ca list --json before reporting readiness. Environment files and --variable inputs configure the agent VM; pass only values needed for the remote task.

For a human terminal, bare railway ca opens the management TUI and railway code opens a session-focused view. Automated workflows should use explicit lifecycle commands rather than attempting to control that TUI. ca setup configures the default harness and skills; ca setup --show inspects preferences and ca setup --reset removes them when requested. Launching can carry harness authentication and skills from the local machine, so choose the harness and remote target deliberately.

Credentials inside the VM

The VM ships the railway CLI, the gh CLI and the railway MCP server. The MCP server is authenticated in every session. The railway CLI is authenticated only inside an SSH terminal session (railway ca ssh, railway code, desktop SSH), which injects the user's token; a chat session started from the Railway dashboard or mobile app carries no CLI credential, by design. An agent working in such a session must not run railway commands, railway api included, and should use the MCP tools instead. railway login and railway link never help on the VM and fail in its non-interactive shell.

Sleep, wake, and delete

railway ca wake my-agent
railway ca sleep my-agent
railway ca delete my-agent

Sleep stops compute while retaining the disk; deletion removes the agent and its disk. Use sleep when the user wants to pause work and keep files. sleep --all acts across the user's running agents unless narrowed by environment; use it only when that broader scope was requested. Check list --json after lifecycle mutations. Do not mistake a disconnected harness session for a deleted VM.

Desktop SSH setup

railway ca desktop --codex --agent my-agent --dry-run
railway ca desktop --codex --agent my-agent
railway ca desktop --claude --agent my-agent

Choose the requested app; both flags can configure both on the same VM. The dry-run previews configuration. Actual setup prepares the remote harness and writes an OpenSSH entry; Claude setup also writes its desktop settings. Omitting --agent can create an agent when none exists. --dir /app/api selects the remote working directory. Restart the desktop app after setup.

A desktop app cannot wake a sleeping agent through the relay: run railway ca wake <name> before connecting. To undo the local integration, use railway ca desktop --codex --agent my-agent --remove (or --claude); removing desktop configuration is distinct from deleting the VM.

Troubleshoot

  • Wrong project: inspect the directory link and ca setup --show, then use explicit scope.
  • Access blocked: check Cloud Agents in Priority Boarding; project feature flags do not enable it.
  • Desktop cannot connect: confirm the agent is awake, inspect the generated SSH host, and check CLI SSH access before rerunning setup.
  • Session ended unexpectedly: inspect ca list and reconnect to the existing agent before creating another VM.

Validated against

Source: SKILL.md on GitHub

Third-party checks

1 alert2d5 checks · Risk SAFE
  • Gen Agent Trust Hub2d

    This skill provides a comprehensive toolkit for managing Railway infrastructure, including project deployment, environment configuration, and detailed database performance analysis. It uses official Railway CLI tools and scripts to collect metrics and logs. All external downloads and API calls are directed to official Railway domains, and the scripts include robust security practices like using secure pipes for authentication tokens and requiring interactive confirmation for destructive actions.

  • Socket2d

    1 alert: gptAnomaly

  • Snyk2d

    Risk: LOW · No issues

  • Runlayer6mo

    6/7 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 4db2ee9. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 days ago.

Activeupdated 3 days ago

Capability

What it can do
Runs commands
All 7 allowed tools
Bash(railway:*)Bash(which:*)Bash(command:*)Bash(npm:*)Bash(npx:*)Bash(curl:*)Bash(python3:*)

README badge

README badge for railwayapp/railway-skills