runpod

Runpod（ルーター）

Runpod スキルのエントリーポイントです。このスキル自体は何も実行せず、適切なレーンを選んで引き継ぎます。複数ステップのタスクやプロビジョニングタスクでは、まず実例（推奨パス）を確認し、該当する例にレーンを選んでもらってください。それ以外の場合は、次に該当するスキルの SKILL.md を読んでください。

レーン

レーン	用途
runpod-mcp	構造化されたツール呼び出しを使ってインフラ（ポッド、エンドポイント、ジョブ、テンプレート、ボリューム、レジストリ、カタログ、請求）を管理します。このセッションで Runpod MCP ツールが接続されている場合に使用します。タスクに応じたジャーニースキル（検出、ライフサイクル CRUD、サーバーレスデプロイ、ポッドデプロイ、ポッドの診断、エンドポイント運用、コスト監査）に引き継ぎます。
runpodctl	ターミナル／CI／スクリプトから同じインフラを管理します。Hub の閲覧／デプロイ、ファイル転送（send／receive）、SSH キー、doctor のセットアップ、モデルキャッシュも含みます。
flash	Runpod サーバーレスで実行するPython を記述します。@remote／@Endpoint 関数、flash dev によるホットリロード、flash deploy が対象です。コードを中心とするもので、インフラ管理ではありません。
companion-clis	前提となる成果物：モデルのダウンロード（hf）、イメージのビルド／プッシュ（docker）、リポジトリ／リリース（gh）、S3 経由でのネットワークボリュームへのデータ移動（aws）。
runpod-usage	操作を行う前に、Runpod の仕組みを理解します。ポッドとサーバーレスの違い、コンテナのビルド、ストレージ、GPU の選択、注意点などが対象です。知識の提供のみです。
runpod-templates	公式のビルド済みポッドテンプレート（ComfyUI、PyTorch など）：このワークロード用のテンプレートがあるか、そのイメージに含まれるもの（ポート、パス、自動起動、準備状況、初回起動時に不足しているもの）を確認します。リファレンス兼ルーティングハブです。デプロイには runpod-mcp／runpodctl を使います。
runpod-build-template	リクエスト、ローカルコード、または GitHub からテンプレートプロジェクトを作成または改善します。ドキュメント付きの Dockerfile、アプリ固有のファイル、Pod／キュー／負荷分散デプロイへの引き継ぎが対象です。
runpod-migrate	既存のコードを GraphQL API または REST v1 から REST v2 に移行します。各部分がどのバージョンを使用しているかを洗い出し、呼び出し箇所を書き換え、破壊的変更を明示します。ユーザーのコードを編集しますが、インフラは管理しません。

これらのスキルはスナップショットです。正確な情報はツールを参照してください

以下の各レーンが扱うものは、それぞれ独自のリリースサイクルで提供され、このリポジトリより速いペースで更新されます。そのため、これらのスキルを使って適切なレーンに案内しつつ、機能と構文は目の前のツールから確認してください。

レーン	ツールに直接確認する内容
runpodctl	runpodctl --help、runpodctl <resource> <action> --help、runpodctl version。エラーの形式を確認するには、わざと間違ったコマンドを実行し、JSON を読みます
runpod-mcp	クライアントのツール一覧（Claude Code では /mcp）を確認します。各ツールには独自のパラメーター説明があります
flash	flash --help と、デプロイ／開発時の出力
companion-clis	各 CLI 独自の --help（hf、gh、docker、aws）
runpod-templates	runpodctl template list --type official、template get <id>（その README が正式な情報源です）
REST v2	https://api.runpod.io/v2/openapi.json にある最新の仕様

まず確認せずに、ツールではできないとユーザーに伝えてはいけません。 機能がないという主張は、ここで最も古くなりやすい情報です。また、読者には再確認する理由がありません。実際、すでに2回古くなっています（runpodctl v2.9.0 で serverless health が追加され、v2.10.0 で pod logs／serverless logs が追加されました）。制限がまだある場合は、「できない」と言うのではなく、その制限が当てはまるバージョンを示してください。

初回実行 — ツールを更新してから認証を確認する

各タスクの最初のコマンドを実行する前に更新してください。 古いビルドには、後のリリースで修正または削除されたフラグが残っています。v2.12.0 より前の runpodctl では pod create --stop-after / --terminate-after が受け付けられますが、バックエンドで適用されないため、期限を過ぎてもポッドへの課金が続いていました。これから使用する各ツールを更新してください：

