Runpod Official Plugins

The official plugin marketplace of skills for AI agents to manage GPU workloads on Runpod — pods, serverless endpoints, jobs, templates, and volumes — via the Runpod MCP server, runpodctl, and flash.

This repo ships one plugin, runpod, with eight skills total: one router plus seven lanes, the hosted Runpod MCP server config, worked golden paths, and a concept graph of how Runpod works. You install and use it as a plugin, exactly as below; the npm package described under Also on npm is an extra way for programs to read the same content.

Compatibility: installs as a native plugin in Claude Code, Codex, Gemini, and opencode (with auto-update), and as skills via skills.sh for Cursor, Copilot, Windsurf, Cline, and 17+ other agents — all from the same manifest.

Quick start

Install — works with every agent (Claude Code, Codex, Cursor, Copilot, Windsurf, Cline, Gemini, opencode, +more). The first line is all you need; drop any others you won't use:

npx skills add runpod/runpod-plugins-official # the skills — any agent (essential)
curl -sSL https://cli.runpod.net | bash       # runpodctl — infra CLI (or: brew install runpod/runpodctl/runpodctl)
uv tool install runpod-flash                  # flash — deploy your own code (optional; or: pip install runpod-flash)
npx @runpod/mcp-server@latest add            # hosted MCP server — guided setup, OAuth (optional)

Then authenticate — one API key covers everything (from the console):

export RUNPOD_API_KEY=<key>      # current shell only — add to ~/.zshrc (or ~/.bashrc) to persist
# or, to save it permanently:
runpodctl doctor                 # prompts for the key and writes ~/.runpod/config.toml

Now just ask in plain English — the skill drives the tools for you:

"list my Runpod endpoints" · "spin up an A100 pod" · "deploy this handler to serverless"

That's it. Notes:

• Claude Code can install natively instead (auto-wires the hosted MCP server + OAuth) — see Install → Claude Code. MCP auth details: Authentication.
• Companion CLIs (docker/gh/hf/aws) install separately, per task — see companion-clis.

Install

Same repo, one manifest — pick your agent below. Every route installs the same eight skills (one router plus seven lanes), plus a hosted Runpod MCP server for control-plane tools. Then authenticate.

Claude Code

/plugin marketplace add runpod/runpod-plugins-official
/plugin install runpod@runpod
/reload-plugins

Installing also wires up the hosted Runpod MCP server (via the bundled .mcp.json) — no separate MCP setup. Authenticate it: /mcp → runpod → Sign in with Runpod (OAuth; no key on disk).

Verify: /plugin shows Runpod under Installed; then ask "list my Runpod endpoints" — it should call the MCP list-endpoints tool.

Codex

codex plugin marketplace add https://github.com/runpod/runpod-plugins-official.git
codex /plugins        # → open the "Runpod" marketplace tab → Runpod → Install (reload if prompted)

Manage the source: codex plugin marketplace list · … upgrade runpod · … remove runpod.

Codex may not auto-wire the bundled MCP — if the runpod MCP tools don't appear after install, add the hosted server manually:

codex mcp add runpod --transport http https://mcp.getrunpod.io/

Verify: ask a Runpod task (the skill/router should answer); once the MCP is added, "list my Runpod endpoints" should call a tool.

Everything else — Cursor, Copilot, Windsurf, Cline, opencode, Gemini (+17)

Install the skills via skills.sh (reads the same .claude-plugin/marketplace.json):

npx skills add runpod/runpod-plugins-official
# just one skill:
npx skills add https://github.com/runpod/runpod-plugins-official/tree/main/plugins/runpod/skills/runpodctl

