Fix docs from agent feedback (Oct 19-23)

agent-setup.mdx

@@ -15,7 +15,7 @@ Every command below is safe to re-run on a machine where setup already happened.
 
 ## Install Runpod Skills and MCP server
 
-Every route installs the same skills: the `runpod` router, the lane skills (`runpod-mcp`, `runpodctl`, `flash`, `runpod-usage`, `runpod-templates`, `companion-clis`, `runpod-migrate`), and the journey skills that `runpod-mcp` routes to (`discovery`, `lifecycle-crud`, `serverless-deploy`, `pod-deploy`, `pod-doctor`, `endpoint-ops`, `cost-audit`). It also wires up the hosted Runpod MCP server (`https://mcp.runpod.io/`) for control-plane tools. The skills install the Runpod CLI and Flash SDK later, on demand, the first time a task needs them. Do not install those now.
+Every route installs the same skills: the `runpod` router, the lane skills (`runpod-mcp`, `runpodctl`, `flash`, `runpod-usage`, `runpod-templates`, `runpod-build-template`, `companion-clis`, `runpod-migrate`), and the journey skills that `runpod-mcp` routes to (`discovery`, `lifecycle-crud`, `serverless-deploy`, `pod-deploy`, `pod-doctor`, `endpoint-ops`, `cost-audit`). It also wires up the hosted Runpod MCP server (`https://mcp.runpod.io/`) for control-plane tools. The skills install the Runpod CLI and Flash SDK later, on demand, the first time a task needs them. Do not install those now.
 
 Use the correct section for your agent below.
 
@@ -36,6 +36,8 @@ claude plugin list | grep -A2 'runpod@runpod'
 
 Expect `Status: ✔ enabled`. If the plugin is listed but disabled, run `claude plugin enable runpod@runpod`.
 
+If your agent isn't Claude Code but loads Claude Code plugins from `~/.claude`, run these same two commands.
+
 If `marketplace add` fails with an SSH `known_hosts` error, the machine usually can't reach `github.com` at all (common on networks that block GitHub). Check with `curl -sI https://github.com` before debugging SSH.
 
 > **User step.** Ask the user to run `/reload-plugins` inside Claude Code to activate the plugin, then sign in to the MCP server with `/mcp` → **runpod** → **Sign in with Runpod**. This uses OAuth, so no API key is created or stored. Wait for the user to confirm before reporting the MCP server as connected.
@@ -44,9 +46,11 @@ If `marketplace add` fails with an SSH `known_hosts` error, the machine usually
 
 ## Install for other agents
 
+**Codex:** skip step 1. The Codex plugin in step 2 installs the skills and the MCP server together and doesn't need Node.js.
+
 ### 1. Install the skills
 
-This step needs Node.js 22.20 or newer. Check with `node --version`; if it's older, stop and report it instead of continuing.
+This step needs Node.js 22.20 or newer. Check with `node --version`. If it's older, skip this step and go to [step 2](#2-register-the-mcp-server). The MCP server serves the same playbooks as the skills, so setup still works without them. Tell the user the skills weren't installed because Node.js is too old.
 
 Run the command below, replacing `<agent-id>` with your agent's id from the table. Always pass `--agent`: without it, the installer targets every agent it knows about and prints a `Failed to install` block for agents that don't apply to you.
 
@@ -69,20 +73,27 @@ npx -y skills add runpod/runpod-plugins-official --skill '*' --agent <agent-id>
 | Zed | `zed` |
 | Kilo Code | `kilo` |
 | Amp | `amp` |
+| Grok Build | `grok` |
+
+To find the id for another agent, run the command with an id that doesn't exist, such as `--agent list-ids`. The installer installs nothing and prints every valid id under `Valid agents`. (`npx -y skills add --help` doesn't list them.) If your agent isn't there, use `--agent universal`, which installs into the shared `~/.agents/skills` directory that many agents read. If your agent reads skills only from its own directory, clone `https://github.com/runpod/runpod-plugins-official` and copy each folder under `plugins/runpod/skills/` into that directory.
+
+`--global` installs the skills for your user account. To install them into the current project only, leave out `--global`. The skills then go in the project's `.agents/skills/`, and you verify with `npx -y skills list` without `--global`.
 
