railway

railway

タスクに必要な、利用可能な中で最小の Railway 操作を使用してください。デプロイ経路を選択する前に、リポジトリの AGENTS.md とデプロイポリシーを確認してください。GitHub 主導のパイプラインは、以下の汎用 CLI の例より優先されます。このスキルが提供するのはツールの操作方法であり、そのパイプラインを回避する権限ではありません。

デプロイ経路と承認

• リポジトリのコードを変更する場合は、ブランチ／PR を準備し、宣言された CI/CD トリガーを使用してください。GitHub 主導のサービスでは、対応するコミットのデプロイを確認してください。再デプロイを促すためだけに、チェックアウトをアップロードしたり、ソースブランチやピン留めを変更したり、プラットフォームにパッチを手動で適用したりしないでください。
• 手動での再起動、再デプロイ、ソース／設定の変更には、ロールアウト失敗の診断後の復旧など、ユーザーが許可した範囲内の運用上の理由が必要です。理由、対象の環境とサービスを正確に記録し、想定される効果も記録してください。
• その操作と範囲に対する既存の承認を再利用してください。意図が未確定の場合、破壊的な影響がある場合、または範囲を追加する場合に限り、判断を求めてください。読み取り専用の診断、元に戻せるコード修正、PR の準備には、追加の確認は必要ありません。
• テストの証拠は、実行時の能力や承認とは分けて報告します。テストの許可として、新たな適格性レポートやチェックリストを要求しないでください。

このスキルが起動する場合

以下の表現がある場合は、このスキルを使用します。

• デプロイ／ビルド
  • 「これを railway にデプロイして」
  • 「railway にプッシュして」、「railway にリリースして」、「railway up」
  • 「railway でビルドに失敗する」、「ビルドが失敗した理由を教えて」
• ログ／デバッグ
  • 「railway のログを見せて」、「ログを追跡して」、「railway logs --since 1h」
  • 「railway でサービスがクラッシュする理由を教えて」
  • 「railway の 500 エラーを見せて」、「HTTP ログを見せて」、「遅いリクエストを見せて」
  • 「railway のログからリクエスト ID abc123 を探して」
• 運用
  • 「railway で再デプロイして」、「api サービスを再起動して」、「直近のデプロイをロールバックして」
  • 「railway サービスをスケールして」、「最新のデプロイを削除して」
• 状態／情報の確認
  • 「railway のプロジェクト一覧を見せて」、「このプロジェクトにあるサービスは何？」、「デプロイ一覧を見せて」
  • 「railway プロジェクトの状態は？」、「サービスは正常？」
• 変数
  • 「railway の環境変数 FOO=bar を設定して」、「railway の変数一覧を見せて」、「railway の変数を削除して」
• 実行／接続
  • 「railway の本番環境変数を使ってこのスクリプトを実行して」、「railway の環境変数を使ってシェルを開いて」
  • 「railway サービスに SSH 接続して」、「railway の postgres／redis／mongo に接続して」
• メトリクス
  • 「railway の CPU／メモリ使用量は？」、「サービスが上限に達している？」
  • 「railway の p95 レイテンシは？」、「/api のリクエストレートは？」

以下の場合は使用しないでください。

• ホストが Railway ではない場合（Fly、Render、Vercel、AWS など）。このスキルが扱うのは railway CLI であり、他のサービスには対応しません。
• 運用上の操作が不要なコード変更で修正できる場合は、通常の開発プロセス向けスキルにコード変更を任せてください。デプロイやログの確認が必要になった時点で、このスキルに戻ってください。

前提条件

