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 (similar to docker ps):

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

Example output (abbreviated):

[
  {
    "id": "abc123xyz",
    "name": "my-pod",
    "desiredStatus": "RUNNING",
    "runtimeStatus": "running",
    "runtimeStatusReason": "",
    "lastStatusChange": "Rented by User: ...",
    "imageName": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04",
    "gpuId": "NVIDIA GeForce RTX 4090",
    "gpuCount": 1,
    "costPerHr": 0.44,
    "uptimeSeconds": 842
  }
]

Each Pod also includes a runtimeStatus and runtimeStatusReason field alongside desiredStatus, plus the backend’s raw lastStatusChange note. See Pod runtime status for the full list of values.

The --status flag filters on desiredStatus only (RUNNING, EXITED, and so on). It does not accept the lowercase runtimeStatus vocabulary.

List flags

--all, -a · bool

Show all Pods including exited ones. By default, only running Pods are shown.

--status · string

Filter by Pod status (e.g., RUNNING, EXITED). Cannot be used with --all.

--since · string

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

--created-after · string

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

--compute-type · string

Filter by compute type (GPU or CPU).

--name · string

Filter by Pod name.

Get Pod details

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

runpodctl pod get <pod-id>

Example output (abbreviated):

{
  "id": "abc123xyz",
  "name": "my-pod",
  "desiredStatus": "RUNNING",
  "runtimeStatus": "running",
  "runtimeStatusReason": "",
  "lastStatusChange": "Rented by User: ...",
  "imageName": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04",
  "uptimeSeconds": 842,
  "ssh": {
    "ssh_command": "ssh root@... -p 12345 -i ~/.ssh/id_ed25519"
  }
}

desiredStatus reports what you asked the platform to do. runtimeStatus reports what the Pod is actually doing, derived from live runtime telemetry. Use runtimeStatus to tell an initializing Pod (image still pulling) apart from one that is serving traffic. See Pod runtime status for the full list of values.

uptimeSeconds is the container’s uptime and is omitted whenever no container is reporting.

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

--template-id · string

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

--image · 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.

--name · string

Custom name for the Pod.

--gpu-id · string

GPU type (e.g., NVIDIA GeForce RTX 4090, NVIDIA A100 80GB PCIe). Use runpodctl gpu list to see available GPUs.

--gpu-count · int · default: "1"

Number of GPUs to allocate.

--compute-type · string · default: "GPU"

Compute type (GPU or CPU).

--container-disk-in-gb · int · default: "20"

Container disk size in GB.

--volume-in-gb · int

Persistent volume size in GB.

--volume-mount-path · string · default: "/workspace"

Mount path for the persistent volume.

--ports · string

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

--env · string

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

--cloud-type · string · default: "SECURE"

Cloud tier (SECURE or COMMUNITY).

--data-center-ids · string

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

--global-networking · bool

Enable global networking (Secure Cloud only).

--public-ip · bool

Require public IP (Community Cloud only).

--ssh · bool · default: "true"

Enable SSH on the Pod.

--network-volume-id · string

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

--min-cuda-version · 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.

--docker-args · string

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

--registry-auth-id · string

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

--country-code · string

Country code for regional deployment (e.g., US, CA, EU). Restricts Pod placement to machines in the specified region.

--stop-after · string

Automatically stop the Pod after the specified duration (e.g., 1h, 24h, 7d).

--terminate-after · string

Automatically terminate the Pod after the specified duration (e.g., 1h, 24h, 7d). Unlike --stop-after, this permanently deletes the Pod.

--compliance · string

Compliance settings for the Pod (e.g., regulatory requirements for data handling).

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>

Reset a Pod

Reset a Pod to its initial state:

runpodctl pod reset <pod-id>

Update a Pod

Update Pod configuration:

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

Update flags

--name · string

New name for the Pod.

--image · string

New Docker image name.

--container-disk-in-gb · int

New container disk size in GB.

--volume-in-gb · int

New volume size in GB.

--volume-mount-path · string

New volume mount path.

--ports · string

New comma-separated list of ports. This flag replaces the Pod’s entire port list rather than appending to it, so include every port you want to keep. Changing the port list bumps the Pod’s version and may restart the container, so processes and container-local state outside the volume may not survive the update.

--env · string

New environment variables as a JSON object.

Delete a Pod

Delete a Pod:

runpodctl pod delete <pod-id>

Pod runtime status

pod get and pod list report a derived runtimeStatus (and an optional runtimeStatusReason token) alongside the platform’s desiredStatus. Use runtimeStatus when you need to know what the Pod is actually doing; a Pod whose 20 GB image is still downloading and one that has been serving traffic for an hour both show desiredStatus: RUNNING, but only the second shows runtimeStatus: running.

Branch scripts on the token values below, not on the free-text lastStatusChange.

runtimeStatus values

running

desiredStatus is RUNNING and the platform is reporting runtime telemetry. The container is up. Does not imply any port is reachable.

initializing

desiredStatus is RUNNING but no runtime telemetry is being reported yet. The Pod is placed on a machine but the container is not up (image pull, container create, or boot). Keep polling.

stopped

desiredStatus is EXITED and the last transition was not a termination. The container is gone but the disk is kept; pod start will bring it back.

terminated

The Pod is being destroyed. Terminated Pods drop out of pod list shortly after, so this is a narrow window.

unknown

The runtime status could not be derived, either because the runtime telemetry lookup failed or because desiredStatus is a value the platform does not surface in practice. Read desiredStatus, which is in the same output.

runtimeStatusReason tokens

awaiting_container

Paired with initializing. No container is being reported for a Pod that should be running.

stopped_by_user / terminated_by_user

You stopped or terminated the Pod.

stopped_by_runpod / terminated_by_runpod

Runpod stopped or terminated the Pod. The platform does not record a machine-readable cause; in practice this is insufficient credit, a fatal image-pull failure, or host action.

stopped_outbid / terminated_outbid

A Spot or Community Cloud Pod lost its machine to a higher bid. Retry elsewhere or at on-demand pricing.

runtime_unavailable

Paired with unknown. The runtime telemetry lookup could not be made, so running and initializing cannot be told apart.

The token is a lossy read of the backend’s free-text lastStatusChange. A phrasing the CLI does not recognize leaves runtimeStatusReason absent rather than wrong; the raw text is still available in the lastStatusChange field on the same output.

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

Related commands

• runpodctl gpu list
• runpodctl template
• runpodctl ssh