runpod

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Runpod (router)

Runpod（路由入口）

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

SKILL.md

next.

这是Runpod技能的入口。该技能本身不执行具体工作——它会选择合适的路径并转交任务。接下来请阅读对应技能的

SKILL.md

文档。

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, `send` / `receive` file transfer, SSH keys, `doctor` setup, 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-mcp	通过结构化工具调用管理基础设施（Pod、端点、任务、模板、卷、注册表、资源目录、账单）——适用于当前会话已连接Runpod MCP工具的场景。
runpodctl	通过终端/CI/脚本管理上述基础设施，还支持仅CLI具备的功能：Hub浏览/部署、 `send` / `receive` 文件传输、SSH密钥、 `doctor` 环境检测、模型缓存。
flash	编写可在Runpod无服务器环境运行的Python代码—— `@remote` / `@Endpoint` 函数、 `flash dev` 热重载、 `flash deploy` 。以代码为核心，不涉及基础设施管理。
companion-clis	生成前置依赖产物：下载模型（ `hf` ）、构建/推送镜像（ `docker` ）、仓库/版本发布（ `gh` ）、通过S3将数据迁移至网络卷（ `aws` ）。
runpod-usage	在操作前了解Runpod的工作机制——Pod与无服务器的区别、容器构建、存储、GPU选择、常见陷阱。仅提供知识类内容。

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:

RUNPOD_API_KEY

env →

.env

→

~/.runpod/config.toml