runpodctl update && runpodctl version   # runpodctl
flash update                            # flash

MCP ではこの手順は不要です。ホスト型サーバーは常に最新であり、npx @runpod/mcp-server@latest でローカルインストールを開始すると最新リリースが取得されます。 タスクの残りの作業でも同じビルドを使用してください。

runpod-build-template を使用したファイルの作成には、クラウド認証情報は必要ありません。認証が必要なのは、実際にコントロールプレーンまたはその他の認証済みサービスを使用する操作だけです。

インフラストラクチャのタスク（ポッド、エンドポイント、ジョブ、ボリューム）には、動作するコントロールプレーン（Runpod MCP または runpodctl）が必要です。タスクの途中で何もセットアップされていないと気づくことのないよう、まず確認してください。セットアップされていない場合は、不完全な代替手段で続けるのではなく、ユーザーのセットアップを支援してください。

確認（認証情報の解決順序：RUNPOD_API_KEY 環境変数 → .env → ~/.runpod/config.toml）：

runpodctl user            # succeeds ⇒ a key is set and valid

さらに、Claude Code では /mcp に runpod Connected と表示される必要があります。

ルール：まずキーを取得してください。MCP OAuth をデフォルトにしないでください。 理由は、1 つの RUNPOD_API_KEY ですべてのツール（--header "Authorization: Bearer $RUNPOD_API_KEY" として認証する runpodctl + flash + ホスト型 MCP）を利用できるからです。MCP の「Runpod でサインイン」OAuth で認証されるのは MCP だけです。CLI は引き続き利用できないため、CLI 専用のタスク（send／receive、SSH、doctor、 モデルキャッシュ／Model Repository、CPU エンドポイント）で行き詰まります。⚠️ OAuth だけではセットアップが不完全です。 何もセットアップされていない場合は、作業を止めて次の順にキーを取得してください：

1. flash login — ブラウザー OAuth を使って実際のキーを ~/.runpod/config.toml に保存します（runpodctl と flash がこれを読み取り、MCP の Bearer として再利用できます）。1 ステップですべてを利用できます。人間による操作が必要です。
2. export RUNPOD_API_KEY=…（https://console.runpod.io/user/settings）— 同様にすべてを利用できます。ヘッドレスエージェントに最適です。
3. MCP OAuth のみ（/mcp → サインイン）— 最終手段です。MCP だけを使う作業向けで、CLI は引き続き未認証のままです。

次に： すでに動作する方法があれば、それを使ってください。ただし、MCP だけが OAuth 認証済みの場合は、CLI 専用の手順に進む前にキーを取得してください。CLI がない場合は、curl -sSL https://cli.runpod.net | bash（runpodctl）· uv tool install runpod-flash（flash）· npx @runpod/mcp-server@latest add（MCP）を実行してください。セットアップの全手順： runpod-usage/reference/getting-started.md。

ルーティング方法

0. 既存の実例で対応できる内容ですか？ 単一の呼び出しを超える内容では、どのレーンを選ぶか決める前に、ゴールデンパスのインデックスを確認してください。一致するパスには、レーン、フラグ、順序、注意点がすでに記載されているため、一から導き出すのではなく、読めばルーティングできます。次のいずれかに該当する場合は確認してください。

• 複数のリソース（イメージ＋テンプレート＋エンドポイント、Pod＋ボリューム、マルチリージョンなど）または複数のレーンが必要
• 課金対象のリソースをプロビジョニングする、またはユーザーの依頼が「Xを稼働／デプロイ／動作させる」という形になっている
• ストレージ、ネットワーク、自動スケーリング、ストリーミング、または稼働中のリソースのデバッグに関するもの。これらは、直感では分かりにくい順序こそが難しさのすべてを左右する領域です
• 複数ステップの計画を作成しようとしている

単一の読み取りや単一の CRUD 呼び出し（「自分の Pod を一覧表示」「Pod X を停止」「利用可能な GPU は？」など）ではステップ 0 を省略し、すぐにレーンを選んでください。一致するゴールデンパスは、ワークフローの選択において、このルーターのレーン表より優先されます。そのコマンドだけでは、機能が CLI 専用だとは判断できません。パスの順序と検証手順を維持しながら、実行レーンは現在利用可能なツールと以下の機能マトリックスに基づいて選択してください。