1. 利用可能なツールの一覧を確認してください。対応するプラットフォームの読み取りには、認証済みの Railway コネクターを使用してください。ローカルのチェックアウト、SSH、または正確なコマンドの実行には CLI を使用してください。同等の設定済みコネクターがある場合、CLI のグローバルインストールも、トークンの表示も必要ありません。
2. CLI を使用する場合は、command -v railway と railway --version を確認してから、範囲を限定したアカウント／プロジェクトの読み取りによって認証状態を診断してください。トークン、トークンの先頭部分、環境変数を決して表示しないでください。既存の CLI ログインまたは注入された認証情報を再利用してください。RAILWAY_API_TOKEN はアカウントのスコープ、RAILWAY_TOKEN はプロジェクト／環境のスコープです。ワークスペース一覧の取得が拒否されても、プロジェクトのスコープでの読み取りに失敗するとは限りません。
3. プロジェクト、環境、サービスの ID を明示的に特定してください。読み取り専用の情報取得で、リンク済みのコンテキストを変更してはいけません。インストール、ログイン、またはより広いアクセスを求める前に、コマンドで実際に発生した 401／403、未対応のフラグ、ツールの不足を診断してください。まず同等の設定済み機能を使用してください。ツールのインストール／更新は、依頼された操作に必要であり、かつ許可された範囲内にある場合に限って行ってください。

操作手順

このスキルは小さなステートマシンです。ユーザーの質問に答えるために必要な、最小限のエントリーポイントを選びます。依頼されていない調査は実行しないでください。

       ┌──────────┐
       │ Discover │  list projects / services / deployments / env / vars
       └────┬─────┘
            ▼
       ┌──────────┐        ┌──────────┐
       │  Debug   │◄──────►│ Metrics  │   logs (build/deploy/http) + cpu/mem/p95
       └────┬─────┘        └──────────┘
            ▼
       ┌──────────┐
       │   Fix    │  variables set / code edit / config change
       └────┬─────┘
            ▼
       ┌──────────┐        ┌──────────┐
       │  Deploy  │───────►│  Verify  │   up / redeploy / restart / down / roll back
       └──────────┘        └──────────┘

Step 1 — 検出

後続の呼び出しを明示的に行えるよう、必要な ID を必ず最初に取得します。解析しやすい JSON 出力を優先してください。

# Workspace-wide view (requires an account token).
railway list --json

# A single project's structure (project token works here too if you pass --project).
railway status --json --project "$PROJECT_ID"

# Services and environments inside that project.
railway service list --json --project "$PROJECT_ID" --environment production
railway environment list --json --project "$PROJECT_ID"

# Deployments for a specific service (most recent first).
railway deployment list \
  --project "$PROJECT_ID" \
  --service api \
  --environment production \
  --limit 20 --json

JSON から、プロジェクト ID、環境の ID／名前（通常は production、staging、および PR プレビュー環境）、サービスの ID／名前、最新のデプロイ ID とその status（SUCCESS、FAILED、BUILDING、DEPLOYING、CRASHED、REMOVED）を取得します。デプロイのステータスから、症状がビルドの問題、起動の問題、定常稼働時の問題のどれに当たるかがわかります。それに応じて適切なログストリームを選んでください。

Step 2 — デバッグ（まずログを確認）

Railway には 3 つのログストリームがあります。障害の状況に合ったものを選んでください。混在させると、ログの末尾が読みづらくなります。

ストリーム	フラグ	使用する状況
デプロイ／ランタイム	railway logs（デフォルト）	アプリは稼働しているものの、動作に問題がある場合、または起動後にクラッシュした場合。
ビルド	railway logs --build [DEPLOYMENT_ID]	デプロイが FAILED で、ランタイムに到達していない場合。
HTTP	railway logs --http	症状がステータスコード、レイテンシの急増、特定のリクエストに関する場合。

エージェントのセッションでは、デフォルトでストリーミングしない過去のログを照会してください。ストリーミングはシェルをハングさせます。--lines、--since、--until のいずれかを指定すると、ストリーミングは無効になります。

# Last 200 deploy log lines, JSON for parsing.
railway logs \
  --project "$PROJECT_ID" --service api --environment production \
  --lines 200 --json

# Build logs for the failed deployment specifically.
railway logs --build "$DEPLOYMENT_ID" \
  --project "$PROJECT_ID" --service api --environment production \
  --lines 500

# Errors only in the last hour.
railway logs --since 1h --filter "@level:error" --lines 100 \
  --project "$PROJECT_ID" --service api --environment production

# All 5xx HTTP responses in the last 30 minutes.
railway logs --http --since 30m --status ">=500" --lines 200 \
  --project "$PROJECT_ID" --service api --environment production --json

