runpod

Runpod (router)

The entrypoint for the Runpod skills. This skill does no work itself: it picks the lane and points at the golden path or journey skill that carries the procedure. For a multi-step or provisioning task, check the worked examples first and let the matching one pick the lane; otherwise read the matching skill's SKILL.md next.

Who owns what (one home per rule; the others link to it):

Topic	Owner
Lane choice, MCP-vs-runpodctl matrix, golden-path index	this skill
MCP answer contract, MCP connection and auth, MCP tool-use rules, journey routing	runpod-mcp (load it before the first Runpod MCP tool call)
Credentials for every lane, tool updates, control-plane check	getting-started.md
Deployment loop (prefer prebuilt, plan, verify, teardown)	development-loop.md
CUDA floor, Secure vs Community Cloud	gpu-selection.md (steps 3 and 5)

The lanes

Lane	Use it for
runpod-mcp	Manage infra (pods, endpoints, jobs, templates, volumes, registries, catalog, billing) via structured tool calls — when the Runpod MCP tools are connected in this session. It routes on to the journey skill for the task.
runpodctl	Manage the same infra from a terminal/CI/script, including Hub browse/deploy, file transfer (send/receive, network-volume upload/download), SSH keys, doctor setup, and model cache.
runpod-flash	Write Python that runs on Runpod serverless with the Runpod SDK — runpod.App with @app.queue/@app.api/@app.task, rp flash dev, rp flash deploy; also maintains or migrates legacy runpod-flash projects. Code-first, not infra management.
runpod-companion-clis	Prerequisite artifacts: download a model (hf), build/push an image (docker), repos/releases (gh), other S3 tools against a network volume (aws; runpodctl v3.1.0+ network-volume upload/download is the default for moving files).
runpod-usage	Understand how Runpod works before acting — pods vs serverless, building a container, storage, GPU selection, gotchas. Knowledge only.
runpod-templates	Official prebuilt pod templates (ComfyUI, PyTorch, …): is there one for this workload, and what does its image ship — ports, paths, autostart, readiness, what's missing on first boot. Reference + routing hub; deploy via runpod-mcp/runpodctl.
runpod-build-template	Create or improve a template project from a request, local code, or GitHub: documented Dockerfile, app-specific files, and Pod/queue/load-balanced deployment handoff.
runpod-migrate	Move existing code off the GraphQL API or REST v1 onto REST v2 — inventory which parts use which version, rewrite call sites, flag breaking changes. Edits the user's code; does not manage infra.

These skills are a snapshot; the tools are the source of truth

Every lane wraps something that ships on its own release train and moves faster than this repo. So route with these skills, but take capability and syntax from the tool in front of you:

Lane	Ask it directly
runpodctl	runpodctl --help, runpodctl <resource> <action> --help, runpodctl version. For failure shapes, run a command wrong on purpose and read the JSON
runpod-mcp	your client's tool list (/mcp in Claude Code); rules in runpod-mcp
runpod-flash	rp --help, rp flash <command> --help, pip show runpod, and the dev/deploy output
runpod-companion-clis	that CLI's own --help (hf, gh, docker, aws)
runpod-templates	runpodctl template list --type official, template get <id> (its readme is authoritative)
REST v2	the live spec at https://api.runpod.io/v2/openapi.json

Never tell a user a tool cannot do something without checking first. A missing capability is the claim most likely to be out of date here, and it is the one a reader has no reason to reverify — it has already gone stale twice (runpodctl v2.9.0 added serverless health, v2.10.0 added pod logs/serverless logs). If a limit still holds, name the version it holds for rather than saying "cannot".

Before the first command

• Update the CLI you are about to use (runpodctl update, rp update; the MCP needs no step). runpodctl before v2.12.0 accepts --stop-after/--terminate-after, which the backend never enforced, so pods kept billing past the deadline.
• Check the control plane before infra work: runpodctl user succeeds, or /mcp shows runpod Connected. If neither works, help the user set up rather than limping on.
• MCP OAuth first, a key only when a task needs one: get RUNPOD_API_KEY (rp login with a human at an interactive terminal, else export) at the first CLI-only step; with no user in the loop, use the key from the start. Companion CLIs use their own credentials, never RUNPOD_API_KEY.

Details, install commands and the per-lane key table: getting-started.md.

How to route

0. Does a worked example already cover this? For anything beyond a single call, check the golden-paths index before picking a lane — a matching path already names the lane(s), the flags, the ordering, and the traps, so routing becomes reading rather than re-deriving. Check it when any of these is true:

• the task needs more than one resource (image + template + endpoint, pod + volume, multi-region, …) or more than one lane
• it provisions something billable, or the user's ask is shaped like "get X running / deployed / working"
• it involves storage, networking, autoscaling, streaming, or debugging a live resource — the areas where the non-obvious ordering is the whole difficulty
• you are about to write a multi-step plan for it

Skip step 0 for a single read or a single CRUD call ("list my pods", "stop pod X", "what GPUs are available") — go straight to the lane. A matching golden path outranks this router's lane table for workflow selection. Its commands do not establish that a capability is CLI-only: choose the execution lane from the live tool surface and the capability matrix below, while preserving the path's ordering and verification steps.

For an explicit request to create or optimize a Dockerfile/template project, match path 26 before generic deployment examples; GP26 is an authoring specification with local checks, not a live-verified deployment. An existing prebuilt does not replace the requested deliverable.

1. Conceptual question, or an unmade design choice (serverless vs pod? which GPU? bake the model or mount a volume?) → read runpod-usage first, then continue with the answer.
2. Author or improve a template project / Dockerfile, including converting local code or a GitHub repository, or prepare its Hub listing files → runpod-build-template. It delegates build/push mechanics and infrastructure work to their existing lanes. Registering an already-built image as a reusable template ("make a template from my image") and browsing/deploying an existing Hub listing use the infrastructure lanes below; registration needs no new Dockerfile.
3. Run a common workload on a pod, or fix a template pod ("run ComfyUI / PyTorch dev box", won't boot, missing models) → runpod-templates — check for an official prebuilt before planning any install, and let it route repairs.
4. Write/iterate/ship your own code on Runpod GPUs using its code-first workflow → runpod-flash.
5. Produce an artifact (download a model, build+push an image, create a repo release, sync data to a volume) → runpod-companion-clis.
6. Migrate existing code between Runpod API versions — "move us to REST v2", "which Runpod API is this repo on?", "what breaks if we upgrade?" → runpod-migrate. (Calling the API to do something is a different job; that is the infra lanes below.)
7. Manage infrastructure (create/list/update/delete pods, endpoints, templates, volumes; list GPUs/data centers; run a serverless job; billing):
   • A capability only the CLI has (the runpodctl rows of the matrix below) → runpodctl.
   • Otherwise, if the Runpod MCP tools are connected in this session (create-pod, list-endpoints, … are available) → runpod-mcp.
   • Otherwise (shell-only agent, no MCP) → runpodctl.

runpod-mcp vs runpodctl (the overlap)

Both drive the same Runpod API, so they overlap on infra CRUD. Choose by capability first, environment second:

• MCP wins on convenience for simple, structured operations — reads and basic CRUD — when its tools are connected (typed params, no shell quoting).
• runpodctl takes over when an operation needs a capability MCP lacks — even if MCP is connected — and is the only option for a shell-only agent or when the user wants a reproducible command.

Capability matrix (pick the preferred lane per operation):

Operation	Preferred lane	Why
List/get anything; start/stop/restart/delete a pod; simple CRUD on endpoints, templates, volumes, registries; catalog; billing	runpod-mcp if connected, else runpodctl	Simple structured ops — MCP is typed and convenient
Create a simple pod (one image + one GPU)	runpod-mcp if connected, else runpodctl	Both handle it
Create a pod from a template, a CPU pod, or both together	runpod-mcp if connected, else runpodctl	MCP's create-pod takes templateId and, for CPU, a cpu object in place of gpu; template + CPU in one create live-verified 2026-10-29. runpodctl v3 sends the same v2 create, so it is no fallback. Field semantics: runpod-mcp pod creates
Create a pod with a multi-GPU priority list	neither: one GPU type per create	v2 create-pod takes one gpu.id, and runpodctl rejects a comma list in --gpu-id (only one gpu id is supported; checked through v3.0.1). Pick one type from the stock read; on a capacity error, retry with the next
Browse or deploy an existing Hub listing	runpod-mcp if connected and it exposes the requested operation, else runpodctl	Check the live tool surface; Hub is not a reason by itself to switch to the CLI
File transfer (send/receive, network-volume upload/download), SSH keys/info, doctor setup, model cache	runpodctl	MCP has no tool for these
Invoke a serverless job (run/runsync/status/stream)	runpod-mcp if connected, else runpodctl	Both lanes have first-class job commands now (runpodctl serverless run/status/health, v2.9.0+); MCP is typed, and only MCP streams a job's incremental output (stream-job)
Read pod or worker logs	either — runpod-mcp if connected, else runpodctl	Both lanes read them: MCP stream-pod-logs/stream-worker-logs return parsed frames; runpodctl pod logs/serverless logs emit json lines and --follow (v2.10.0+)

Rule of thumb: default to MCP for the easy stuff, hand off to runpodctl the moment an op needs a flag/feature MCP doesn't expose.

Deploying a workload (the golden loop)

For any "get <X> running on Runpod" task, follow development-loop.md: decide pod vs serverless → provision → set up (only if from-scratch) → verify → deliver → cost-guard + teardown. Its binding rules, in one line each: prefer a prebuilt template / Hub worker unless the user asked for a custom template project; pin the CUDA floor on every GPU create (--min-cuda-version 12.8 / gpu.minCudaVersion: "12.8", 13.0 only for a CUDA-13 image; without it an image can land on a host too old for it and die at startup or silently run on CPU; why); default to Secure Cloud; cache vs network volume is a latency call (download time is not billed, but a cache miss holds the worker start, so the job queues and the endpoint looks idle); stock picks the data center, the network volume follows (read per-data-center GPU stock, create the volume once where the GPU is, and on a stock refusal keep it: retry once there or let the user choose; why); and verify with a real request from outside before delivering — "Running"/"ready" does not mean serving.

It branches to two sub-loops:

• Service you open at a URL (Ollama, ComfyUI, dev box) → runpod-usage/reference/pod-workflows.md (ports + env + volume at creation, SSH-exec install, bind 0.0.0.0, poll the proxy URL). Execute in the runpodctl lane.
• Request/response API that scales to zero (Whisper, inference) → runpod-usage/reference/endpoint-workflows.md (Hub worker vs flash vs custom image; invoke /run//runsync; poll job status).

Worked examples (golden paths)

This is step 0 of routing, not an appendix. Two dozen end-to-end scenarios live in ./golden-paths/README.md, each with a status header (live-verified with a date, spec-checked, or legacy; check it before trusting a path), the real commands and observed output, plus a Gotchas and a Cost & cleanup section, which is the part that is expensive to rediscover.

Match the task to a row below and open that path before you plan or call anything. A partial match is still worth opening: the closest path's ordering and gotchas usually transfer even when the model, GPU, or region does not. Only fall through to the lane tables above when nothing here is close.

Want to…	Golden path
Run a server (Ollama/ComfyUI) on a pod at a URL	01, 02
Deploy a serverless model endpoint (Hub / flash / custom image)	03, 05
Serve an LLM with vLLM (Pod, load-balancing or Hub queue endpoint)	27 — vLLM Pod → endpoint; procedure in runpod-vllm
Install vLLM or ComfyUI privately on a Pod you already run (pinned, loopback, API-driven)	vLLM: runpod-vllm existing-pod; ComfyUI: 02 Variant C
Serve a HuggingFace model without baking it in or a volume (host-cached)	20 — model caching (--model-reference)
Call a ready hosted model (no deploy)	11 — Public Endpoints
Fine-tune, then serve the result	04, 08
Interactive dev box (SSH / VS Code)	06
Move data pod → volume → serverless	07
Custom serverless when flash isn't enough (dual-mode image dev loop)	09
Create or improve a complete template project from code, a repo or an app request	26 — project authoring
Build a minimal image for a target (pod vs serverless queue)	22 (pod), 23 (queue); concepts in building-images
Decide what to bake into the image vs mount on a network volume	25 — bake vs mount
Pick a network-volume storage tier (standard vs high-performance)	21 — storage tiers
High availability / multi-region serverless (multi-volume + data sync)	10, 19 (3-region)
Stream output incrementally (/stream)	12
Tune autoscaling / raise per-worker throughput	13 (autoscaling), 18 (concurrency)
Load-balancing / HTTP-server or WebSocket worker	14 (LB), 17 (WebSocket)
Get notified on job completion (push, not poll)	16 — webhooks
Check health / debug a failing endpoint	15 — monitor & debug

Multi-lane tasks

Sequence is always understand → produce artifacts → manage infra → verify, because infra can only reference artifacts that already exist. Keep each step in one lane, and switch lanes at credential boundaries.

Example — "deploy openai/gpt-oss-20b to a serverless endpoint":

1. runpod-usage — serverless vs pod, GPU tier for 20B, bake vs mount vs cache.
2. runpod-companion-clis — hf download …, docker build --platform=linux/amd64 …, docker push.
3. runpod-mcp or runpodctl — create the endpoint referencing the image + GPU pool.
4. Same infra lane — invoke the endpoint / check status to verify.