> ## Documentation Index
> Fetch the complete documentation index at: https://runpod-b18f5ded-promptless-runpodctl-pod-runtime-status.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# pod

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
runpodctl <subcommand> pod [flags]
```

## Subcommands

### List Pods

List your Pods. By default, this command shows only running Pods (similar to `docker ps`):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
runpodctl pod list
```

List all Pods including exited ones:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
runpodctl pod list --all
```

Filter by status:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
runpodctl pod list --status exited
```

Filter by creation time:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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

<ResponseField name="--all, -a" type="bool">
  Show all Pods including exited ones. By default, only running Pods are shown.
</ResponseField>

<ResponseField name="--status" type="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`.
</ResponseField>

<ResponseField name="--since" type="string">
  Filter Pods created within the specified duration (e.g., `1h`, `24h`, `7d`). Cannot be used with `--created-after`.
</ResponseField>

<ResponseField name="--created-after" type="string">
  Filter Pods created after the specified date in `YYYY-MM-DD` format. Cannot be used with `--since`.
</ResponseField>

<ResponseField name="--compute-type" type="string">
  Filter by compute type (`GPU` or `CPU`).
</ResponseField>

<ResponseField name="--name" type="string">
  Filter by Pod name.
</ResponseField>

### Get Pod details

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
runpodctl pod get <pod-id>
```

### Create a Pod

Create a new Pod from a template:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
runpodctl pod create --template-id runpod-torch-v21 --gpu-id "NVIDIA GeForce RTX 4090"
```

Create a Pod with a custom Docker image:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
runpodctl pod create --image "runpod/pytorch:1.0.3-cu1281-torch291-ubuntu2404" --gpu-id "NVIDIA GeForce RTX 4090"
```

Create a CPU-only Pod:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
runpodctl pod create --compute-type cpu --image ubuntu:22.04
```

#### Create flags

<ResponseField name="--template-id" type="string">
  Template ID to use for Pod configuration. Use [`runpodctl template search`](/runpodctl/reference/runpodctl-template) to find templates.
</ResponseField>

<ResponseField name="--image" type="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.
</ResponseField>

<ResponseField name="--name" type="string">
  Custom name for the Pod.
</ResponseField>

<ResponseField name="--gpu-id" type="string">
  GPU type (e.g., `NVIDIA GeForce RTX 4090`, `NVIDIA A100 80GB PCIe`). Use [`runpodctl gpu list`](/runpodctl/reference/runpodctl-gpu) to see available GPUs.
</ResponseField>

<ResponseField name="--gpu-count" type="int" default="1">
  Number of GPUs to allocate.
</ResponseField>

<ResponseField name="--compute-type" type="string" default="GPU">
  Compute type (`GPU` or `CPU`).
</ResponseField>

<ResponseField name="--container-disk-in-gb" type="int" default="20">
  Container disk size in GB.
</ResponseField>

<ResponseField name="--volume-in-gb" type="int">
  Persistent volume size in GB.
</ResponseField>

<ResponseField name="--volume-mount-path" type="string" default="/workspace">
  Mount path for the persistent volume.
</ResponseField>

<ResponseField name="--ports" type="string">
  Comma-separated list of ports to expose (e.g., `8888/http,22/tcp`).
</ResponseField>

<ResponseField name="--env" type="string">
  Environment variables as a JSON object (e.g., `'{"KEY":"value"}'`).
</ResponseField>

<ResponseField name="--cloud-type" type="string" default="SECURE">
  Cloud tier (`SECURE` or `COMMUNITY`).
</ResponseField>

<ResponseField name="--data-center-ids" type="string">
  Comma-separated list of preferred datacenter IDs. Use [`runpodctl datacenter list`](/runpodctl/reference/runpodctl-datacenter) to see available datacenters.
</ResponseField>

<ResponseField name="--global-networking" type="bool">
  Enable global networking (Secure Cloud only).
</ResponseField>

<ResponseField name="--public-ip" type="bool">
  Require public IP (Community Cloud only).
</ResponseField>

<ResponseField name="--ssh" type="bool" default="true">
  Enable SSH on the Pod.
</ResponseField>

<ResponseField name="--network-volume-id" type="string">
  Network volume ID to attach. Use [`runpodctl network-volume list`](/runpodctl/reference/runpodctl-network-volume) to see available network volumes.
</ResponseField>

<ResponseField name="--min-cuda-version" type="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.
</ResponseField>

<ResponseField name="--docker-args" type="string">
  Docker arguments passed to the container at runtime (e.g., `"sleep infinity"`).
</ResponseField>

<ResponseField name="--registry-auth-id" type="string">
  Container registry authentication ID for pulling private images. Use [`runpodctl registry list`](/runpodctl/reference/runpodctl-registry) to see available registry credentials.