# Slow GETs on a specific path.
railway logs --http --method GET --path /api/users \
  --filter "@totalDuration:>=1000" --lines 50 --json \
  --project "$PROJECT_ID" --service api --environment production

# Trace one request end-to-end.
railway logs --http --request-id "$REQUEST_ID" --lines 50 --json \
  --project "$PROJECT_ID" --service api --environment production

フィルター構文（Railway クエリ言語。ダッシュボードでも使用できます）：

• テキスト：単語のみ → 部分文字列で一致。"two words" → フレーズで一致。
• レベル（デプロイ／ビルドのみ）：@level:error、@level:warn、@level:info。
• HTTP フィールド：@httpStatus、@method、@path、@host、@requestId、@clientUa、@srcIp、@edgeRegion、@upstreamAddress、@upstreamProto、@downstreamProto、@responseDetails、@deploymentId、@deploymentInstanceId、@totalDuration、@responseTime、@upstreamRqDuration、@txBytes、@rxBytes、@upstreamErrors。
• 演算子：> >= < <= ..（範囲。例：@httpStatus:200..299）、AND、OR、-（否定）、括弧。

ユーザーが「失敗した場合でも、最新のデプロイのログ」を求めている場合は、--latest を追加してください。それ以外では、railway logs は直近の成功したデプロイまで遡るため、回帰のデバッグでは通常、意図した結果になりません。

Step 3 — メトリクス（リソースの状態を確認）

症状がリソースの上限に関係している可能性がある場合（OOM による強制終了、CPU スロットリング、エグレスの急増、ボリュームの空き容量不足）は、ログとメトリクスを併せて確認します。

# Compact summary for the linked service, last hour.
railway metrics --json \
  --project "$PROJECT_ID" --service api --environment production

# Specific dimensions.
railway metrics --cpu --memory --since 6h --json \
  --project "$PROJECT_ID" --service api --environment production

# HTTP percentiles + RPS for a path.
railway metrics --http --path /api/users --json --since 1h \
  --project "$PROJECT_ID" --service api --environment production

# Table across every service in the project.
railway metrics --all --json \
  --project "$PROJECT_ID" --environment production

これらをデプロイログと併せて確認します。メモリ使用量がサービスの上限に近づいた後、突然途切れていれば OOM です。p95 が上昇するなかで CPU 使用率が 100% の状態が続いていれば、スロットリングです。数値が示す範囲を超えて論評しないでください。

Step 4 — 変数（まず読み取り専用で確認し、書き込みは許可された範囲内で行う）

設定ミスは通常、変数に潜んでいます。変数を一覧表示するとシークレットの値が出力されます。出力は機密情報として扱い、生の値をチャットにそのまま返してはいけません。また、--json を使い、シークレットを平文で貼り付ける代わりに（キー名と値の長さを）要約できるようにしてください。

# Read — JSON includes raw values; redact before surfacing.
railway variable list --json \
  --project "$PROJECT_ID" --service api --environment production

# Write only for the selected target within existing authorization.
railway variable set "FEATURE_FLAG=on" \
  --project "$PROJECT_ID" --service api --environment production
# Setting a variable triggers a redeploy by default; add --skip-deploys
# (top-level, before the subcommand) to set without redeploying.

# Delete.
railway variable delete FEATURE_FLAG \
  --project "$PROJECT_ID" --service api --environment production

まず変数名を確認し、診断に必要な場合に限り、値を非公開で調べてください。ユーザーが対象と変更内容をすでに指定している場合、再度選ばせないでください。新しいシークレットは、サポートされている非公開の方法で渡してください。シークレットをそのまま返したり、プロンプト、ログ、診断コマンドの出力に含めたりしてはいけません。フラグを独自に作らず、インストールされている CLI がサポートする標準入力／非公開入力インターフェースを確認してください。

ステップ 5 — 修正してデプロイする

意図が強くなる順に、3 つのデプロイ用動詞があります。