bash

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 (Hub,

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

基础设施任务（Pod、端点、任务、卷）需要可用的控制平面——Runpod MCP或runpodctl。不要在任务执行中途才发现未配置环境：请先检查，若未配置，协助用户完成设置，而非依赖部分降级方案继续。

检查方式（凭证优先级：

RUNPOD_API_KEY

环境变量 →

.env

文件 →

~/.runpod/config.toml

）：

bash

runpodctl user            # 执行成功 ⇒ 已设置有效密钥

此外，在Claude Code中，

/mcp

应显示

runpod

已Connected（已连接）。

规则：优先获取密钥——不要默认使用MCP OAuth。 原因：单个

RUNPOD_API_KEY

可解锁所有工具——它能认证runpodctl + flash + 托管MCP（通过

--header "Authorization: Bearer $RUNPOD_API_KEY"

）。MCP的“通过Runpod登录”OAuth仅能认证MCP本身——CLI工具仍会被限制，因此在执行任何仅CLI支持的任务（Hub操作、

send

receive

、SSH、

doctor

、模型缓存/模型仓库、CPU端点）时会受阻。⚠️ 仅OAuth是不完整的配置。若未配置任何环境，请按以下顺序获取密钥：

flash login
—— 浏览器OAuth登录，将真实密钥保存至
```
~/.runpod/config.toml
```
（runpodctl和flash均可读取；可复用为MCP的Bearer凭证）。一步完成，解锁所有工具。仅适用于人工操作。
export RUNPOD_API_KEY=…
（获取地址：https://console.runpod.io/user/settings）—— 同样可解锁所有工具；最适合无头Agent场景。
仅MCP OAuth（
```
/mcp
```
→ Sign in登录）—— 最后选择，仅支持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

。

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,
  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.

概念性问题，或未确定的设计选择（无服务器还是Pod？选哪种GPU？将模型打包进镜像还是挂载卷？）→ 先查看runpod-usage，再继续解答。
在Runpod GPU上编写/迭代/发布自定义代码 → 使用flash。
生成依赖产物（下载模型、构建+推送镜像、创建仓库版本、将数据同步至卷）→ 使用companion-clis。
管理基础设施（创建/列出/更新/删除Pod、端点、模板、卷；列出GPU/数据中心；运行无服务器任务；账单管理）：
- 仅CLI具备的功能——Hub操作、
```
send
```
  /
```
receive
```
  文件传输、SSH密钥、
```
doctor
```
  环境检测、模型缓存 → 使用runpodctl。
- 其他场景，若当前会话已连接Runpod MCP工具（
```
create-pod
```
  、
```
list-endpoints
```
  等工具可用）→ 使用runpod-mcp。
- 其他场景（仅支持Shell的Agent，无MCP）→ 使用runpodctl。

runpod-mcp vs runpodctl (the overlap)

runpod-mcp vs runpodctl（功能重叠部分）

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
Deploy from the Hub	runpod-mcp if connected, else runpodctl	MCP has `list-hub-repos` + `deploy-hub-repo`
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	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.

两者均调用同一Runpod API，因此在基础设施CRUD操作上存在重叠。选择时优先看功能，再看运行环境：

MCP在便捷性上更优：适用于简单的结构化操作——查询和基础CRUD——当工具已连接时（类型化参数，无需Shell转义）。
runpodctl接管MCP不支持的操作——即使MCP已连接——且是仅Shell Agent或用户需要可复现命令时的唯一选择。

功能矩阵（按操作选择优先路径）：

操作	优先路径	原因
列出/查询任何资源；启动/停止/重启/删除Pod；端点、模板、卷、注册表、资源目录、账单的基础CRUD	已连接则选runpod-mcp，否则选runpodctl	简单结构化操作——MCP支持类型化参数，使用便捷
创建简单Pod（单个镜像+单个GPU）	已连接则选runpod-mcp，否则选runpodctl	两者均支持
从模板创建Pod或创建CPUPod	已连接则选runpod-mcp，否则选runpodctl	MCP的create-pod支持 `templateId` （仅v2版本）和 `computeType: "CPU"` 参数
创建带有多GPU优先级列表的Pod，或同时使用模板+CPU	runpodctl	MCP仅支持单一GPU类型，且拒绝为CPU Pod使用模板部署
从Hub部署	已连接则选runpod-mcp，否则选runpodctl	MCP支持 `list-hub-repos` + `deploy-hub-repo` 工具
文件传输（ `send` / `receive` ）、SSH密钥/信息、 `doctor` 环境检测、模型缓存	runpodctl	MCP无对应工具
调用无服务器任务（ `run` / `runsync` /状态查询/流式输出）	已连接则选runpod-mcp，否则选runpodctl	MCP具备原生任务工具

经验法则：简单操作默认使用MCP，一旦操作需要MCP未暴露的参数/功能，立即切换至runpodctl。

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
```
(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).

对于任何“在Runpod上运行<X>”的任务，请遵循

runpod-usage/reference/development-loop.md

中的开发流程：确定使用Pod还是无服务器 → 资源配置 → 环境搭建（仅从零开始时需要）→ 验证 → 交付 → 成本管控 + 资源销毁。流程中需遵循两条规则：

优先使用预构建模板/Hub工作负载，而非从零开始构建镜像。
交付前，通过Pod/端点外部的真实请求验证工作负载——“Running”/“ready”状态不代表服务已正常提供。

流程分为两个子流程：

对外提供URL访问的服务（Ollama、ComfyUI、开发环境）→
```
runpod-usage/reference/pod-workflows.md
```
创建时配置端口+环境变量+卷、通过SSH执行安装、绑定
```
0.0.0.0
```
、轮询代理URL。使用runpodctl路径执行。
支持请求/响应、可缩容至零的API（Whisper、推理服务）→
```
runpod-usage/reference/endpoint-workflows.md
```
Hub工作负载 vs flash vs 自定义镜像；调用
```
/run
```
/
```
/runsync
```
；轮询任务状态。

Worked examples (golden paths)

实践示例（最佳路径）

Two dozen end-to-end scenarios (nearly all live-verified) live in

./golden-paths/README.md

— 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 ( `--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
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 ( `/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

共24个端到端场景（几乎均经过实时验证），存放在

./golden-paths/README.md

中——这是“Agent能否完成任务”的衡量标准，包含可直接复制的真实命令和观测输出。当任务与某示例匹配时，请优先查看对应的最佳路径，而非重新推导：

想要…	最佳路径
在Pod上运行可通过URL访问的服务（Ollama/ComfyUI）	01, 02
部署无服务器模型端点（Hub / flash / 自定义镜像）	03, 05
无需打包进镜像或挂载卷即可运行HuggingFace模型（主机缓存）	20 — 模型缓存（ `--model-reference` ）
调用已部署的托管模型（无需自行部署）	11 — 公共端点
微调模型并提供服务	04, 08
交互式开发环境（SSH / VS Code）	06
数据迁移：Pod → 卷 → 无服务器	07
flash不足以满足需求时的自定义无服务器开发（双模式镜像开发流程）	09
为目标环境构建最小镜像（Pod vs 无服务器队列）	22（Pod）, 23（队列）; 相关概念见building-images
决定将内容打包进镜像还是挂载到网络卷	25 — 打包vs挂载
高可用/多区域无服务器（多卷+数据同步）	10, 19（三区域）
增量流式输出（ `/stream` ）	12
调优自动扩缩容 / 提升单Worker吞吐量	13（自动扩缩容）, 18（并发处理）
负载均衡 / HTTP服务器或WebSocket Worker	14（负载均衡）, 17（WebSocket）
任务完成时接收通知（推送而非轮询）	16 — WebHook
检查健康状态 / 调试故障端点	15 — 监控与调试

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.

执行顺序始终为了解需求 → 生成依赖产物 → 管理基础设施 → 验证，因为基础设施只能引用已存在的产物。每个步骤使用单一路径，在凭证边界处切换路径。

示例——“将

openai/gpt-oss-20b

部署为无服务器端点”：

runpod-usage —— 确定使用无服务器还是Pod、20B模型对应的GPU层级、打包vs挂载vs缓存。

companion-clis ——

hf download …

docker build --platform=linux/amd64 …

docker push

。

runpod-mcp或runpodctl —— 创建引用该镜像+GPU池的端点。
使用同一基础设施路径 —— 调用端点/检查状态以验证。

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.

所有工具共用一个密钥：RUNPOD_API_KEY
（获取地址：https://console.runpod.io/user/settings）。每个路径只需确保该密钥可被解析——`runpodctl doctor

、

flash login

、MCP标准输入输出环境变量，或MCP托管的“通过Runpod登录”（OAuth，密钥不存储在本地）。配套CLI工具使用各自的凭证（HuggingFace令牌、GitHub认证、Docker Hub PAT、Runpod **S3**密钥用于

aws

）——请勿将

RUNPOD_API_KEY`复用至这些工具。