ssh

Use runpodctl to manage SSH keys and retrieve the connection command and key details required to access a Runpod Pod.

Manage SSH keys and get SSH connection information for Pods.

Command

runpodctl ssh <subcommand> [flags]

Subcommands

Get SSH connection info

Get SSH connection details for a Pod. This returns the SSH command and key information, but does not initiate an interactive session:

runpodctl ssh info <pod-id>

Info flags

--verbose · bool

Include Pod ID and name in output. Shorthand: -v.

The ssh info command returns connection details that you can use to connect via SSH manually. It does not start an interactive SSH session. When a Pod is not reachable, runpodctl ssh info reports the specific reason instead of a generic message.

To connect to your Pod, use the SSH command provided in the output:

ssh user@host -p <port> -i <key-path>

runpodctl ssh info explains which of the following cases applies. It also reports the Pod’s runtimeStatus, so you can match a not-ready result to the runtime status vocabulary:

Reason	Meaning	What to do
Pod is initializing	No container is reported yet (image pull, container creation, or boot).	Wait and try again.
Pod is stopped	The Pod’s container is gone but its disk is kept.	Start it with runpodctl pod start <pod-id>.
Pod is terminated	The Pod has been destroyed.	None; deploy a new Pod.
Pod is in an error state	The Pod is in a state it won’t recover from on its own.	Check runpodctl pod logs <pod-id>, then delete or recreate the Pod.
No SSH port published	The Pod is running but does not publish 22/tcp.	Add it with the runpodctl pod update command the CLI provides (see the Warning below).
No public IP	Port 22 is mapped, but the machine has no publicly routable IP. This affects direct SSH over a public IP specifically; basic SSH (proxied through Runpod, no public IP required) may still work.	Use Basic SSH, which does not need a public IP. If you need direct SSH over a public IP, redeploy on a machine that provides one.
Mapping not ready yet	Port 22 is declared, but the host has not published the mapping yet.	Wait and try again.

For the “No SSH port published” case, runpodctl ssh info gives you a ready-to-run command of the form runpodctl pod update <pod-id> --ports <existing-ports>,22/tcp that preserves your existing ports.

runpodctl pod update --ports replaces the Pod’s entire port list (unlike --env, which merges), so always include your current ports when you add 22/tcp. Changing the port list also bumps the Pod’s version, which can restart the container. Processes and container-local state outside the volume disk may not survive. If the Pod is running an active job, checkpoint your work to the volume disk before changing ports, since the container may restart.

For the full list of runtime status values, see Pod runtime status.

List SSH keys

List all SSH keys associated with your account:

runpodctl ssh list-keys

Add an SSH key

Add a new SSH key to your account:

# Add a key from a file
runpodctl ssh add-key --key-file ~/.ssh/id_ed25519.pub

# Add a key directly
runpodctl ssh add-key --key "ssh-ed25519 AAAA..."

If the key or file contains several public keys, one per line, each is saved as a separate key. Blank lines and comment lines that start with # are skipped. If any other line isn’t a valid public key, the command fails before saving anything. Keys already on your account are matched by fingerprint and aren’t added again.

Add-key flags

--key · string

The public key string to add.

--key-file · string

Path to a file containing the public key.

--remove-invalid · bool

Delete saved entries that aren’t valid public keys without asking. See Fix invalid saved entries.

Remove an SSH key

Remove an SSH key from your account by name or fingerprint:

# Remove a key by name
runpodctl ssh remove-key --name my-laptop

# Remove a key by fingerprint
runpodctl ssh remove-key --fingerprint SHA256:abcd1234...

You must provide --name, --fingerprint, or --invalid. If multiple keys share the same name, use --fingerprint instead.

Remove-key flags

--name · string

Name of the key to remove.

--fingerprint · string

Fingerprint of the key to remove. Use this when multiple keys have the same name.

--invalid · bool

Remove every saved entry that isn’t a valid public key, and keep all valid keys. Can’t be combined with --name or --fingerprint.

--remove-invalid · bool

Delete saved entries that aren’t valid public keys without asking, then remove the key you specified.

Fix invalid saved entries

Older accounts can have saved SSH key entries that aren’t valid public keys, such as a stray line of text. While any such entry exists, Runpod rejects every change to your key list, so you can’t add or remove keys.

When you run ssh add-key or ssh remove-key in an interactive terminal, runpodctl lists the invalid entries and asks whether to delete them before continuing. Nothing is deleted unless you confirm.

When runpodctl runs in a script or from an AI agent, it doesn’t prompt. Instead, the command fails with a conflict error that names the invalid entry. To fix it, do one of the following:

• Re-run the command with --remove-invalid to delete the invalid entries as part of the same change.
• Run runpodctl ssh remove-key --invalid to delete only the invalid entries.

Related commands

• runpodctl pod get
• runpodctl doctor