動詞	効果	使用する場面
railway restart	再ビルドせずに最新のデプロイを再起動します。	プロセスが応答しなくなっているものの、ビルド成果物に問題がない場合。
railway redeploy	最新のデプロイを再実行します（または --from-source を指定して最新のコミット／イメージを取得します）。	一時的な障害が発生した場合、または同じ成果物を再デプロイする場合。アップロードせずに新しいコミットを取り込むには、--from-source を使用します。
railway up	現在の作業ディレクトリをアップロードしてデプロイします。	競合するリポジトリパイプラインがなく、アップロードによるデプロイを明示的に選択する場合。

認証済みの手動操作での CLI の仕組みです（デフォルトの CI/CD 経路ではありません）。

# Restart (no rebuild). -y skips the confirmation dialog.
railway restart -y --json \
  --project "$PROJECT_ID" --service api --environment production

# Redeploy the latest deployment.
railway redeploy -y --json \
  --project "$PROJECT_ID" --service api --environment production

# Redeploy and pull the newest commit / image from the configured source.
railway redeploy -y --from-source --json \
  --project "$PROJECT_ID" --service api --environment production

# Upload and deploy this directory. --ci streams build logs only, then exits;
# perfect for agent sessions (no interactive log attach).
railway up --ci \
  --project "$PROJECT_ID" --service api --environment production \
  --message "fix: bump httpx to 0.27 to pick up TLS bug fix"

# Remove the most recent deployment (rollback to whatever was before it).
railway down -y \
  --project "$PROJECT_ID" --service api --environment production

railway up --ci はエージェント向けの形式です。CI=true が暗黙的に設定され、ビルドログが stdout にストリーミングされ、ビルドに失敗するとゼロ以外の終了コードで終了します。--ci を指定しない場合、CLI はライブログページャーをアタッチしようとするため、自動化のコンテキストでは処理がハングします。

デプロイ後は、新しいデプロイのログと短時間のメトリクスを必ず確認してください。終了コードだけを信用してはいけません。Railway のビルドが成功しても、ランタイムが起動時にクラッシュループすることがあります。

# Quick verification loop.
railway deployment list --json --limit 3 \
  --project "$PROJECT_ID" --service api --environment production
railway logs --lines 50 --since 2m \
  --project "$PROJECT_ID" --service api --environment production

ステップ 6 — run、shell、ssh、db connect

本番環境の環境変数をローカルで必要とする開発ワークフローや、稼働中のコンテナでシェルを使う場合：

# Run a one-shot command with the linked service's variables injected.
railway run --service api --environment production -- node scripts/migrate.js

# Open a subshell with the same env (interactive — only run when the user is at the terminal).
railway shell --service api --environment production --silent

# SSH into the running container of a service. -i picks an identity file if Railway
# can't find a usable key in ~/.ssh.
railway ssh \
  --project "$PROJECT_ID" --service api --environment production

# One-shot remote command (non-interactive).
railway ssh \
  --project "$PROJECT_ID" --service api --environment production \
  -- ls /app

# Open a database shell against a Railway-managed DB service.
railway connect postgres \
  --project "$PROJECT_ID" --environment production

railway run env と railway run printenv は、そのサービスのすべてのシークレット変数を出力します。出力は railway variable list --json と同様に扱い、絶対にそのまま貼り付けないでください。

よくある障害のパターン

Unauthorized. Please check that your RAILWAY_TOKEN is valid

実際のコマンドのスコープと、設定済みの認証情報で利用できる操作を確認してください。プロジェクトスコープの認証情報でプロジェクトの読み取りはできても、ワークスペース一覧の取得には失敗する場合があります。まず、必要なプロジェクト読み取り操作または同等の認証済みコネクターを試してください。既存の機能ではその操作を完了できない場合に限り、追加アクセスを要求してください。認証情報の内容は絶対に出力しないでください。

ビルドが FAILED、デプロイログが空

失敗はデフォルトのデプロイストリームではなく、--build ログに記録されています。

railway logs --build "$DEPLOYMENT_ID" --lines 500 \
  --project "$PROJECT_ID" --service api --environment production

デプロイ ID が不明な場合は、railway deployment list --json --limit 5 を実行すると、直近で失敗したデプロイを確認できます。

