Sandboxes CLI - Porter

porter sandbox contains commands for listing, inspecting, executing commands in, monitoring CPU and memory usage of, 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. The image accepts a tag (alpine:3.20) or a digest (repo@sha256:<digest>). 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
`--env-group`	Environment group on the cluster whose variables are injected into the sandbox. 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
`--ttl`	Maximum sandbox lifetime as a Go duration, such as `30m` or `2h`. Defaults to no limit
`--cpu`	CPU cores, such as `2` or `500m` for half a core. Defaults to the cluster’s sandbox size
`--memory`	Memory, such as `4Gi` or `512Mi`. Defaults to the cluster’s sandbox size
`--json`	Print the created sandbox as 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. --env-group injects the variables of a named environment group on the cluster. Values are resolved to the group’s latest version at create time and do not update afterwards. On a key conflict, a later --env-group wins over an earlier one, and an explicit --env wins over any group value. Creation fails if a named group does not exist on the cluster or has not synced yet. --ttl bounds the sandbox’s lifetime regardless of its main process: once the duration elapses, counted from creation, Porter terminates the sandbox the same way an explicit terminate does. See sandbox lifetime. --cpu and --memory size an individual sandbox instead of using the cluster’s default sandbox size. Pass one or both; the flag you omit keeps the default. CPU is in cores, either a whole number (2) or an m suffix for a fraction (500m is half a core), and memory takes a Gi or Mi suffix (4Gi, 512Mi). See custom sandbox sizes. 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 alpine:3.20 --env-group my-env-group -- sleep 3600

porter sandbox create alpine:3.20 --ttl 2h -- sleep 7200

porter sandbox create python:3.12 --cpu 2 --memory 4Gi -- python train.py

porter sandbox create ubuntu:24.04 --volume /workspace=my-data --command bash --arg -lc --arg 'ls -la' --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
`--json`	Print sandboxes as 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 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 --json

porter sandbox list --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 metrics`

Use this command to monitor a sandbox’s resource usage: how much CPU and memory it is consuming and how close it is to its limits. It prints p50 and p90 CPU and memory usage over a lookback window for a running sandbox, alongside the sandbox’s CPU and memory limits and each percentile’s utilization as a percentage of that limit. Only running sandboxes report metrics. Usage:

porter sandbox metrics <sandbox> [flags]

Options:

Flag	Description
`--since`	Lookback window as a Go duration, such as `30m` or `2h`. Bounded to `[3m, 24h]`. Defaults to `1h`
`--json`	Print the metrics summary as JSON

CPU is reported in cores and memory in bytes. Utilization is each percentile divided by the sandbox’s limit, as a percentage; it can exceed 100% because the limit is a throttling and OOM threshold, not a hard cap on the reported sample. Memory values include page cache and slightly overestimate resident memory. The summary has one row per metric (cpu_cores, mem_bytes) with these columns:

Column	Description
`metric`	Metric name
`p50`	Median value over the window
`p90`	90th-percentile value over the window
`limit`	The sandbox’s limit for this metric
`p50_util_pct`	`p50` as a percentage of `limit`
`p90_util_pct`	`p90` as a percentage of `limit`
`window_seconds`	Length of the lookback window in seconds

--json prints the same values at full precision on one line, plus a has_data boolean that is false when no samples were collected in the window.

porter sandbox metrics web

porter sandbox metrics web --since 30m

porter sandbox metrics web --json

porter sandbox metrics web --json | jq '.cpu_util_p90_pct'

Output looks like this:

┌──────────────┬────────────────────┬────────────────────┐
│    METRIC    │        P50         │        P90         │
├──────────────┼────────────────────┼────────────────────┤
│ cpu cores    │ 0.001 cores (0.1%) │ 0.003 cores (0.3%) │
│ cpu limit    │ 1.000 cores        │                    │
│ memory       │ 1.27 GiB (63.6%)   │ 2.54 GiB (126.9%)  │
│ memory limit │ 2.00 GiB           │                    │
└──────────────┴────────────────────┴────────────────────┘

window: 1h0m0s

`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
`--json`	Print volumes as 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 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 --json

porter sandbox volume list --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. With --bucket, the volume is an object volume exposing an S3 bucket registered with porter storage bucket register. Use --prefix to scope it to keys under a prefix and --access to restrict how sandboxes can use it. Usage:

porter sandbox volume create [name] [flags]

Options:

Flag	Description
`--json`	Print the created volume as JSON
`--bucket`	Create an object volume exposing this registered S3 bucket
`--prefix`	Scope an object volume to keys under this prefix. Requires `--bucket`
`--access`	Access mode for an object volume: `read-write` (default), `read-only`, or `write-only-new-files`. Requires `--bucket`