Dockerfile／テンプレートプロジェクトの作成や最適化を明示的に依頼された場合は、一般的なデプロイ例ではなく、パス 26を参照してください。GP26 はローカルチェックを含む作成仕様であり、ライブ環境で検証済みのデプロイ手順ではありません。既存のビルド済みイメージがあっても、依頼された成果物の代わりにはなりません。

1. 概念的な質問、またはまだ決まっていない設計上の選択（サーバーレスか Pod か？どの GPU か？モデルをイメージに含めるか、ボリュームをマウントするか？）→ まず runpod-usage を読み、その後回答に進んでください。
2. テンプレートプロジェクト／Dockerfile の作成や改善。ローカルコードや GitHub リポジトリからの変換、Hub 掲載用ファイルの準備も含みます → runpod-build-template。ビルド／プッシュの仕組みとインフラ作業は、既存の各レーンに委ねます。すでにビルド済みのイメージを再利用可能なテンプレートとして登録する（「自分のイメージからテンプレートを作成」）場合や、既存の Hub 掲載内容を閲覧／デプロイする場合は、以下のインフラレーンを使います。登録に新しい Dockerfile は不要です。
3. Pod で一般的なワークロードを実行する、またはテンプレート Pod を修復する（「ComfyUI／PyTorch 開発環境を実行」、起動しない、モデルがないなど）→ runpod-templates。インストールを計画する前に公式のビルド済みテンプレートがないか確認し、修復方法の選択は任せてください。
4. Runpod GPU 上で、コード中心のワークフローを使って独自のコードを作成／反復／公開する → flash。
5. 成果物を作成する（モデルをダウンロードする、イメージをビルドしてプッシュする、リポジトリのリリースを作成する、データをボリュームに同期する）→ companion-clis。
6. 既存のコードを Runpod API のバージョン間で移行する。「REST v2 に移行する」「このリポジトリはどの Runpod API を使っているか？」「アップグレードすると何が壊れるか？」など → runpod-migrate。（API を呼び出して何かを実行するのは別の作業であり、以下のインフラレーンを使います。）
7. インフラを管理する（Pod、エンドポイント、テンプレート、ボリュームの作成／一覧表示／更新／削除、GPU／データセンターの一覧表示、サーバーレスジョブの実行、請求）：
   • CLI でのみ使える機能 — send／receive、SSH キー、doctor、モデルキャッシュ → runpodctl。
   • それ以外の場合、このセッションで Runpod の MCP ツールが接続されている（create-pod、list-endpoints などが利用可能） → runpod-mcp。
   • それ以外（シェルのみのエージェントで、MCP なし） → runpodctl。

runpod-mcp と runpodctl（重複する機能）

どちらも同じ Runpod API を操作するため、インフラの CRUD では機能が重複します。選ぶ際は、まず機能、次に環境を基準にしてください。

• ツールが接続されている場合、シンプルで構造化された操作（読み取りや基本的な CRUD）では、利便性の点で MCP が優れています（型付きパラメーターを使え、シェルのクォートが不要です）。
• 操作に MCP にはない機能が必要な場合は、MCP が接続されていても runpodctl に切り替えます。シェルのみを使うエージェントにとって唯一の選択肢であり、ユーザーが再現可能なコマンドを求める場合にも適しています。

機能マトリックス（操作ごとに推奨される方法を選択してください）：