-For any other agent, run `npx -y skills add --help` and use the id it lists for your agent.
+On Windows `cmd`, single quotes are passed through literally, so write `--skill "*"`. If the installer still reports `No matching skills found`, run `npx -y skills add runpod/runpod-plugins-official --list` and pass the skill names, comma-separated, to `--skill`.
 
 Verify:
 
 ```
 npx -y skills list --global
 ```
 
-Expect the `runpod` router and the lane and journey skills listed above. If the output also mentions PromptScript or another agent you aren't, ignore it; it doesn't affect your install.
+Expect the `runpod` router and the lane and journey skills listed above. Each skill's folder should contain a `SKILL.md` file. If one is empty, run the install command again. If the output also mentions PromptScript or another agent you aren't, ignore it; it doesn't affect your install.
 
 ### 2. Register the MCP server
 
-Use the section for your agent. Every agent connects to the same hosted server, `https://mcp.runpod.io/`, and signs in with OAuth on first Runpod tool use.
+Use the section for your agent. Every agent connects to the same hosted server, `https://mcp.runpod.io/`, and signs in with OAuth on first Runpod tool use. Older configs and installers may name `https://mcp.getrunpod.io/`: it's the same server under its old name, and it still works. Register only one of them. Each address has its own sign-in, so registering both gives you two separate entries.
+
+Don't open the server URL in a browser to sign in: it's an MCP endpoint, not a web page, and returns HTTP `405`. Sign-in always starts from your agent.
 
 #### Codex
 
@@ -91,12 +102,16 @@ codex plugin marketplace add https://github.com/runpod/runpod-plugins-official.g
 codex plugin add runpod@runpod
 ```
 
-If the `runpod` MCP tools don't appear after install, add the hosted server directly:
+The plugin installs the skills and registers the hosted MCP server. Don't also add the server with `codex mcp add`, or you'll end up with a second entry that needs its own sign-in.
+
+If Codex says `codex plugin add` isn't a command, or reports `plugin not found`, your Codex is too old or has plugins turned off. Update Codex, or check that `features.plugins` isn't set to `false` in `~/.codex/config.toml`, then retry. If you can't install the plugin, install the skills with step 1 (`--agent codex`) and register the server directly:
 
 ```
 codex mcp add runpod --url https://mcp.runpod.io/
 ```
 
+`codex mcp add` opens the OAuth sign-in immediately and waits until the user approves it in the browser. Before you run it, tell the user to expect the browser prompt. With no user present, use an API key instead (see [No user in the loop](#no-user-in-the-loop)).
+
 In Codex Desktop, the user must fully quit and reopen the app before the plugin and MCP tools appear.
 
 #### Gemini CLI
@@ -113,9 +128,28 @@ Gemini can alternatively install natively through the plugin's bundled `gemini-e
 pi mcp add runpod --url https://mcp.runpod.io/
 ```
 
+#### Hermes
+
+```
+hermes config set mcp_servers.runpod.url https://mcp.runpod.io/
+hermes config set mcp_servers.runpod.auth oauth
+```
+
+> **User step.** Ask the user to run `hermes mcp login runpod` and approve the sign-in in the browser. Then check with `hermes mcp test runpod`.
+
+If Hermes gets a `403` error before the browser opens, connect with an API key instead (see [If OAuth sign-in fails](#if-oauth-sign-in-fails)).
+
+#### Grok Build
+
+```
+grok mcp add --transport http runpod https://mcp.runpod.io/
+```
+
+> **User step.** In Grok, the user opens `/mcps`, selects **runpod**, and presses `i` to sign in.
+
 #### Cursor, GitHub Copilot, Windsurf, Cline, opencode, and all other agents
 
-For Cursor, Windsurf, VS Code (GitHub Copilot), opencode, and Claude Desktop, run the installer with your agent's id. It writes the config without prompts:
+For Cursor, Windsurf, VS Code (GitHub Copilot), opencode, Pi, and Claude Desktop, run the installer with your agent's id. It writes the config without prompts:
 
 ```
 npx @runpod/mcp-server@latest add --client <agent-id>