デプロイが CRASHED で、デプロイログが起動コマンドで終わる

アプリが起動中に停止しています。railway logs --lines 200 の末尾を読み、実際の例外を確認してください。よくあるパターンは次のとおりです。

• 環境変数の不足（KeyError: 'DATABASE_URL' や panic: required environment variable … など）→ railway variable list --json で確認してから、railway variable set … を実行します。
• ポートのバインド設定が誤っている — Railway は $PORT を設定します。サービスはハードコードされたポートではなく、0.0.0.0:$PORT にバインドする必要があります。
• DB 接続が拒否された — リンクされた DB サービスが同じ環境にあることと、プライベートネットワークの DNS（例：postgres.railway.internal）がアプリの想定どおりであることを確認してください。

ビルドは成功するが、ランタイムでエッジから 502 / Bad Gateway が返る

アプリが制限時間内に $PORT へバインドできていません（デフォルトのヘルスチェック時間枠）。アプリの起動が遅い（railway.json／railway.toml の healthcheckTimeout を延ばすか、起動の遅さを解消する）か、0.0.0.0 ではなく 127.0.0.1 にバインドしています。railway logs --http --status 502 --lines 50 でエッジが原因であることを確認してください。

突然の OOM（SIGKILL／out of memory）

デプロイログと railway metrics --memory --since 30m --json を照らし合わせてください。メモリ使用量がサービスの上限に達し、そのタイミングが強制終了と一致する場合は、サービスのメモリ上限を引き上げてください（ダッシュボードまたは railway.json の resources.memory）。ユーザーに伝えずに上限を引き上げてはいけません。上限に達したことを明確に伝えてください。

エージェントのセッションで railway up がハングする

--ci を付け忘れています。デフォルトモードでは終了しないライブページャーがアタッチされます。プロセスを終了し、--ci を付けて再実行してください。

変数の変更が「反映されなかった」場合

railway variable set はデフォルトで再デプロイをトリガーします。ただし、--skip-deploys が渡されていた場合、変数は適用待ちの状態になり、実行中のデプロイには古い値が残ります。適用待ちの変更と、リポジトリのロールアウト手順を確認してください。運用上の操作が許可されており、パイプラインと互換性がある場合に限り、変更を適用するか再デプロイしてください。単にコードをロールアウトするためだけに、この操作を実行しないでください。

規約

• JSON を優先します。 対応しているすべてのコマンドに --json を追加し、人間が読みやすい出力をスクレイピングするのではなく、jq で解析してください。出力形式は変わることがありますが、JSON のキーは安定しています。
• 呼び出しごとにスコープを明示します。 エージェントのセッションでは、すべてのコマンドに --project、--service、--environment を渡してください。.railway/ のリンク済み状態には依存しないでください。ユーザーには見えず、状態がずれると混乱を招きます。
• ログはデフォルトで非ストリーミングにします。 必ず --lines、--since、--until のいずれかと組み合わせてください。ストリーミングはターミナルを使う人向けであり、エージェント向けではありません。
• シークレットを貼り付けないでください。 railway variable list、railway run env、railway shell は、いずれも平文のシークレットを表示します。代わりに、キー名や値の長さを要約してください。ユーザーがシークレットを必要とする場合は、サポートされている非公開の受け渡し方法を使ってください。通常の診断出力には、名前と安全なステータスのみを含めてください。
• 操作のスコープを守ってください。 再起動、再デプロイ、設定変更には、既存の承認を再利用してください。削除や、そのスコープ外の操作を行う前には、具体的な意図と影響を確認してください。非対話型フラグを指定しても、権限が与えられるわけではありません。
• デプロイ後に検証してください。 railway up --ci の成功メッセージだけで終わらせないでください。最新のデプロイのステータスと、50 行のログサンプルを取得し、ビルド結果だけでなく実際の実行状態をユーザーに示してください。
• 調査では、障害モードを 1 つずつ扱ってください。 ビルド失敗、クラッシュループ、5xx、OOM はそれぞれ異なる状態であり、確認すべきログも異なります。複数のログ末尾を 1 つのレポートに混在させないでください。

