
runpod
Start here for any Runpod task — running GPU/CPU pods, deploying serverless endpoints, templates, network volumes, building images, or understanding how Runpod works. Routes to the right skill (runpod-mcp, runpodctl, flash, companion-clis, runpod-usage, runpod-templates, runpod-build-template, runpod-migrate) and indexes two dozen live-verified end-to-end examples (golden paths) — use it when the lane is unclear, and for any multi-step or provisioning task even when it is not.
- Installs
- 13.8K
- Last 24h
- +147
- Trending rank
- #1499
- Security
- Warn
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/runpod/runpod-plugins-official --skill runpod- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads runpod automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
Runpod (router)
The entrypoint for the Runpod skills. This skill does no work itself — it picks
the right lane and hands off. 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.
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. Routes on to the journey skill for the task (discovery, lifecycle-crud, serverless-deploy, pod-deploy, pod-doctor, endpoint-ops, cost-audit). |
| runpodctl | Manage the same infra from a terminal/CI/script, including Hub browse/deploy, file transfer (send/receive), SSH keys, doctor setup, and model cache. |
| flash | Write Python that runs on Runpod serverless — @remote/@Endpoint functions, flash dev hot-reload, flash deploy. Code-first, not infra management. |
| companion-clis | Prerequisite artifacts: download a model (hf), build/push an image (docker), repos/releases (gh), move data to a network volume over S3 (aws). |
| 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 below 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) — each tool carries its own parameter descriptions |
| flash | flash --help, and the deploy/dev output |
| 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".
First run — update the tools, then check auth
Update before the first command of every task. Old builds keep flags that later releases
fixed or removed. runpodctl before v2.12.0 accepts pod create --stop-after /
--terminate-after, but the backend never enforced them, so pods kept billing past the
deadline. Update each tool you are about to use:
runpodctl update && runpodctl version # runpodctl
flash update # flash
The MCP needs no step: the hosted server is always current, and a local install started with
npx @runpod/mcp-server@latest fetches the latest release.
Use the same build for the rest of the task.
File authoring with runpod-build-template needs no cloud credentials. Check auth only when an operation actually uses the control plane or another authenticated service.
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: RUNPOD_API_KEY env → .env → ~/.runpod/config.toml):
runpodctl user # succeeds ⇒ a key is set and valid
Plus, in Claude Code, /mcp should show runpod Connected.
Rule: get a key first — do not default to MCP OAuth. The reason: one RUNPOD_API_KEY
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 (send/receive, SSH, doctor,
model cache/Model Repository, CPU endpoints). ⚠️ OAuth-only is a half-setup. If nothing's
set up, stop and get a key, in order:
flash login— browser OAuth that saves a real key to~/.runpod/config.toml(runpodctl- flash read it; reuse it for the MCP Bearer). One step, unlocks all. Human-only.
export RUNPOD_API_KEY=…(https://console.runpod.io/user/settings) — same full unlock; best for headless agents.- MCP OAuth only (
/mcp→ 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
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.
- 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.
- 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.
- 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.
- Write/iterate/ship your own code on Runpod GPUs using its code-first workflow → flash.
- Produce an artifact (download a model, build+push an image, create a repo release, sync data to a volume) → companion-clis.
- 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.)
- Manage infrastructure (create/list/update/delete pods, endpoints,
templates, volumes; list GPUs/data centers; run a serverless job; billing):
- Capability only the CLI has —
send/receive, SSH keys,doctor, model cache → 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.
- Capability only the CLI has —
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 templateId (v2-only) and computeType: "CPU" |
| 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 |
| 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), 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 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. These rules bind within it:
- Prefer a prebuilt template / Hub worker over building an image from scratch —
except when the user explicitly requests a custom template project or Dockerfile;
official pod templates are indexed in
runpod-templates. - Before delivering, verify the workload with a real request from outside the pod/endpoint — a "Running"/"ready" status does not mean it is serving.
- Default to Secure Cloud. Community Cloud hosts are approved vendors; Secure Cloud
hosts are data-center-grade providers and so tend toward more stable behavior. Only
deploy Community when the user explicitly asks. (
runpodctl pod createalready defaults to--cloud-type SECURE; don't override it.) - Cache vs network volume is a latency call, not a cost call. Download time is never
billed, but on a cache miss Runpod holds the worker start until the model lands — the
job sits in the queue and the endpoint looks idle. Latency-sensitive → pre-load a
network volume; otherwise the cache is the cheaper default. Cache capacity is per
machine, so time both on the user's own endpoint rather than quoting a threshold. See
runpodctl/reference/model-caching.md. - Pin the CUDA floor on every GPU create —
--min-cuda-version 12.8in runpodctl,gpu.minCudaVersion: "12.8"in REST v2 and MCP (13.0only for a CUDA-13 image). Without it the create accepts any host CUDA version and a modern image can land on a host too old to run it, which reads as a container that dies at startup or silently runs on CPU:gpu-selection.md.
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, bind0.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
(nearly all live-verified on a real account) live in
./golden-paths/README.md, with the real commands and the
observed output to copy from — plus a Gotchas and a Cost & cleanup section each, 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 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":
- runpod-usage — serverless vs pod, GPU tier for 20B, bake vs mount vs cache.
- companion-clis —
hf download …,docker build --platform=linux/amd64 …,docker push. - 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: RUNPOD_API_KEY (https://console.runpod.io/user/settings).
Each lane just makes that key resolvable — runpodctl doctor, flash login, 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 aws) — do not reuse RUNPOD_API_KEY for
those.
FAQ
What does the runpod skill do?
Start here for any Runpod task — running GPU/CPU pods, deploying serverless endpoints, templates, network volumes, building images, or understanding how Runpod works. Routes to the right skill (runpod-mcp, runpodctl, flash, companion-clis, runpod-usage, runpod-templates, runpod-build-template, runpod-migrate) and indexes two dozen live-verified end-to-end examples (golden paths) — use it when the lane is unclear, and for any multi-step or provisioning task even when it is not.
How do I install runpod?
Run npx skills add https://github.com/runpod/runpod-plugins-official --skill runpod in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/runpod/ (personal) or .claude/skills/runpod/ (project).
Which AI agents can use runpod?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is runpod safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket flagged items to review; Snyk passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains runpod?
It is published by runpod in runpod/runpod-plugins-official. It has 13,756 recorded installs.
More from runpod/runpod-plugins-official
runpodctl
runpod/runpod-plugins-official
Runpod CLI for managing GPU/CPU workloads from the terminal — pods, serverless endpoints, templates, network volumes, Hub deploys, models, SSH, and file transfer (send/receive). Use for terminal/CI/scripting, SSH setup, doctor, or when the Runpod MCP tools are not connected; prefer runpod-mcp for structured tool calls in an MCP-enabled session.
flash
runpod/runpod-plugins-official
Write and deploy code-first Runpod Serverless with runpod-flash: @Endpoint/@remote, flash dev, resource configuration, and debugging. Use runpod-build-template for explicit Dockerfile/template project authoring, and runpodctl/runpod-mcp for infrastructure management.
companion-clis
runpod/runpod-plugins-official
Companion CLIs for Runpod workflows — HuggingFace, GitHub, Docker, and AWS. Use runpod-build-template for complete template project authoring, and the ComfyUI model-repair guide in runpod-templates for imported workflows lacking model download metadata.
runpod-usage
runpod/runpod-plugins-official
Explain Runpod architecture and design choices: Pods versus Serverless, GPU/VRAM, image construction, storage, networking, and workload development. For creating or improving a complete template project use runpod-build-template; execute infrastructure with runpodctl/runpod-mcp and code-first work with flash.
runpod-mcp
runpod/runpod-plugins-official
Manage Runpod infrastructure through the connected Runpod MCP server's tool calls (pods, serverless endpoints and jobs, templates, network volumes, registry credentials, secrets, clusters, the GPU/CPU catalog, and billing), and connect the server when it is missing (hosted or local npx). Load it before the first Runpod MCP tool call of a request: it routes the task to the journey skill that carries the procedure, owns the answer contract and the rules on which resources you may change, and defers to runpodctl for the terminal, file transfer, and SSH setup; template project and Hub listing authoring routes to runpod-build-template.
runpod-migrate
runpod/runpod-plugins-official
Migrate a codebase from the Runpod GraphQL API or REST v1 to REST v2 — inventory which parts use which API version, rewrite the call sites, flag breaking changes, and verify. Use when someone asks to move to v2, asks what v2 would change, or asks which Runpod API their code is on. For managing infrastructure rather than migrating code, use runpod-mcp or runpodctl.
Popular productivity & automation skills
agent-browser
vercel-labs/agent-browser
Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools.
lark-doc
open.feishu.cn
飞书云文档(Docx / Wiki)内容操作:读取、创建、编辑文档,插入或下载图片附件,以及操作思维笔记。用户提供文档 URL/token(包括 doubao.com 的 /docx/、/wiki/)时使用;按 URL 路径/token 而非域名路由;/page/ 是妙搭应用,非飞书云文档。文档内嵌资源按读取参考中的统一规则分流。独立评论操作走 lark-drive;随正文读取评论使用 docs +fetch。表格或 Base 内部数据操作不在本 skill。
lark-drive
open.feishu.cn
飞书云空间(云盘/云存储):管理 Drive 文件和文件夹,包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、查询权限设置、评论/权限/订阅、标题、版本、飞书文档密级标签(secure labels)和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token、判断链接类型/真实 token/标题,或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用;doubao.com 云空间 URL/token 也按资源路径和 token 路由,不回退 WebFetch。不负责:文档内容编辑(走 lark-doc)、表格/Base 表内数据操作(走 lark-sheets/lark-base)、知识空间节点/成员管理(走 lark-wiki)、原生 Markdown 文件读写/patch/diff(走 lark-markdown)。
lark-base
open.feishu.cn
飞书多维表格(Base)操作:建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式(BaseApp/AppMode 页面与组件)、Workspace 目录、workflow、角色权限、模板中心(多维表格模板分类/列表/搜索);遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps;文件导入/导出转 lark-drive,认证/授权转 lark-shared。
lark-shared
open.feishu.cn
Use for lark-cli setup/auth tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, or handling notice JSON.
lark-im
open.feishu.cn
飞书即时通讯:收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件、管理表情回复、发送应用内/短信/电话加急、发送和处理交互卡片(Interactive Card)、监听卡片按钮回调(card.action.trigger)。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 Feed 置顶(添加/移除/查询置顶会话)、管理标签数据、处理卡片回调时使用。