@@ -127,14 +161,57 @@ npx @runpod/mcp-server@latest add --client <agent-id>
 | Windsurf | `windsurf` |
 | VS Code (GitHub Copilot) | `vscode` |
 | opencode | `opencode` |
+| Pi | `pi` |
 | Claude Desktop | `claude-desktop` |
 
-The installer needs Node 20 or later. It exits `0` when every named client was configured, `1` when one failed, and `2` on bad usage. Run `npx @runpod/mcp-server@latest add --list` to see which clients it detects and where each config lives. Always pass `--client`: without it and without a terminal, the installer exits `2` and configures nothing. After it writes the config, it prints the sign-in step for each client (for example, restart Cursor, or run `opencode mcp auth runpod`); do that step or relay it to the user.
+The installer needs Node.js 20.12 or later. It exits `0` when every named client was configured, `1` when one failed, and `2` on bad usage. Run `npx @runpod/mcp-server@latest add --list` to see which clients it detects and where each config lives. Always pass `--client`: without it and without a terminal, the installer exits `2` and configures nothing. After it writes the config, it prints the sign-in step for each client (for example, restart Cursor, or run `opencode mcp auth runpod`); do that step or relay it to the user.
+
+To set up opencode by hand instead, add this to `opencode.json`. Note that opencode uses the `mcp` key, not `mcpServers`, and needs `"type": "remote"`:
+
+```json
+{
+  "mcp": {
+    "runpod": { "type": "remote", "url": "https://mcp.runpod.io/" }
+  }
+}
+```
+
+Then ask the user to run `opencode mcp auth runpod` to sign in. If no browser window opens, the sign-in link is in the opencode log.
+
+For any other agent, such as Cline, add a server entry named `runpod` with the HTTP (streamable HTTP) transport and URL `https://mcp.runpod.io/` to your agent's MCP configuration. Most clients use this shape:
 