Onsager 同梱スクリプト（任意、リポジトリ固有）

scripts/ ディレクトリには、onsager-ai/onsager モノレポ向けに調整された 3 つのシェルラッパーが含まれています。これらは同リポジトリのデプロイ構成（サービス名 onsager、環境変数 ONSAGER_RAILWAY_TOKEN、本番 URL https://onsager-production.up.railway.app、justfile のターゲット）に合わせて固定されています。Onsager 以外のリポジトリでは、これらを無視するか、フォークしてください。 上記の一般的な運用手順は、すべてのプロジェクトに適用できます。

Onsager リポジトリでは、次のコマンドを使います。

タスク	コマンド
デプロイ前チェック	sh scripts/preflight.sh
障害の診断	sh scripts/debug.sh [service]
ライブデプロイの検証	sh scripts/smoke.sh [url]

• preflight.sh — デプロイ前、またはビルド失敗のトリアージ時に実行します。ロックファイル（Cargo.lock、pnpm-lock.yaml）が git で追跡されていること、Dockerfile の COPY 元が解決できること、Railway の変数に localhost が含まれていないこと、DATABASE_URL が Railway Postgres プラグインを参照していることを確認します。いずれかのチェックに失敗すると、ゼロ以外の値で終了します。ONSAGER_RAILWAY_TOKEN が設定されていない場合は、Railway の変数チェックをスキップします。
• debug.sh [service] — 失敗または停止中のデプロイに対する一括診断を行います。サービスのステータス、ビルドログ（40 行）、デプロイ／実行時ログ（40 行）、エラーのみのログ（20 行）、HTTP 4xx／5xx（10 件）、変数名のみ（Python 3 が必要）を確認します。デフォルトのサービスは onsager です。設定済みの CLI 認証を再利用し、必要に応じて ONSAGER_RAILWAY_TOKEN を割り当てます。プロバイダーログには非公開のアプリケーションデータが含まれる場合があるため、非公開で確認する必要があります。
• smoke.sh [base_url] — デプロイ後の検証を行います。curl で API（/api/health、/api/auth/me、/api/nodes、/api/sessions）を確認し、agent-browser で任意の UI（/、/sessions、/nodes、/settings）を確認します。デフォルトの URL は https://onsager-production.up.railway.app です。agent-browser が PATH にない場合、UI チェックはエラーにならずスキップされます。

これらのスクリプトはラッパーのパターンを示すものです。このスキルを採用する別のリポジトリでは、ディレクトリをフォークし、独自のデプロイに合わせてスクリプトの内容を調整してください。

関連スキル

• リポジトリの仕様駆動型開発プロセスのスキル — 修正が単なる運用上の調整ではなく、コード変更である場合に使用します。仕様策定／ブランチ作成／PR のサイクルはそこで扱います。このスキルはデプロイの段階から対応します。
• plan-dag — オペレーターの質問が「これをデプロイして」ではなく、「デプロイをまだ妨げているものは何ですか？」である場合に使用します。
• Railway 独自の AI 機能 — railway agent -p "<question>" は CLI 内で対話型アシスタントを起動し、railway mcp install は Railway の MCP サーバーを Claude Code ／ Cursor ／ Codex に接続します。このスキルのスクリプト化されたフローだけでは不十分な場合の代替手段として便利ですが、上記の明示的な JSON 優先のサイクルに代わるものではありません。これらは探索的な質問向けであり、再現可能な自動化向けではありません。

人による判断

確定済みの判断と承認は再利用してください。定型的な実装とツール選定はエージェントの責務です。この手順で人による選択、確認または承認が必要な場合に限り、現在のハーネスでサポートされている構造化質問ツールを、ハーネス固有の指示とツール契約に従って使用してください。手順の詳細は harness-operations で確認してください。プロジェクト、サービス、環境、操作、トレードオフを正確に示し、依存する作業に進む前に明示的な回答を待ってください。依頼を文章だけで伝えて終わらせないでください。使用が許可された質問ツールがない場合は、その制約を明示し、承認を得たものとみなさず、定められた人への引き継ぎ経路を利用してください。