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, that bundles a router skill, the lane skills it routes to, the MCP journey skills, 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.

For AI agents: setup instructions for the Runpod skills and MCP server are at https://agents.runpod.io/

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 skills (the router, the lanes and the MCP journey skills), 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 plugin add runpod@runpod   # or: codex /plugins → "Runpod" marketplace tab → Install

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 --url https://mcp.runpod.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.runpod.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.

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/                         concept graph tooling: validator, bundle, SQLite, graph page
hooks/                            marketplace, branding & link validation

Contributing

See CONTRIBUTING.md. For the reproducible dev environment and the static-analysis gate (ruff, mypy, bandit, shellcheck, shfmt, biome, nixfmt, deadnix, statix — run with nix flake check), see the Nix flake guide.

License

Apache-2.0