Sandboxes CLI - Porter

porter sandbox contains commands for listing, inspecting, executing commands in, and terminating sandboxes in the currently selected Porter project and cluster.

Sandboxes are in a private beta. Please reach out to us at support@porter.run or over Slack if you are interested in joining.

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

If the CLI cannot find a selected project or cluster, it asks you to run porter config or pass --project and --cluster.

`porter sandbox create`

Creates a sandbox from a container image in the current project and cluster. Usage:

porter sandbox create <image> [-- <command> [args...]] [flags]

Options:

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`

Use the positional form after -- 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. The sandbox runs as long as its main process. When the process exits, the sandbox moves to succeeded or failed and stops accepting exec calls, so pass a long-running command if you plan to exec into the sandbox. See sandbox lifetime.

porter sandbox create alpine:3.20

porter sandbox create alpine:3.20 --name web -- sleep 3600

porter sandbox create ghcr.io/example/tool:latest --env PORT=8080 --tag env=dev --tag owner=me

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

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

`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:

porter sandbox list [flags]

Options:

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`

Phases:

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`

Output formats:

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

Plain output includes these columns:

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 list

porter sandbox list --phase all

porter sandbox list --phase running

porter sandbox list --tag workflow=agent-run --tag run=2026-06-17

porter sandbox list -o json

porter sandbox list -o json | jq -r '.[] | select(.phase == "running") | .name'

`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:

porter sandbox exec <sandbox> [-it] -- <command> [args...] [flags]

Options:

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

Do not combine --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

Only running sandboxes accept exec calls.

porter sandbox exec abc123 -- ls -la /workspace

porter sandbox exec abc123 -- python --version

porter sandbox exec abc123 --command "echo hi && ls /workspace"

porter sandbox exec abc123 -- python -c 'print("ok")'

porter sandbox exec web -it -- sh

`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:

porter sandbox logs <sandbox> [flags]

Options:

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

Each rendered log line uses this format:

<timestamp> [<level>] <text>

porter sandbox logs abc123

porter sandbox logs abc123 --since 15m --tail 100

porter sandbox logs abc123 --level error --no-timestamps

porter sandbox logs abc123 --tail 200 | grep -i 'panic\|fatal'

`porter sandbox terminate`

Terminates one sandbox by name, or terminates many sandboxes with --all. Usage:

porter sandbox terminate <sandbox> [flags]
porter sandbox terminate --all [flags]

Options:

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`

Behavior:

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 terminate abc123

porter sandbox terminate --all --dry-run

porter sandbox terminate --all --tag workflow=agent-run --dry-run

porter sandbox terminate --all --tag workflow=agent-run

`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:

porter sandbox volume list [flags]

Options:

Flag	Description
`-o, --output`	Output format: `table`, `plain`, or `json`

Volume phases:

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

Output formats:

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

Plain output includes these columns:

Column	Description
`NAME`	Volume name
`PHASE`	Current volume phase
`ATTACHED`	Attached sandboxes, or `-` when unattached
`CREATED`	Creation timestamp

porter sandbox volume list

porter sandbox volume list -o json

porter sandbox volume list -o json | jq -r '.[].name'

porter sandbox volume list | awk -F'\t' '$2=="ready" {print $1}'

`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:

porter sandbox volume create [name] [flags]

Options:

Flag	Description
`-o, --output`	Output format: `text` or `json`

porter sandbox volume create my-data

porter sandbox volume create

porter sandbox volume create my-data -o json

`porter sandbox volume get`

Shows a single sandbox volume by name, including phase, creation time, and currently attached sandboxes. Usage:

porter sandbox volume get <name> [flags]

Options:

Flag	Description
`-o, --output`	Output format: `text` or `json`

porter sandbox volume get my-data

porter sandbox volume get my-data -o json

`porter sandbox volume delete`

Deletes a sandbox volume by name. Usage:

porter sandbox volume delete <name>

The server rejects deletion while the volume is attached to any sandbox. Terminate or recreate the attached sandboxes first.

porter sandbox volume delete my-data

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>`

​Prerequisites

​porter sandbox create

​porter sandbox list

​porter sandbox exec

​porter sandbox logs

​porter sandbox terminate

​porter sandbox volume

​porter sandbox volume list

​porter sandbox volume create

​porter sandbox volume get

​porter sandbox volume delete

​Common Workflows

​Related Docs

Prerequisites

`porter sandbox create`

`porter sandbox list`

`porter sandbox exec`

`porter sandbox logs`

`porter sandbox terminate`

`porter sandbox volume`

`porter sandbox volume list`

`porter sandbox volume create`

`porter sandbox volume get`

`porter sandbox volume delete`

Common Workflows

Related Docs