[lavanya-gunreddi]

Summary

Adds a new page, Connect a coding agent to a Pod (pods/configuration/ssh-agents.mdx), and adds it to the Pods navigation in docs.json.

Resolves DOCS-438: a user and Claude Code couldn't connect to a Pod over SSH because port 22 wasn't exposed.

What the page covers

• Running Claude Code and Codex on a Pod over basic SSH (no port 22 or public IP needed).
• Keeping agents installed across Pod restarts by putting HOME on /workspace.
• Install and login steps for each agent, including the PATH fix for claude and codex login --device-auth.
• Connecting Cursor over Remote-SSH, which needs TCP port 22 and a public IP.
• Troubleshooting: permission denied, connection refused, port and IP changes after a restart.

Reviews addressed

• Henrik's doc review and live test (11 Sep).
• OneAsterisk's inline review comments.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
runpod-docs	🟢 Ready	View Preview	Oct 21, 2026, 10:10 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[OneAsterisk]

Looks good!

[OneAsterisk]

Claude review, round 1

Verdict: Ready after fixes — the page is a useful consolidation, but its "fix a Pod that lacks port 22" instructions send readers to edit the template, which does not change an already-deployed Pod; the rest of the repo documents Edit Pod for this.
Approval gate: 0 Critical, 1 High, 7 Medium+Low → not approved: one High (wrong recovery path, repeated three times).

Existing feedback