porter sandbox volume create my-data

porter sandbox volume create

porter sandbox volume create datasets --bucket my-bucket --prefix training/v1 --access read-only

porter sandbox volume create my-data --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
`--json`	Print the volume as JSON

porter sandbox volume get my-data

porter sandbox volume get my-data --json

`porter sandbox volume files`

Lists the files and directories under a path inside a volume. Omit the path to list from the volume root. The server walks the tree up to an entry budget; directories it could not fully read are marked truncated. List them directly to see more. Usage:

porter sandbox volume files <name|id> [path] [flags]

Options:

Flag	Description
`--search`	Only show entries whose name contains this substring (case-insensitive)
`--json`	Print the full nested listing as JSON

porter sandbox volume files my-data

porter sandbox volume files my-data models/checkpoints

porter sandbox volume files my-data --search .bin

porter sandbox volume files my-data --json | jq '.entries[].name'

`porter sandbox volume read`

Streams a file’s raw bytes from a volume to stdout. Redirect stdout to save the file locally, or use --range to read part of a large file. Usage:

porter sandbox volume read <name|id> <path> [flags]

Options:

Flag	Description
`--range`	Single byte range to read (`start-end`, `start-`, or `-length`). Defaults to the whole file

Reading a path that does not exist fails with a not-found error.

porter sandbox volume read my-data config/app.yaml

porter sandbox volume read my-data models/model.bin > model.bin

porter sandbox volume read my-data logs/app.log --range 0-4095

`porter sandbox volume write`

Uploads a file into a volume at a path relative to the volume root. Parent directories are created as needed, and an existing file at the path is replaced. Content comes from stdin unless --file names a local file. The write is staged to a temporary file and renamed into place, so a failed or interrupted upload leaves the previous contents alone rather than a truncated file. You can write to a volume whether or not a sandbox has it mounted. Usage:

porter sandbox volume write <name|id> <path> [flags]

Options:

Flag	Description
`--file`	Local file to upload. Defaults to reading stdin

A single write is capped at 1 GiB, and a request from outside the cluster must finish within 30 seconds; write very large files from inside a sandbox that mounts the volume.

porter sandbox volume write my-data config/app.yaml --file ./app.yaml

porter sandbox volume write my-data config/app.yaml < app.yaml

echo hello | porter sandbox volume write my-data notes.txt

`porter sandbox volume move`

Moves a file or directory to a new path inside one volume. The destination is the entry’s full new path, not a directory to drop it into, so a move renames and relocates in one call. A directory moves with everything under it. Usage:

porter sandbox volume move <name|id> <from> <to>

The destination’s parent directory must already exist, and nothing is replaced. The server refuses a move onto an occupied path, and the volume root cannot be moved or overwritten.

porter sandbox volume move my-data notes.txt archive/notes.txt

porter sandbox volume move my-data models/v1 models/v2

`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 a sandbox that cleans itself up	`porter sandbox create alpine:3.20 --ttl 2h -- sleep 7200`
Create a sandbox with an env group	`porter sandbox create alpine:3.20 --env-group my-env-group -- sleep 3600`
Create and mount a volume	`porter sandbox volume create my-data && porter sandbox create ubuntu:24.04 --volume /workspace=my-data -- bash`
Upload a local file to a volume	`porter sandbox volume write my-data config/app.yaml --file ./app.yaml`
Read a file back from a volume	`porter sandbox volume read my-data config/app.yaml`
List running sandboxes	`porter sandbox list --phase running`
Get running sandbox names for a script	`porter sandbox list --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`
Check CPU and memory usage	`porter sandbox metrics <sandbox-name> --since 30m`
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 metrics

​porter sandbox terminate

​porter sandbox volume

​porter sandbox volume list

​porter sandbox volume create

​porter sandbox volume get

​porter sandbox volume files

​porter sandbox volume read

​porter sandbox volume write

​porter sandbox volume move

​porter sandbox volume delete

​Common Workflows

​Related Docs

Prerequisites

`porter sandbox create`

`porter sandbox list`

`porter sandbox exec`

`porter sandbox logs`

`porter sandbox metrics`

`porter sandbox terminate`

`porter sandbox volume`

`porter sandbox volume list`

`porter sandbox volume create`

`porter sandbox volume get`

`porter sandbox volume files`

`porter sandbox volume read`

`porter sandbox volume write`

`porter sandbox volume move`

`porter sandbox volume delete`

Common Workflows

Related Docs