-For any other agent, such as Cline, add a server entry named `runpod` with the HTTP (streamable HTTP) transport and URL `https://mcp.runpod.io/` to your agent's MCP configuration. Merge it into the existing file; do not overwrite other servers. See your agent's MCP documentation in [Resources](#resources) for the file location and format.
+```json
+{
+  "mcpServers": {
+    "runpod": { "url": "https://mcp.runpod.io/" }
+  }
+}
+```
+
+Merge it into the existing file; do not overwrite other servers. See your agent's MCP documentation in [Resources](#resources) for the file location and key names.
 
 After registering, the user approves the OAuth sign-in in the browser the first time you call a Runpod tool.
 
+#### If OAuth sign-in fails
+
+OAuth sign-in works in Claude, ChatGPT, Codex, and Cursor, and in any client that receives the sign-in on a local address (`http://localhost` or `http://127.0.0.1`). Other clients may fail with `redirect_uri is not allowed`, or get a `403` error before the browser opens. If that happens, connect with an API key instead, even when a user is present:
+
+1. Ask the user to create a key on the [Credentials page](https://console.runpod.io/user/settings) and set it as `RUNPOD_API_KEY` in the environment your agent starts from.
+2. Send it as a header on the server entry, for example:
+
+   ```json
+   {
+     "mcpServers": {
+       "runpod": {
+         "url": "https://mcp.runpod.io/",
+         "headers": { "Authorization": "Bearer ${RUNPOD_API_KEY}" }
+       }
+     }
+   }
+   ```
+
+   `${RUNPOD_API_KEY}` reads the key from the environment, but clients write this differently, so check your client's docs. If your client can't read environment variables, run the server locally instead, with `RUNPOD_API_KEY` set: `npx -y @runpod/mcp-server@latest`.
+
 If your agent can't load skills, the MCP server serves the same playbooks: `list-guides` and `read-guide` return them, and `lookup-concept` and `search-concepts` answer questions about how Runpod works.
 
 ---
@@ -143,15 +220,15 @@ If your agent can't load skills, the MCP server serves the same playbooks: `list
 
 When no user is present (CI, a scheduled job, an agent SDK run), nobody can do the **User steps** or the OAuth sign-in. Use a Runpod API key instead:
 
-1. Read the key from the `RUNPOD_API_KEY` environment variable. The `runpodctl` CLI and the Flash SDK read the same variable. Do not ask for the key, print it, or write it to a file. If it is not set, stop and report that it is missing.
+1. Read the key from the `RUNPOD_API_KEY` environment variable. The `runpodctl` CLI and the Flash SDK read the same variable. Do not ask for the key, print it, or write it to a file. If it is not set, stop and report that it is missing. The variable must be set in the environment the agent starts from, for example as a CI secret, in a service unit, or in a shell profile. Clients that store only the variable's name, such as `pi mcp add --bearer-token-env-var RUNPOD_API_KEY`, read the key from there each time they start.
 2. Install the skills for your agent as above. Skip `/reload-plugins`: the plugin loads the next time the agent starts.
 3. Connect the hosted MCP server with the key instead of OAuth:
 
    ```
    claude mcp add --transport http runpod -s user https://mcp.runpod.io/ --header "Authorization: Bearer $RUNPOD_API_KEY"
    ```
 
-   For other clients, add the same `Authorization` header to the server entry (for Gemini CLI: `gemini mcp add -s user -t http -H "Authorization: Bearer $RUNPOD_API_KEY" runpod https://mcp.runpod.io/`), or run the server locally over stdio with `RUNPOD_API_KEY` set: `npx -y @runpod/mcp-server@latest`.
+   For other clients, add the same `Authorization` header to the server entry, as in the JSON under [If OAuth sign-in fails](#if-oauth-sign-in-fails). For Gemini CLI, run `gemini mcp add -s user -t http -H "Authorization: Bearer $RUNPOD_API_KEY" runpod https://mcp.runpod.io/`. You can also run the server locally with `RUNPOD_API_KEY` set: `npx -y @runpod/mcp-server@latest`.
 4. In headless Claude Code (`claude -p`), allow the Runpod skill and the MCP tools your task needs up front, for example `--allowedTools "Skill(runpod:runpod-mcp)"`. Without `Skill(runpod:runpod-mcp)`, the `runpod-mcp` skill is refused.
 5. Write the result banner below to your log. Mark anything that still needs a person with `✗`.
 

api-reference-v2/openapi.json

@@ -2680,7 +2680,7 @@
             ]
           },
           "direct": {
-            "description": "Connection straight to the pod's sshd over its published `22/tcp` mapping. Supports the full SSH feature set. Null unless `22/tcp` is in `ports` and the running pod has been assigned a public port for it — so it is absent while the pod is provisioning or stopped. Also null when listing pods with `GET /v2/pods`; fetch a single pod by ID to obtain the live mapping.",
+            "description": "Connection straight to the pod's sshd over its published `22/tcp` mapping. Supports the full SSH feature set. Null unless `22/tcp` is in `ports` and the running pod has been assigned a public port for it — so it is usually absent while the pod is provisioning or stopped. It can still appear on a stopped pod, so check that `status` is `RUNNING` before connecting. Also null when listing pods with `GET /v2/pods`; fetch a single pod by ID to obtain the live mapping.",
             "anyOf": [
               {
                 "$ref": "#/components/schemas/PodSshEndpoint"
@@ -2974,7 +2974,7 @@
               "cost": {
                 "type": "number",
                 "format": "float",
-                "description": "Current cost in USD per hour (0.0 when EXITED or TERMINATED)",
+                "description": "The Pod's hourly compute rate in USD. It's returned in every status, including `EXITED`, so it isn't what you're paying right now: a stopped Pod isn't billed for compute, only for its volume disk.",
                 "examples": [
                   0.35
                 ]
@@ -3031,7 +3031,7 @@
             "required": [
               "name"
             ],
-            "description": "Request body for creating a pod. Exactly one of `gpu` or `cpu`\nmust be set — enforced at the handler layer. For CPU pods, memory\nis derived by the API from the selected flavor's RAM multiplier;\nclients provide only CPU flavor and vCPU count. CPU pods support\ncontainer disk and network volumes only; `mounts.persistent` is\ninvalid when `cpu` is set.\n\n`image` is required unless `templateId` is set.\n",
+            "description": "Request body for creating a pod. Exactly one of `gpu` or `cpu`\nmust be set — enforced at the handler layer. For CPU pods, memory\nis derived by the API from the selected flavor's RAM multiplier;\nclients provide only CPU flavor and vCPU count. CPU pods support\ncontainer disk, network volumes, and a global volume; `mounts.persistent`\nis invalid when `cpu` is set.\n\n`image` is required unless `templateId` is set.\n",
             "properties": {
               "name": {
                 "type": "string",
@@ -5716,9 +5716,9 @@
       },
       "RateLimitPolicyHeader": {
         "type": "string",
-        "description": "Static per-window quota policy. Optional — omitted for rate-limit-exempt\ncallers.\n\nA structured-field list with one member per window (`minute`, `hour`,\n`day`), each carrying the quota `q` and the window length in seconds `w`.\nReturned on responses to authenticated requests, not only on 429s.\n",
+        "description": "Static per-window quota policy. Optional — omitted for rate-limit-exempt\ncallers.\n\nA structured-field list with one member per window (`minute`, `hour`,\n`day`), each carrying the quota `q` and the window length in seconds `w`.\nReturned on responses to authenticated requests, not only on 429s.\n\nLimits are per user, and every `/v2` route counts toward the same\nlimits; creating pods has no separate limit. Read the current quotas from\nthis header instead of hard-coding them, because they can change and some\naccounts have higher limits. A 429 only slows you down: wait for the\n`Retry-After` time and retry. Your account isn't suspended.\n",
         "examples": [
-          "\"minute\";q=60;w=60, \"hour\";q=3000;w=3600, \"day\";q=50000;w=86400"
+          "\"minute\";q=180;w=60, \"hour\";q=3600;w=3600, \"day\";q=43200;w=86400"
         ]
       }
     }

get-started.mdx

@@ -59,6 +59,8 @@ You can also click **Pods** in the left sidebar.
 
     Use the search box, **Network volume** filter, **Filter** button, or **Sort by** dropdown to narrow the list. Click **Compare GPUs** to ask the Runpod assistant for a comparison of the selected GPUs.
 
+    To choose between Secure Cloud and Community Cloud, click **Filter** and set **Cloud type** to **Secure** or **Community**. Organization accounts can deploy only to Secure Cloud, so the option isn't shown for them.
+
     The **Network volume** filter narrows the GPU list to compatible GPUs by filtering for GPUs that are in the same data center as the selected network volume. Select any network volume, and GPU availability updates to match it. GPUs that aren't compatible with the selected volume move to the incompatible section of the **All** tab.
 
     If the GPU you want shows **Out of capacity**, you can still select it and deploy it once capacity frees up. Selecting an out-of-capacity GPU changes the final [Deploy](#deploy) step: instead of deploying right away, you can subscribe to deploy when the GPU becomes available.