操作	推奨される方法	理由
あらゆる対象の一覧表示／取得、Pod の起動／停止／再起動／削除、エンドポイント、テンプレート、ボリューム、レジストリの基本的な CRUD、カタログ、課金	接続されていれば runpod-mcp、そうでなければ runpodctl	シンプルで構造化された操作には、型付きで便利な MCP が適しています
シンプルな Pod（イメージ 1 つ＋GPU 1 つ）の作成	接続されていれば runpod-mcp、そうでなければ runpodctl	どちらでも対応できます
テンプレートからの Pod、または CPU Pod の作成	接続されていれば runpod-mcp、そうでなければ runpodctl	MCP の create-pod は templateId（v2 専用）と computeType: "CPU" を受け取ります
複数 GPU の優先リストを指定した Pod、またはテンプレートと CPU を組み合わせた Pod の作成	runpodctl	MCP では GPU タイプを 1 つに限定しており、CPU Pod へのテンプレートのデプロイは拒否されます
既存の Hub 掲載項目の閲覧またはデプロイ	接続されており、要求された操作が提供されていれば runpod-mcp、そうでなければ runpodctl	実際に利用できるツールを確認してください。Hub であることだけを理由に CLI に切り替える必要はありません
ファイル転送（send／receive）、SSH キー／情報、doctor によるセットアップ、モデルキャッシュ	runpodctl	MCP にはこれらを行うツールがありません
サーバーレスジョブの実行（run／runsync／ステータス／ストリーム）	接続されていれば runpod-mcp、そうでなければ runpodctl	どちらにもジョブ専用コマンドが用意されています（runpodctl serverless run／status／health、v2.9.0 以降）。MCP は型付きで、ジョブの増分出力をストリーミングできるのは MCP のみです（stream-job）
Pod またはワーカーのログの読み取り	どちらでも可 — 接続されていれば runpod-mcp、そうでなければ runpodctl	どちらもログを読み取れます。MCP の stream-pod-logs／stream-worker-logs は解析済みフレームを返し、runpodctl の pod logs／serverless logs は json 行を出力し、--follow（v2.10.0 以降）にも対応しています

判断の目安：簡単な操作は MCP を標準とし、MCP で利用できないフラグや機能が必要になった時点で runpodctl に切り替えてください。

ワークロードのデプロイ（ゴールデンループ）

「Runpod で を実行する」タスクでは、runpod-usage/reference/development-loop.md の開発ループに従います。Pod とサーバーレスのどちらにするか決定 → プロビジョニング → セットアップ（ゼロから構築する場合のみ）→ 検証 → 引き渡し → コスト管理とティアダウン。このループでは、次のルールが適用されます。

• ゼロからイメージを構築するより、ビルド済みのテンプレート／Hub ワーカーを優先してください — ただし、ユーザーがカスタムテンプレートプロジェクトまたは Dockerfile を明示的に希望している場合を除きます。 公式 Pod テンプレートは runpod-templates にインデックスされています。
• 引き渡す前に、Pod／エンドポイントの外部から実際にリクエストを送信してワークロードを検証してください。 「Running」／「ready」ステータスだけでは、サービスが提供されているとは限りません。
• デフォルトでは Secure Cloud を使用してください。 Community Cloud のホストは承認済みベンダーです。Secure Cloud のホストはデータセンター品質のプロバイダーであるため、より安定した動作が期待できます。ユーザーが明示的に希望した場合にのみ、Community をデプロイしてください。（runpodctl pod create はすでにデフォルトで --cloud-type SECURE を使用するため、上書きしないでください。）
• キャッシュとネットワークボリュームの選択はコストではなく、レイテンシに関する判断です。 ダウンロード時間は課金されませんが、キャッシュミス時には、モデルが配置されるまで Runpod がワーカーの起動を保留します。その間、ジョブはキューに滞留し、エンドポイントはアイドル状態に見えます。レイテンシが重要な場合は、ネットワークボリュームに事前ロードしてください。それ以外の場合は、デフォルトでキャッシュを使うほうが安価です。キャッシュ容量はマシンごとに異なるため、しきい値を提示するのではなく、ユーザー自身のエンドポイントで両方の所要時間を計測してください。詳しくは runpodctl/reference/model-caching.md を参照してください。
• GPU の作成時には毎回、CUDA の下限バージョンを指定してください — runpodctl では --min-cuda-version 12.8、REST v2 および MCP では gpu.minCudaVersion: "12.8"（CUDA 13 のイメージの場合のみ 13.0）を指定します。指定しないと、作成時にどのホスト CUDA バージョンでも受け入れられます。その結果、新しいイメージが実行には古すぎるホストに配置され、コンテナーが起動時に終了するか、気付かないうちに CPU で実行されるように見える場合があります。 gpu-selection.md。

このループは、次の 2 つのサブループに分岐します。

• URL からアクセスするサービス（Ollama、ComfyUI、開発ボックス）→ runpod-usage/reference/pod-workflows.md （作成時にポート、環境変数、ボリュームを設定し、SSH-exec でインストールし、0.0.0.0 にバインドして、プロキシ URL をポーリングします）。runpodctl の手順で実行してください。
• ゼロまでスケールするリクエスト／レスポンス API（Whisper、推論）→ runpod-usage/reference/endpoint-workflows.md （Hub ワーカー、flash、カスタムイメージのいずれかを選び、/run／/runsync を呼び出し、ジョブのステータスをポーリングします）。