Gemini can also install natively via the bundled gemini-extension.json (see your client's extension docs). For these clients, add the MCP server yourself — the guided installer configures most agents:

npx @runpod/mcp-server@latest add     # detects your agent + sets up the hosted MCP (OAuth)

See runpod-mcp/SKILL.md for hosted vs local (stdio) MCP setup and all client options.

Authentication

Auth is needed in two places, and one Runpod API key covers both:

| What | What it needs | How | | --- | --- | --- | | runpodctl + flash (the CLIs) | RUNPOD_API_KEY (env or saved) | export RUNPOD_API_KEY=<key>, or runpodctl doctor to save it | | Hosted Runpod MCP server (infra tools) | OAuth or the same key | /mcp sign-in, or pass the key as a Bearer header |

Fastest path — one key, everything:

1. Get an API key: Runpod console → Settings → API Keys.
2. Make it available to the CLIs (runpodctl, flash) — either way works:

   export RUNPOD_API_KEY=<key>   # this shell only; add to ~/.zshrc / ~/.bashrc to persist
   runpodctl doctor              # OR: prompts once and saves to ~/.runpod/config.toml (persistent)
   

3. Authenticate the MCP server — pick one:
   • OAuth (easiest, no key on disk): in Claude Code, /mcp → runpod → Sign in with Runpod.
   • Reuse the key you just set:

     claude mcp add --transport http runpod -s user https://mcp.getrunpod.io/ \
       --header "Authorization: Bearer $RUNPOD_API_KEY"
     

Codex and local-stdio MCP variants are in runpod-mcp. Companion CLIs (hf, docker, gh, aws) use their own credentials — see companion-clis. If nothing is set up, the runpod skill detects it and walks you through this.

Updating

The plugin is versioned: updates arrive when we cut a release (a version bump, see the CHANGELOG). Claude Code pulls the new version in the background; if it hasn't picked it up yet, force it manually:

| Client | Update command | | --- | --- | | Claude Code | /plugin marketplace update runpod then /reload-plugins | | Codex | codex plugin marketplace upgrade runpod | | skills.sh | re-run npx skills add runpod/runpod-plugins-official |

Uninstall

Remove the plugin (and, where applicable, the marketplace it came from):

| Client | Uninstall | | --- | --- | | Claude Code | /plugin uninstall runpod@runpod, then /plugin marketplace remove runpod | | Codex | codex plugin marketplace remove runpod | | skills.sh | npx skills remove runpod |

If a command reports a name mismatch, list what's installed first — /plugin marketplace list (Claude Code) · codex plugin marketplace list (Codex) · npx skills list (skills.sh) — and use the name shown. Removing the marketplace also drops the bundled hosted-MCP registration it added; if you configured the MCP separately, remove that too (Claude Code: claude mcp remove runpod).

What's inside

Start with the runpod router; it points at the right lane.

| Skill | Use it for | | --- | --- | | runpod | Router / entrypoint. Start here when the right skill is unclear. | | runpod-mcp | Manage infra via the Runpod MCP server's structured tool calls. | | runpodctl | Manage infra from the CLI, plus Hub, file transfer, SSH, doctor. | | flash | Write and deploy your own code on Runpod serverless (@remote). | | companion-clis | Prerequisite CLIs: hf, docker, gh, aws. | | runpod-usage | Concepts — pods/serverless, containers, storage, GPU selection, gotchas. | | runpod-templates | Official pod templates — what each image ships, ports/paths, readiness, gotchas. | | runpod-migrate | Migrate code from the GraphQL API or REST v1 to REST v2. |

See the plugin's README for the full guide, the development loop, and setup. Worked end-to-end examples live in plugins/runpod/skills/runpod/golden-paths/.

Concept graph. runpod-usage/concepts/ holds one YAML file per Runpod concept (pod, network volume, machine, worker, …), with rules that each cite a public source. Every skill, reference doc and golden path lists the concepts it covers, so an agent can go from a question to the exact rule and to a verified example that uses it.

| To | Read | | --- | --- | | Browse, query, validate or serve the graph | ontology/README.md | | Understand the concept file format | concepts/README.md | | Add or change a concept | add-concept skill | | Add or change a skill, reference doc or golden path | write-guide skill | | Tag a golden path with lanes, MCP coverage and concepts | golden-paths/README.md |

Also on npm

Every release also publishes @runpod/plugin-knowledge: all the skills, reference docs, golden paths and concepts as one JSON file, at the plugin's version. It is for programs, not for installing the plugin. The Runpod MCP server can depend on it to serve the same guides and concepts to agents that don't have the plugin. Nothing changes for plugin or skills.sh users.

Ask for it by name

Plain English works for one-off actions. For anything you're designing, add one clause — "and look at the examples first":

• "Use the Runpod plugin skills and look at the examples. I want to build a speech translator: audio in, translated text out. Plan it out."
• "Use the runpod-migrate skill to move this repo from GraphQL to REST v2. Show me the inventory before you change anything."
• "Use the Runpod skills to repair the missing model links in this ComfyUI workflow, then download the approved files to my Pod."
• "Use the Runpod skills and check the examples — deploy this handler to serverless."
• "Use the Runpod skills — cheapest GPU that fits a 13B model?"
• "Use the Runpod skills and check the examples — my endpoint returns IN_QUEUE forever."

You don't need to know which example applies; the agent picks. Worth adding either way: "show me the plan before you change anything" and "verify it with a real request" ("Running" is not "ready").

Why the extra clause helps. Skills auto-load from their description, but the golden paths deliberately have no SKILL.md, so agents never load them on their own — and each skill's reference/*.md opens only on demand. Asking is what pulls them in, and they're where the commands that were actually run against a real account live.

Repository layout

.claude-plugin/marketplace.json   Claude Code / skills.sh marketplace manifest
.agents/plugins/marketplace.json  Codex marketplace manifest
plugins/runpod/                   the plugin (skills/ incl. runpod/golden-paths/ and
                                  runpod-usage/concepts/, .mcp.json, manifests)
packages/knowledge/               @runpod/plugin-knowledge, the npm package built from the plugin
ontology/