pod

Manage Pods, including creating, listing, starting, stopping, and deleting Pods.

runpodctl <subcommand> pod [flags]

Subcommands

List Pods

List your Pods. By default, this command shows only running Pods and Pods in an error state (similar to docker ps). Pods in an error state are included because they still exist and may still incur charges:

runpodctl pod list

List all Pods including exited ones:

runpodctl pod list --all

Filter by status:

runpodctl pod list --status exited

Filter by creation time:

# Pods created in the last 24 hours
runpodctl pod list --since 24h

# Pods created in the last 7 days
runpodctl pod list --since 7d

# Pods created after a specific date
runpodctl pod list --created-after 2025-01-15

List flags

bool

Show all Pods including exited ones. By default, only running Pods and Pods in an error state are shown.

string

Filter by desired status (desiredStatus), such as RUNNING or EXITED. Matching is case-insensitive. Does not accept runtimeStatus values like initializing; passing one returns no results. Cannot be used with --all.

string

Filter Pods created within the specified duration (e.g., 1h, 24h, 7d). Cannot be used with --created-after.

string

Filter Pods created after the specified date in YYYY-MM-DD format. Cannot be used with --since.

string

Filter by compute type (GPU or CPU).

string

Filter by Pod name.

Get Pod details

Get detailed information about a specific Pod, including SSH connection info:

runpodctl pod get <pod-id>

Get flags

bool

Include the Pod’s placement: its datacenter ID (dataCenterId) and whether it runs on Secure Cloud (secureCloud).

bool

Include details of the attached network volume.

Create a Pod

Create a new Pod from a template:

runpodctl pod create --template-id runpod-torch-v21 --gpu-id "NVIDIA GeForce RTX 4090"

Create a Pod with a custom Docker image:

runpodctl pod create --image "runpod/pytorch:1.0.3-cu1281-torch291-ubuntu2404" --gpu-id "NVIDIA GeForce RTX 4090"

Create a CPU-only Pod:

runpodctl pod create --compute-type cpu --image ubuntu:22.04

Create flags

string

Template ID to use for Pod configuration. Use runpodctl template search to find templates.

string

Docker image to use (e.g., runpod/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04). Required if no template specified.

string

Custom name for the Pod. If you don’t set one, the Pod is named after its image without the tag (for example, runpod/pytorch). A Pod created from a template without --image is named after the template ID.

string

GPU type (e.g., NVIDIA GeForce RTX 4090, NVIDIA A100 80GB PCIe). Required for GPU Pods, and not supported for CPU Pods. Use runpodctl gpu list to see available GPUs.

int

default:"1"

Number of GPUs to allocate.

string

default:"GPU"

Compute type (GPU or CPU).

int

default:"20"

Container disk size in GB.

int

Persistent volume size in GB. CPU Pods can’t have a persistent volume. You also can’t combine this flag with --network-volume-id because a network volume takes the place of the persistent volume.

string

default:"/workspace"

Mount path for the persistent volume.

string

Comma-separated list of ports to expose (e.g., 8888/http,22/tcp).

string

Environment variables as a JSON object (e.g., '{"KEY":"value"}').

string

default:"SECURE"

Cloud tier (SECURE or COMMUNITY). Community Cloud Pods aren’t guaranteed a public IP address, so their SSH port may not be publicly reachable. Use Secure Cloud if you need SSH access.

string

Comma-separated list of preferred datacenter IDs. Use runpodctl datacenter list to see available datacenters.

bool

Enable global networking (Secure Cloud only).

bool

default:"true"

Enable SSH on the Pod.

string

Network volume ID to attach. Use runpodctl network-volume list to see available network volumes.

string

Minimum CUDA version required (e.g., 11.8, 12.4). The Pod will only be scheduled on machines that meet this CUDA version requirement.

string

Docker arguments passed to the container at runtime (e.g., "sleep infinity").

string

Container registry authentication ID for pulling private images. Use runpodctl registry list to see available registry credentials.

string

Country code that restricts Pod placement to datacenters in that country (e.g., US, DE). Supported only for GPU Pods on Secure Cloud. For CPU Pods, use --data-center-ids instead.

string

Comma-separated list of compliance certifications the datacenter must hold (e.g., HIPAA,SOC_2_TYPE_2). Supported only on Secure Cloud.

Start a Pod

Start a stopped Pod:

runpodctl pod start <pod-id>

Stop a Pod

Stop a running Pod:

runpodctl pod stop <pod-id>

Restart a Pod

Restart a Pod:

runpodctl pod restart <pod-id>

Update a Pod

Update Pod configuration:

runpodctl pod update <pod-id> --name "new-name"

Update flags

string

New name for the Pod.

string

New Docker image name.

int

New container disk size in GB.

int

New volume size in GB.

string

New volume mount path.

string

New comma-separated list of ports.

string

New environment variables as a JSON object.

Delete a Pod

Delete a Pod:

runpodctl pod delete <pod-id>

Pod runtime status

runpodctl pod get and runpodctl pod list report a Pod’s real runtime state in their JSON and YAML output, alongside the existing desiredStatus. desiredStatus is the state you asked for (for example, RUNNING), while runtimeStatus is what the Pod is actually doing. For example, a Pod still pulling a large image and a Pod that has been serving traffic for an hour both show desiredStatus: RUNNING, but their runtimeStatus values differ.

string

Always present. What the Pod is actually doing (see the table below).

string

Present only when there is more to say. A stable token you can safely branch on in scripts.

For example, runpodctl pod list --output json returns entries like this for a running Pod:

{
  "id": "abc123xyz",
  "name": "my-training-pod",
  "desiredStatus": "RUNNING",
  "runtimeStatus": "running",
  "imageName": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04",
  "gpuCount": 1,
  "costPerHr": 0.69,
  "createdAt": "2025-01-15T09:30:00Z",
  "uptimeSeconds": 3600
}

When a Pod is initializing, runtimeStatus is initializing, runtimeStatusReason is awaiting_container, and uptimeSeconds is omitted because no container is reporting yet.

Runtime status values

Value	Meaning	What to do
`running`	desiredStatus is `RUNNING` and the platform is reporting runtime telemetry, so the container is up. Does not imply that any port (such as SSH) is reachable.	Ready to use.
`initializing`	desiredStatus is `RUNNING` but no telemetry is being reported yet. Usually the container is not up yet (image pull, container creation, or boot, which the platform does not distinguish). Read this as “no container reported,” not “the container is provably down.”	Keep polling.
`stopped`	desiredStatus is `EXITED`. The container is gone, but the Pod’s disk is kept.	Run `runpodctl pod start <pod-id>` to bring it back.
`terminated`	desiredStatus is `TERMINATED`: the Pod is being destroyed. A terminated Pod drops out of `runpodctl pod list` shortly after, so this is a narrow window.	None; the Pod is gone. Because a terminated Pod quickly drops out of `runpodctl pod list`, a teardown script should treat “Pod not found” (not `runtimeStatus: terminated`) as the reliable signal that a Pod is gone.
`error`	desiredStatus is `ERROR`: the Pod is in a state it won’t recover from on its own. It still exists and may still incur charges, so the default `runpodctl pod list` keeps showing it. No SSH command is offered.	Check `runpodctl pod logs <pod-id>`, then delete or recreate the Pod.
`unknown`	The runtime state cannot be derived (an uncommon `desiredStatus`, or the runtime lookup wasn’t made).	Read `desiredStatus` from the same output.

Runtime status reasons

Token	Paired status	Meaning
`awaiting_container`	`initializing`	No container is being reported yet for a Pod that should be running.
`runtime_unavailable`	`unknown`	The runtime lookup could not be made, so `running` and `initializing` cannot be told apart.

The API doesn’t record why a Pod stopped in a machine-readable form, so stopped, terminated, and error have no reason token.

To poll a Pod to readiness in a script, wait for runtimeStatus: running. Branch on the runtimeStatus and runtimeStatusReason tokens in scripts. If runtimeStatus becomes error, stop polling, because the Pod won’t recover on its own.

# Wait until the Pod's container is up
until [ "$(runpodctl pod get <pod-id> --output json | jq -r '.runtimeStatus')" = "running" ]; do
  sleep 5
done

A runtimeStatus of unknown with reason runtime_unavailable during polling usually means the runtime lookup momentarily failed, not that the Pod is down—keep polling rather than treating it as terminal.

runtimeStatus and desiredStatus come from the same API read, so they always agree on the Pod’s state. The uptimeSeconds field reports the container’s uptime and is omitted when no container is reporting.

Pod URLs

Access exposed ports on your Pod using the following URL pattern:

https://<pod-id>-<port>.proxy.runpod.net

For example, if your Pod ID is abc123xyz and you exposed port 8888:

https://abc123xyz-8888.proxy.runpod.net

Flash CLI

Runpod CLI

Subcommands

List Pods

List flags

Get Pod details

Get flags

Create a Pod

Create flags

Start a Pod

Stop a Pod

Restart a Pod

Update a Pod

Update flags

Delete a Pod

Pod runtime status

Runtime status values

Runtime status reasons

Pod URLs

​Subcommands

​List Pods

​List flags

​Get Pod details

​Get flags

​Create a Pod

​Create flags

​Start a Pod

​Stop a Pod

​Restart a Pod

​Update a Pod

​Update flags

​Delete a Pod

​Pod runtime status

​Runtime status values

​Runtime status reasons

​Pod URLs

​Related commands

Subcommands

List Pods

List flags

Get Pod details

Get flags

Create a Pod

Create flags

Start a Pod

Stop a Pod

Restart a Pod

Update a Pod

Update flags

Delete a Pod

Pod runtime status

Runtime status values

Runtime status reasons

Pod URLs

Related commands