実例（成功パターン）

これは付録ではなく、ルーティングのステップ 0です。エンドツーエンドのシナリオが 24 件あり（ほとんどは実際のアカウントでライブ検証済みです）、実際のコマンドと確認された出力をそのまま使える形で ./golden-paths/README.md にまとめています。各シナリオには「注意点」と「コストとクリーンアップ」のセクションもあり、ここは自力で再発見するにはコストがかかる部分です。

以下の行からタスクに合うものを選び、計画を立てたり何かを呼び出したりする前に、該当するパスを開いてください。 一部しか一致しない場合でも、開く価値があります。モデル、GPU、リージョンが違っても、最も近いパスの手順や注意点はたいてい応用できます。ここに近いものが何もない場合に限り、上記のレーン表に進んでください。

やりたいこと…	成功パターン
URL でアクセスできるポッド上でサーバー（Ollama／ComfyUI）を実行する	01、02
サーバーレスのモデルエンドポイントをデプロイする（Hub／flash／カスタムイメージ）	03、05
HuggingFace モデルをイメージやボリュームに含めずに提供する（ホストキャッシュ）	20 — モデルのキャッシュ（--model-reference）
すぐに利用できるホスト型モデルを呼び出す（デプロイ不要）	11 — パブリックエンドポイント
ファインチューニングしてから、その結果を提供する	04、08
対話型の開発環境（SSH／VS Code）	06
データをポッド → ボリューム → サーバーレスへ移動する	07
flash では不十分な場合のカスタムサーバーレス（デュアルモードイメージの開発ループ）	09
コード、リポジトリ、またはアプリの依頼をもとに、完全なテンプレートプロジェクトを作成または改善する	26 — プロジェクトの作成
対象に合わせた最小限のイメージを作成する（ポッドとサーバーレスキュー）	22（ポッド）、23（キュー）。概念についてはイメージのビルドを参照
イメージに含めるものとネットワークボリュームにマウントするものを決める	25 — イメージに含めるかマウントするか
ネットワークボリュームのストレージ階層（標準と高性能）を選ぶ	21 — ストレージ階層
高可用性／マルチリージョンのサーバーレス（複数ボリューム＋データ同期）	10、19（3 リージョン）
出力を逐次ストリーミングする（/stream）	12
オートスケーリングを調整する／ワーカーあたりのスループットを上げる	13（オートスケーリング）、18（並行処理）
ロードバランサー／HTTP サーバーまたは WebSocket ワーカー	14（ロードバランサー）、17（WebSocket）
ジョブの完了通知を受け取る（ポーリングではなくプッシュ）	16 — Webhook
エンドポイントのヘルスチェックを行う／障害のあるエンドポイントをデバッグする	15 — 監視とデバッグ

複数レーンにまたがるタスク

順序は常に理解 → 成果物の作成 → インフラの管理 → 検証です。 インフラから参照できるのは、すでに存在する成果物だけだからです。各ステップは 1 つのレーン内で進め、認証情報の境界でレーンを切り替えてください。

例 — 「openai/gpt-oss-20b をサーバーレスエンドポイントにデプロイする」：

1. runpod-usage — サーバーレスとポッドのどちらにするか、20B 向けの GPU 階層、イメージに含めるか、マウントするか、キャッシュするかを判断します。
2. companion-clis — hf download …、docker build --platform=linux/amd64 …、docker push を実行します。
3. runpod-mcp または runpodctl — イメージと GPU プールを指定してエンドポイントを作成します。
4. 同じインフラレーン — エンドポイントを呼び出す／ステータスを確認して検証します。

認証

必要なのは RUNPOD_API_KEY（https://console.runpod.io/user/settings）だけです。 各方法では、このキーを利用可能にします。runpodctl doctor、flash login、MCP の stdio 環境変数、または MCP ホスト版の「Runpod でサインイン」（OAuth、キーをディスクに保存しません）です。 連携する CLI はそれぞれ独自の認証情報（HuggingFace トークン、GitHub 認証、 Docker Hub PAT、aws 用の Runpod S3 キー）を使用します。これらに RUNPOD_API_KEY を使い回さないでください。