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:

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:

Uninstall

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

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.

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.

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