Runpod (router)
The entrypoint for the Runpod skills. This skill does no work itself — it picks
the right lane and hands off. Read the matching skill's
next.
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. |
| runpodctl | Manage the same infra from a terminal/CI/script, plus the things only the CLI does: Hub browse/deploy, / file transfer, SSH keys, setup, model cache. |
| flash | Write Python that runs on Runpod serverless — / functions, hot-reload, . Code-first, not infra management. |
| companion-clis | Prerequisite artifacts: download a model (), build/push an image (), repos/releases (), move data to a network volume over S3 (). |
| runpod-usage | Understand how Runpod works before acting — pods vs serverless, building a container, storage, GPU selection, gotchas. Knowledge only. |
First run — check auth before the first infra action
Infra tasks (pods, endpoints, jobs, volumes) need a working control plane — the Runpod MCP
or runpodctl. Don't start and discover mid-task that nothing's set up: check first, and if
it isn't, help the user set up rather than limping on a partial fallback.
Check (credential resolution order:
env →
→
):
bash
runpodctl user # succeeds ⇒ a key is set and valid
Plus, in Claude Code,
should show
Connected.
Rule: get a key first — do not default to MCP OAuth. The reason: one
unlocks every tool — it authenticates
runpodctl + flash + the hosted MCP (as
--header "Authorization: Bearer $RUNPOD_API_KEY"
). The MCP's "Sign in with Runpod" OAuth auths the
MCP alone — the CLIs
stay blocked, so you hit a wall on any CLI-only task (Hub,
/
, SSH,
,
model cache/Model Repository, CPU endpoints). ⚠️
OAuth-only is a half-setup. If nothing's
set up, stop and get a key, in order:
- — browser OAuth that saves a real key to (runpodctl
- flash read it; reuse it for the MCP Bearer). One step, unlocks all. Human-only.
- (https://console.runpod.io/user/settings) — same full unlock;
best for headless agents.
- MCP OAuth only ( → Sign in) — last resort, MCP-only work; CLIs stay unauthed.
Then: if a lane already works, use it — but if
only the MCP is OAuth'd, still get a key
before any CLI-only step. Missing a CLI?
curl -sSL https://cli.runpod.net | bash
(runpodctl) ·
uv tool install runpod-flash
(flash) ·
npx @runpod/mcp-server@latest add
(MCP). Full setup:
runpod-usage/reference/getting-started.md
.
How to route
- 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.
- Write/iterate/ship your own code on Runpod GPUs → flash.
- Produce an artifact (download a model, build+push an image, create a repo
release, sync data to a volume) → companion-clis.
- Manage infrastructure (create/list/update/delete pods, endpoints,
templates, volumes; list GPUs/data centers; run a serverless job; billing):
- Capability only the CLI has — Hub, /, SSH keys, ,
model cache → runpodctl.
- Otherwise, if the Runpod MCP tools are connected in this session
(, , … 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 or a CPU pod | runpod-mcp if connected, else runpodctl | MCP's create-pod takes (v2-only) and |
| Create a pod with a multi-GPU priority list, or template + CPU together | runpodctl | MCP narrows to one GPU type, and rejects a template deploy for a CPU pod |
| Deploy from the Hub | runpod-mcp if connected, else runpodctl | MCP has + |
| File transfer (/), SSH keys/info, setup, model cache | runpodctl | MCP has no tool for these |
| Invoke a serverless job (//status/stream) | runpod-mcp if connected, else runpodctl | MCP has first-class job tools |
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 the
development loop in
runpod-usage/reference/development-loop.md
: decide pod vs serverless → provision → set up
(only if from-scratch) → verify → deliver → cost-guard + teardown. Two rules bind within it:
- Prefer a prebuilt template / Hub worker over building an image from scratch.
- Before delivering, verify the workload with a real request from outside the pod/endpoint
— a "Running"/"ready" status does not mean it is serving.
It branches to two sub-loops:
- Service you open at a URL (Ollama, ComfyUI, dev box) →
runpod-usage/reference/pod-workflows.md
- Request/response API that scales to zero (Whisper, inference) →
runpod-usage/reference/endpoint-workflows.md
Worked examples (golden paths)
Two dozen end-to-end scenarios (nearly all
live-verified) live in
— the yardstick for "can
an agent finish the job", with real commands + observed output to copy from. When a
task matches one,
open its golden path first instead of re-deriving it:
| 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 a HuggingFace model without baking it in or a volume (host-cached) | 20 — model caching () |
| 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 |
| 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 |
| High availability / multi-region serverless (multi-volume + data sync) | 10, 19 (3-region) |
| Stream output incrementally () | 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
to a serverless endpoint":
- runpod-usage — serverless vs pod, GPU tier for 20B, bake vs mount vs cache.
- companion-clis — ,
docker build --platform=linux/amd64 …
- runpod-mcp or runpodctl — create the endpoint referencing the image + GPU pool.
- Same infra lane — invoke the endpoint / check status to verify.
Auth
Everything is one key:
(
https://console.runpod.io/user/settings).
Each lane just makes that key resolvable —
,
, MCP
stdio env var, or MCP hosted "Sign in with Runpod" (OAuth, no key on disk).
Companion CLIs use their
own credentials (HuggingFace token, GitHub auth,
Docker Hub PAT, Runpod
S3 keys for
) — do not reuse
for
those.