• @OneAsterisk approved at bbb9e3a ("Looks good!"); GitHub dismissed it on the 4f6072c push. No claims to verify.
• Mintlify vale-spellcheck (neutral, 18 suggestions): 11 are real Google-style hits, listed under Nits; 7 are false positives against repo conventions (## Step N: headings, "Claude Code", the Connect UI label, "Community Cloud", the env-var heading). https://github.com/runpod/docs/runs/102988429847
• mintlify[bot] preview deploy: renders with the correct title.

PR description vs code

The PR body is empty, so there are no claims to check. See Low below.

Findings

High

• Template edits do not fix a Pod that was deployed without port 22 — pods/configuration/ssh-agents.mdx:17, repeated at :115 and :123. The page says to stop the Pod, add 22 to the template, and restart. A template change applies to new deployments; the existing Pod keeps the ports it was created with. The repo's documented path for an existing Pod is Edit Pod → TCP ports (pods/manage-pods.mdx:172-187, pods/configuration/expose-ports.mdx:28, community-solutions/ohmyrunpod/overview.mdx:119). The claim "You cannot expose TCP port 22 while the Pod is running" also conflicts with manage-pods.mdx:177, which says editing a running Pod is allowed and resets it, erasing data outside /workspace or a network volume. Fix: replace all three passages with the Edit Pod flow plus that data-loss warning, linking /pods/manage-pods#update-a-pod.

Medium

• Step 1 routes official-template users through Duplicate, but official templates already expose SSH — :30-32 vs :48. use-ssh.mdx:112 and connect-to-ide.mdx:68 say official templates ship with full SSH over exposed TCP, and the deploy flow has an SSH terminal access toggle for them (get-started.mdx:51). A reader on Runpod PyTorch will duplicate a template for nothing. Fix: say official templates already expose 22 (check Direct TCP Ports) and reserve the Duplicate flow for community or Hub templates that lack it. No other page documents a Duplicate action; please confirm the label.
• Cursor steps conflict with the adjacent IDE page — :76-82. This page says choose Remote-SSH: Connect to Host and enter the ssh command. connect-to-ide.mdx:117-127 says that in Cursor this opens the SSH config file and you add a Host block; the ssh-command shortcut is documented only for VS Code (:91-92). Two neighbouring pages now disagree. Fix: link to /pods/configuration/connect-to-ide#step-4-configure-ssh-for-your-ide instead of duplicating the steps.
• Reconnect troubleshooting covers IP changes but not port changes — :125-127. expose-ports.mdx:96 says external port mappings change whenever a Pod resets, on every cloud type, and connect-to-ide.mdx:168 says the same. An agent that loses its session after a stop/start sees "Connection refused", and this page's entry for that (:115) sends the reader to the template. Fix: rename the entry "Pod IP address or port changed" and tell readers to re-copy both from Direct TCP Ports.

Low

• RUNPOD_TCP_PORT_22 … missing entry does not belong to this flow — :121-123. That message is printed by the password-SSH helper script (use-ssh.mdx:197-199); nothing on this page runs it. Drop the entry or say where the message comes from.
• Requirements link lands on a page that only links onward — :11. On main, use-ssh.mdx:19-21 no longer contains key-generation steps and points to /get-started/credentials#ssh-public-keys. Link there directly. Same at :50: the Docker start command lives under #full-ssh-via-public-ip-with-key-authentication; add the anchor.
• Next steps as bullets — :129-133. Both style files require CardGroup with horizontal cards for Next steps (.cursor/rules/rp-styleguide.mdc:26-36, .claude/style-guide.md:98-108). The repo is mixed (11 CardGroup pages, 15 bullet pages on main), so this is the written rule rather than universal practice.
• Empty PR description — add one line on what the page is for and the Linear ticket the branch name (docs438) refers to, so reviewers and future readers have context.

Nits

• :4 description names Claude Code and Cursor; the page also covers Codex.
• :21 "two ways" is followed by three options.
• :25 link the console URL (https://www.console.runpod.io/user/templates, as expose-ports.mdx:30 does) instead of backticks.
• :26, :32 repo wording is "three-dot menu" (manage-pods.mdx:185, pods/storage/types.mdx:64), not ⋮.
• :56 Claude Code can also run locally; "In this setup, Claude Code runs on the Pod" is accurate.
• :115 link "web terminal" to /pods/connect-to-a-pod#web-terminal.
• Vale (real hits): avoid "will" (:38, :44); active voice (:32, :48, :115); contractions (:32, :36, :115); Oxford comma (:56); "preceding" rather than "above" (:32).

Simplification opportunities

1. Replace the three identical ssh root@… blocks (:60-62, :80-82, :90-92) with one "Connect over SSH" step before Step 3, keeping per-agent sections to install commands only. About 15 lines removed; same PR.
2. Replace the Cursor section with a link to connect-to-ide (Medium above). About 6 lines removed; same PR.

Verified clean

• docs.json entry sits after use-ssh in Connect to Pods; the group is unchanged on main at the same position, and GitHub reports the PR mergeable.
• Frontmatter has title, sidebarTitle, description; ## Step N: headings and a Requirements section follow the style guide.
• /pods/configuration/use-ssh#troubleshooting-ssh-key-authentication still exists on main (use-ssh.mdx:126) after that page's recent rewrite; the expose-ports and connect-to-ide targets exist.
• Both installer URLs return 200: claude.ai/install.sh is Anthropic's native installer, chatgpt.com/codex/install.sh is OpenAI's (fetches from releases.openai.com/codex).
• Preview deploy renders with the right title; link-rot and tooltip-import checks pass; every code block has a language identifier.
• "Official templates start sshd" (:48) matches use-ssh.mdx:112; service ssh status matches the service ssh start the repo uses; the Community Cloud IP note matches expose-ports.mdx:94.

Questions for the author

• Is Duplicate the actual menu label for Hub templates in the console? No other page documents it.
• Did you verify that Cursor's Remote-SSH: Connect to Host accepts a raw ssh … command? The IDE page says it opens the config file.

---

_{Reviewed by Claude (claude-fable-5-1) via the pr-review skill. Tokens: 706 in / 30,804 out / 1,711,845 cache read / 111,850 cache write = 1,855,205. Estimated cost: $4.21 at $10/$50 per MTok in/out, $0.25 cache read, $20 cache write (1-hour TTL, 2× input), rate card from the bundled claude-api skill 2.1.288. Round 1 of this PR. This is automated assistance; a human owns the final call.}

[OneAsterisk]

Claude review, round 2

Verdict: Approved — every round 1 finding is fixed at ac4a8ec0; one Low (empty PR description) remains.
Approval gate: 0 Critical, 0 High, 1 Medium+Low → approved.

Status of prior findings

#	Finding	Severity	Status	Evidence
R1-1	Template edit does not fix a deployed Pod missing port 22	High	Fixed	ssh-agents.mdx:17 now uses Edit Pod with the reset warning and links /pods/manage-pods#update-a-pod; :113 points to it; the :115 and :123 passages are gone. ac4a8ec
R1-2	Official-template users routed through Duplicate	Medium	Fixed	:21 says official templates already expose 22; :32-34 limits Duplicate to community or Hub templates. ac4a8ec
R1-3	Cursor steps conflict with connect-to-ide	Medium	Fixed	:80 links connect-to-ide#step-4-configure-ssh-for-your-ide (heading exists on main, line 72). ac4a8ec
R1-4	Reconnect entry covered IP but not port	Medium	Fixed	:119-121 "Pod IP address or port changed". ac4a8ec
R1-5	RUNPOD_TCP_PORT_22 entry not part of this flow	Low	Fixed	Entry removed. ac4a8ec
R1-6	Requirements and Docker-command links	Low	Fixed	:11 links /get-started/credentials#ssh-public-keys; :52 adds the #full-ssh-via-public-ip-with-key-authentication anchor. Both headings exist on main. ac4a8ec
R1-7	Next steps as bullets	Low	Fixed	:125-135 uses CardGroup with horizontal cards. ac4a8ec
R1-8	Empty PR description	Low	Not addressed	PR body is still empty.
R1-nits	Description, "two ways", console link, three-dot menu, "runs on the Pod", web terminal link, Vale hits	Nit	Fixed	:4, :23, :27, :28, :34, :58, :113; "will" and "above" removed.

Existing feedback

• All 13 round 1 threads: Fixed, replied, and resolved (they were posted from this account).
• @OneAsterisk's bbb9e3a approval was dismissed by GitHub on a later push; no claims to verify.
• mintlify[bot]: preview deploy for this branch; the Mintlify Deployment check is still pending at this head, not failing.

PR description vs code

The PR body is empty, so there are no claims to check (R1-8).

Findings

Low

• Empty PR description (R1-8, carried forward). Add one line on what the page is for and the Linear ticket the branch name (docs438) refers to.

Nits

• :17, :29 the field label is written Expose TCP Ports in expose-ports.mdx:83. Match whichever casing the console uses.
• :21 connect-to-ide.mdx:67 tells readers to confirm the SSH Terminal Access checkbox during deploy. A pointer to it here would give official-template users a check before deploying, not only after.

Simplification opportunities

1. The three-step ssh root@… block still appears twice (:62-64, :88-90). One "Connect over SSH" step before the per-agent sections would remove about 8 lines. Optional; fine as is.

Verified clean

• Diff 4f6072c1...ac4a8ec0 touches only pods/configuration/ssh-agents.mdx (+35/-33); docs.json is unchanged since round 1 and GitHub reports the PR mergeable.
• Every internal link target exists on main: /get-started/credentials#ssh-public-keys (credentials.mdx:80), /pods/manage-pods#update-a-pod (:173), /pods/connect-to-a-pod#web-terminal (:23), connect-to-ide#step-4-… (:72), use-ssh#full-ssh-via-public-ip-… (:60), use-ssh#troubleshooting-ssh-key-authentication (:126). The in-page #step-1-expose-tcp-port-22 anchor matches the Step 1 heading.
• :17 reset warning matches manage-pods.mdx:177-179.
• "Three ways" at :23 now matches the three options that follow.
• Check tooltip imports passes.

Questions for the author

• Is Duplicate the actual menu label for Hub templates in the console (:34)? No other page documents it. Carried from round 1; not blocking.

---

_{Reviewed by Claude (claude-opus-5-5) via the pr-review skill. Tokens: 18 in / 4,244 out / 489,477 cache read / 57,157 cache write = 550,896. Estimated cost: $0.64 at $4/$20 per MTok in/out, $0.20 cache read, $8 cache write (1-hour TTL, 2× input), rate card from the bundled claude-api skill 2.1.288. Round 2 of this PR. This is automated assistance; a human owns the final call.}