porter sandbox volume

Manage persistent volumes that Porter sandboxes can mount, including creating, listing, inspecting, and deleting cluster-scoped sandbox volumes.

porter sandbox volume contains commands for managing persistent volumes that sandboxes mount at launch.

Sandbox volumes are cluster-scoped persistent volumes created up front with a stable name. Once created, you reference them from porter sandbox create via --volume <mount_path>=<name|id> so data persists across sandbox runs.

Prerequisites

• You’ve logged in to the Porter CLI after running porter auth login
• You’re connected to the correct project by running porter config set-project
• You’re connected to the correct cluster by running porter config set-cluster

---

porter sandbox volume create

Creates a persistent volume on the current cluster. Volumes start in the pending phase. Sandboxes that mount them wait for the underlying claim to bind, so you don’t need an explicit wait step before porter sandbox create.

The name must be a valid DNS label (lowercase alphanumerics and dashes). Omit the name to let the server default it to the new volume’s ID.

Usage:

porter sandbox volume create [name] [flags]

Options:

Flag	Description
-o, --output	Output format: text or json. Defaults to text.

Named volume

porter sandbox volume create my-data

---

porter sandbox volume list

Lists every volume on the current project and cluster, including the IDs of any sandboxes the volume is currently attached to. Output is sorted most-recent first.

When stdout is a TTY, the default output is a human-friendly table with color-coded phases. When piped or redirected, output defaults to plain tab-separated rows. Use --output json for machine-readable consumption.

Usage:

porter sandbox volume list [flags]

Options:

Flag	Description
-o, --output	Output format: table, json, or plain. Defaults to table on a TTY, plain when piped.

List volumes

porter sandbox volume list

---

porter sandbox volume get

Shows the phase, creation time, and currently attached sandboxes for a single volume. Accepts either a volume name or ID. IDs are detected by UUID shape; names are resolved server-side.

Usage:

porter sandbox volume get <name|id> [flags]

Options:

Flag	Description
-o, --output	Output format: text or json. Defaults to text.

Get by name

porter sandbox volume get my-data

---

porter sandbox volume delete

Deletes a volume by name or ID. The server rejects the call while the volume is still attached to any sandbox — terminate the dependent sandboxes first with porter sandbox terminate <id>.

Usage:

porter sandbox volume delete <name|id>

Delete by name

porter sandbox volume delete my-data

Deletion is permanent. The underlying persistent volume claim is removed and any data stored on it is lost.

---

Mounting volumes in a sandbox

Once a volume exists, mount it when creating a sandbox with --volume <mount_path>=<name|id>. Either the volume name or its UUID works — names are resolved client-side via a single lookup.

porter sandbox create ubuntu:24.04 --volume /workspace=my-data -- bash -lc 'ls -la /workspace'

The --volume flag is repeatable, so you can attach multiple volumes at distinct mount paths in a single sandbox.