porter sandbox contains commands for listing, inspecting, executing commands in, and terminating sandboxes in the currently selected Porter project and cluster.
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
- Sandboxes are enabled on the selected AWS cluster
porter config or pass --project and --cluster.
porter sandbox create
Creates a sandbox from a container image in the current project and cluster.
Usage:
| Flag | Description |
|---|---|
--name | Cluster-unique sandbox name. Use lowercase letters, numbers, and hyphens; start and end with a letter or number. Use this name with exec, logs, and terminate |
--command | Override the image entrypoint. Repeat for each argv element |
--arg | Argument passed to the command. Repeatable |
-e, --env | Environment variable in KEY=VALUE form. Repeatable |
--tag | Tag in key=value form. Repeatable |
--volume | Volume mount in mount_path=volume-ref form, where volume-ref is a volume name or ID. Repeatable. The mount path must be absolute |
-o, --output | Output format: text or json |
-- for common one-shot commands. Use --command and --arg when scripting individual argv elements.
Volume values can be volume names or volume IDs. The CLI resolves names first, then falls back to treating the value as an ID.
Sandbox names currently cannot be reused, even after the sandbox is terminated. Omit --name only for one-off sandboxes where you do not need stable lookup later.
porter sandbox list
Lists sandboxes in the current project and cluster. The command auto-paginates through the API and sorts results most-recent-first.
Usage:
| Flag | Description |
|---|---|
--phase | Filter by phase. Defaults to hiding terminated sandboxes. Use all to include every phase |
--tag | Filter by tag in key=value format. Repeat the flag to require multiple tags |
-o, --output | Output format: table, plain, or json |
| Phase | Description |
|---|---|
queued | Accepted by the API and waiting for capacity |
creating | Runtime is being prepared and the container is starting |
running | Sandbox is ready and can accept exec calls |
succeeded | Sandbox command completed successfully |
failed | Sandbox command or runtime failed |
terminated | Sandbox was explicitly terminated |
all | Includes every phase when used with --phase |
| Format | Description |
|---|---|
table | Colorized table for terminal output |
plain | Tab-separated rows with a header. Used by default when output is piped or redirected |
json | JSON array, recommended for scripts |
| Column | Description |
|---|---|
NAME | Sandbox name |
IMAGE | Container image |
PHASE | Current sandbox phase |
CREATED | Creation timestamp |
STARTED | Start timestamp, when available |
EXIT | Exit code, when available |
TAGS | Sandbox tags |
porter sandbox exec
Runs a command in a running sandbox, identified by name. Non-interactive exec prints stdout and stderr; interactive exec opens a shell session.
Usage:
| Flag | Description |
|---|---|
-c, --command | Shell-style command string to run through sh -c inside the sandbox |
-i, --interactive | Keep stdin open and stream it to the sandbox |
-t, --tty | Allocate a TTY for an interactive shell |
--command with positional command arguments.
Exit codes:
| Exit code | Meaning |
|---|---|
0 | Command succeeded |
1 | Operational error or propagated sandbox command failure |
2 | CLI usage error |
3 | Sandbox is not in the running phase |
running sandboxes accept exec calls.
porter sandbox logs
Fetches and prints a batch of log lines for a sandbox. By default, the CLI requests logs from the last hour with a limit of 500 lines.
Usage:
| Flag | Description |
|---|---|
--since | Lookback window as a Go duration, such as 30m or 1h30m. Defaults to 1h |
--limit | Maximum number of log lines. Defaults to 500; server cap is 5000; 0 uses the server default |
--tail | Alias for --limit. When greater than 0, it overrides --limit |
--level | Client-side filter: info, warning, or error |
--no-timestamps | Suppress the leading RFC3339 timestamp on each line |
porter sandbox terminate
Terminates one sandbox by name, or terminates many sandboxes with --all.
Usage:
| Flag | Description |
|---|---|
--all | Terminate every actionable sandbox in the current project and cluster |
--dry-run | Print the sandboxes that would be terminated without terminating them |
--tag | Scope bulk termination by tag in key=value format. Requires --all |
| Case | Behavior |
|---|---|
--all | No interactive confirmation is shown |
| Already terminated sandboxes | Skipped |
404 during --all | Treated as success because another caller may have already deleted the sandbox |
porter sandbox volume
Manages persistent volumes that sandboxes can mount at launch. Create a volume first, then reference it from porter sandbox create with --volume <mount_path>=<volume-ref>, where volume-ref is a volume name or ID.
porter sandbox volume list
Lists sandbox volumes in the current project and cluster, sorted most-recent-first.
Usage:
| Flag | Description |
|---|---|
-o, --output | Output format: table, plain, or json |
| Phase | Description |
|---|---|
pending | The volume was created and is waiting for the underlying claim to bind |
ready | The volume is ready to mount into sandboxes |
failed | The volume failed to provision |
| Format | Description |
|---|---|
table | Colorized table for terminal output |
plain | Tab-separated rows with a header. Used by default when output is piped or redirected |
json | JSON array, recommended for scripts |
| Column | Description |
|---|---|
NAME | Volume name |
PHASE | Current volume phase |
ATTACHED | Attached sandboxes, or - when unattached |
CREATED | Creation timestamp |
porter sandbox volume create
Creates a persistent volume on the current cluster. The volume name may contain lowercase letters, numbers, and hyphens, and must start and end with a letter or number. Omit the name only for one-off volumes where you do not need stable lookup later.
Volumes start in the pending phase. Sandboxes that mount them wait for the underlying claim to bind, so porter sandbox create does not need a separate wait step.
Volume names must be unique within a cluster for the lifetime of the volume. After a volume is deleted, its name can be used again.
Usage:
| Flag | Description |
|---|---|
-o, --output | Output format: text or json |
porter sandbox volume get
Shows a single sandbox volume by name, including phase, creation time, and currently attached sandboxes.
Usage:
| Flag | Description |
|---|---|
-o, --output | Output format: text or json |
porter sandbox volume delete
Deletes a sandbox volume by name.
Usage:
Common Workflows
| Workflow | Command |
|---|---|
| Create a named sandbox | porter sandbox create alpine:3.20 --name web -- sleep 3600 |
| Create and mount a volume | porter sandbox volume create my-data && porter sandbox create ubuntu:24.04 --volume /workspace=my-data -- bash |
| List running sandboxes | porter sandbox list --phase running |
| Get running sandbox names for a script | porter sandbox list -o json | jq -r '.[] | select(.phase == "running") | .name' |
| Run a smoke command | porter sandbox exec <sandbox-name> -- python -c 'print("ok")' |
| Fetch recent errors | porter sandbox logs <sandbox-name> --since 30m --level error |
| Preview tagged cleanup | porter sandbox terminate --all --tag run=<run-id> --dry-run |
| Clean up tagged sandboxes | porter sandbox terminate --all --tag run=<run-id> |