Connect a coding agent to a Pod

Set up SSH access so coding agents like Claude Code, Codex, and Cursor can connect to your Runpod Pod over a secure shell connection.

Coding agents like Claude Code, Codex, and Cursor connect to Pods over SSH. This page covers port exposure, confirming the SSH daemon is running, and connecting your agent.

Requirements

You need an SSH key pair added to your Runpod account before starting. See SSH public keys for setup instructions.

Step 1: Expose TCP port 22

If you deployed a Pod without port 22, open the Pod’s three-dot menu, click Edit Pod, add 22 to the Expose TCP ports field, and save. Editing a Pod resets it and erases anything stored outside /workspace or a network volume. See Update a Pod.

Official Runpod templates already expose port 22, so you can skip this step if you use one. After you deploy, check that port 22 appears under Direct TCP Ports in the Pod’s Connect tab.

For other templates, there are three ways to add port 22.

Edit an existing template:

1. Go to Templates in the Runpod console.
2. Find your template, click the three-dot menu at the right of its row, and select Edit template.
3. In the Config tab, expand Networking configuration and add 22 to the Expose TCP ports field.
4. Click Save, then deploy the Pod.

Use a community or Hub template that lacks port 22:

You can’t edit these templates directly. Open the template’s three-dot menu and click Duplicate to create an editable copy, then follow the preceding steps on the copy.

Override ports for one deployment:

If you only need port 22 for this specific Pod and don’t want to change the template permanently, click Set overrides next to the selected template on the Deploy a Pod page. This changes ports for that deployment only and leaves the template unchanged.

After the Pod starts, open its Connect tab and look for Direct TCP Ports. You see a mapping like this:

TCP port 213.173.109.39:13007 -> :22

This is the public IP and port your agent uses to connect.

Step 2: Confirm the SSH daemon is running

Official Runpod templates such as Runpod PyTorch and Stable Diffusion start the SSH daemon automatically, so you don’t need any extra setup.

Custom templates require you to start the SSH daemon manually. See Full SSH via public IP for the Docker start command to add to your template.

Step 3: Connect your agent

Claude Code

In this setup, Claude Code runs on the Pod itself. SSH is how you open a terminal session to reach it. Cursor, by contrast, runs locally and connects to the Pod remotely.

SSH into the Pod using the IP and port from Step 1:

ssh root@POD_IP_ADDRESS -p SSH_PORT -i ~/.ssh/id_ed25519

Once inside the Pod, install Claude Code using the native installer:

curl -fsSL https://claude.ai/install.sh | bash

Then navigate to your project directory and start Claude Code:

claude

Cursor

Cursor runs on your local machine and connects to the Pod over Remote-SSH. Follow Configure SSH for your IDE, using the IP and port from Step 1.

Codex

Like Claude Code, Codex runs on the Pod itself in this setup. SSH into the Pod first, then install and run Codex there.

SSH into the Pod using the IP and port from Step 1:

ssh root@POD_IP_ADDRESS -p SSH_PORT -i ~/.ssh/id_ed25519

Once inside the Pod, install Codex using the native installer:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Authenticate and start Codex from your project directory:

codex login
codex

Troubleshooting

Permission denied (publickey)

See Troubleshooting SSH key authentication for a full list of causes and fixes.

Connection refused

Check that port 22 appears under Direct TCP Ports in the Pod’s Connect tab. If it’s missing, add it with Edit Pod as described in Step 1. Then confirm the SSH daemon is running by opening the web terminal and running:

service ssh status

Pod IP address or port changed

The external port mapping changes whenever a Pod stops and restarts, and Community Cloud Pods may also receive a new IP address. If your agent loses its connection, copy the IP and port again from Direct TCP Ports in the Pod’s Connect tab and reconnect.

Next steps

Connect to a Pod with SSH

Full reference for basic SSH, full SSH via public IP, and password-based SSH.

Expose ports

TCP and HTTP port exposure for Pods.

Connect to a Pod with VSCode or Cursor

Set up a full IDE connection to your Pod.