</ResponseField>

<ResponseField name="--country-code" type="string">
  Country code for regional deployment (e.g., `US`, `CA`, `EU`). Restricts Pod placement to machines in the specified region.
</ResponseField>

<ResponseField name="--stop-after" type="string">
  Automatically stop the Pod after the specified duration (e.g., `1h`, `24h`, `7d`).
</ResponseField>

<ResponseField name="--terminate-after" type="string">
  Automatically terminate the Pod after the specified duration (e.g., `1h`, `24h`, `7d`). Unlike `--stop-after`, this permanently deletes the Pod.
</ResponseField>

<ResponseField name="--compliance" type="string">
  Compliance settings for the Pod (e.g., regulatory requirements for data handling).
</ResponseField>

### Start a Pod

Start a stopped Pod:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
runpodctl pod start <pod-id>
```

### Stop a Pod

Stop a running Pod:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
runpodctl pod stop <pod-id>
```

### Restart a Pod

Restart a Pod:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
runpodctl pod restart <pod-id>
```

### Reset a Pod

Reset a Pod to its initial state:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
runpodctl pod reset <pod-id>
```

### Update a Pod

Update Pod configuration:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
runpodctl pod update <pod-id> --name "new-name"
```

#### Update flags

<ResponseField name="--name" type="string">
  New name for the Pod.
</ResponseField>

<ResponseField name="--image" type="string">
  New Docker image name.
</ResponseField>

<ResponseField name="--container-disk-in-gb" type="int">
  New container disk size in GB.
</ResponseField>

<ResponseField name="--volume-in-gb" type="int">
  New volume size in GB.
</ResponseField>

<ResponseField name="--volume-mount-path" type="string">
  New volume mount path.
</ResponseField>

<ResponseField name="--ports" type="string">
  New comma-separated list of ports.
</ResponseField>

<ResponseField name="--env" type="string">
  New environment variables as a JSON object.
</ResponseField>

### Delete a Pod

Delete a Pod:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
runpodctl pod delete <pod-id>
```

## Pod runtime status

`runpodctl pod get` and `runpodctl pod list` now 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.

<ResponseField name="runtimeStatus" type="string">
  Always present. What the Pod is actually doing (see the table below).
</ResponseField>

<ResponseField name="runtimeStatusReason" type="string">
  Present only when there is more to say. A stable token you can safely branch on in scripts.
</ResponseField>

<ResponseField name="lastStatusChange" type="string">
  Present when available. The backend's raw status text (for example, `Exited by user: <date>` or `Outbid: <date>`).
</ResponseField>

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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` and the last status change does not name a termination. The container is gone, but the Pod's disk is kept.                                                                                                                                   | Run `runpodctl pod start <pod-id>` to bring it back.                                                                                                                                                                 |
| `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. |
| `unknown`      | The runtime state cannot be derived (an uncommon `desiredStatus`, or the runtime lookup failed).                                                                                                                                                                       | 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.                                                                                                                                                               |
| `stopped_by_user`, `terminated_by_user`     | `stopped` or `terminated` | You stopped or terminated the Pod.                                                                                                                                                                                                 |
| `stopped_by_runpod`, `terminated_by_runpod` | `stopped` or `terminated` | Runpod stopped or terminated the Pod. No machine-readable cause is recorded; in practice this is a low account balance, a fatal image-pull failure, or host action.                                                                |
| `stopped_outbid`, `terminated_outbid`       | `stopped` or `terminated` | A spot or Community Cloud Pod lost its machine to a higher bid. Retry on a different machine or at on-demand pricing. To avoid another outbid, redeploy with `runpodctl pod create` on Secure Cloud or an on-demand configuration. |
| `runtime_unavailable`                       | `unknown`                 | The runtime lookup could not be made, so `running` and `initializing` cannot be told apart.                                                                                                                                        |

<Tip>
  To poll a Pod to readiness in a script, wait for `runtimeStatus: running`. Branch on the `runtimeStatus` and `runtimeStatusReason` tokens rather than parsing the free-text `lastStatusChange`.

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
  # 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.
</Tip>

<Note>
  `runtimeStatus` and `desiredStatus` come from different sources, so a single command can briefly show them disagreeing (for example, `desiredStatus: RUNNING` next to `runtimeStatus: stopped`). When they disagree, trust `runtimeStatus`.
</Note>

The `uptimeSeconds` field now reports the container's actual uptime and is omitted entirely when no container is reporting, instead of always showing `0`.

## 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/reference/runpodctl-gpu)
* [`runpodctl template`](/runpodctl/reference/runpodctl-template)
* [`runpodctl ssh`](/runpodctl/reference/runpodctl-ssh)