> ## Documentation Index
> Fetch the complete documentation index at: https://porter-mintlify-f4c50f36.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Sandboxes CLI
> Manage Porter Sandboxes from the Porter CLI
`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](mailto: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](/standard/cli/command-reference/porter-auth)
* You're connected to the correct project by running [porter config set-project](/standard/cli/command-reference/porter-config)
* You're connected to the correct cluster by running [porter config set-cluster](/standard/cli/command-reference/porter-config)
* 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:**
```bash theme={null}
porter sandbox create [-- [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 |
| `-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.
`--env-group` injects the variables of a named [environment group](/applications/configure/environment-groups) 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](/sandboxes/overview#sandbox-lifetime).
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](/sandboxes/overview#sandbox-lifetime).
```bash Create Sandbox theme={null}
porter sandbox create alpine:3.20
```
```bash Named Sandbox theme={null}
porter sandbox create alpine:3.20 --name web -- sleep 3600
```
```bash With Env and Tags theme={null}
porter sandbox create ghcr.io/example/tool:latest --env PORT=8080 --tag env=dev --tag owner=me
```
```bash With Volume theme={null}
porter sandbox create ubuntu:24.04 --volume /workspace=my-data -- bash -lc 'ls -la /workspace'
```
```bash With Env Group theme={null}
porter sandbox create alpine:3.20 --env-group my-env-group -- sleep 3600
```
```bash With TTL theme={null}
porter sandbox create alpine:3.20 --ttl 2h -- sleep 7200
```
```bash JSON Output theme={null}
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:**
```bash theme={null}
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 |
```bash List Sandboxes theme={null}
porter sandbox list
```
```bash Include Terminated theme={null}
porter sandbox list --phase all
```
```bash Filter by Phase theme={null}
porter sandbox list --phase running
```
```bash Filter by Tags theme={null}
porter sandbox list --tag workflow=agent-run --tag run=2026-06-17
```
```bash JSON Output theme={null}
porter sandbox list -o json
```
```bash Script Running Names theme={null}
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:**
```bash theme={null}
porter sandbox exec [-it] -- [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.
```bash List Files theme={null}
porter sandbox exec abc123 -- ls -la /workspace
```
```bash Check Python theme={null}
porter sandbox exec abc123 -- python --version
```
```bash Shell Command theme={null}
porter sandbox exec abc123 --command "echo hi && ls /workspace"
```
```bash Inline Script theme={null}
porter sandbox exec abc123 -- python -c 'print("ok")'
```
```bash Interactive Shell theme={null}
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:**
```bash theme={null}
porter sandbox logs [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:
```text theme={null}
[]
```
```bash Recent Logs theme={null}
porter sandbox logs abc123
```
```bash Last 15 Minutes theme={null}
porter sandbox logs abc123 --since 15m --tail 100
```
```bash Errors Only theme={null}
porter sandbox logs abc123 --level error --no-timestamps
```
```bash Search Logs theme={null}
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:**
```bash theme={null}
porter sandbox terminate [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 |
```bash Terminate One theme={null}
porter sandbox terminate abc123
```
```bash Dry Run Bulk Terminate theme={null}
porter sandbox terminate --all --dry-run
```
```bash Terminate by Tag Dry Run theme={null}
porter sandbox terminate --all --tag workflow=agent-run --dry-run
```
```bash Terminate by Tag theme={null}
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 =`, 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:**
```bash theme={null}
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 |
```bash List Volumes theme={null}
porter sandbox volume list
```
```bash JSON Output theme={null}
porter sandbox volume list -o json
```
```bash Script Volume Names theme={null}
porter sandbox volume list -o json | jq -r '.[].name'
```
```bash Ready Volume Names theme={null}
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:**
```bash theme={null}
porter sandbox volume create [name] [flags]
```
**Options:**
| Flag | Description |
| -------------- | ------------------------------- |
| `-o, --output` | Output format: `text` or `json` |
```bash Create Named Volume theme={null}
porter sandbox volume create my-data
```
```bash Create Generated Name theme={null}
porter sandbox volume create
```
```bash JSON Output theme={null}
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:**
```bash theme={null}
porter sandbox volume get [flags]
```
**Options:**
| Flag | Description |
| -------------- | ------------------------------- |
| `-o, --output` | Output format: `text` or `json` |
```bash Get by Name theme={null}
porter sandbox volume get my-data
```
```bash JSON Output theme={null}
porter sandbox volume get my-data -o json
```
### `porter sandbox volume delete`
Deletes a sandbox volume by name.
**Usage:**
```bash theme={null}
porter sandbox volume delete
```
The server rejects deletion while the volume is attached to any sandbox. Terminate or recreate the attached sandboxes first.
```bash Delete by Name theme={null}
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` |
| 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 -- python -c 'print("ok")'` |
| Fetch recent errors | `porter sandbox logs --since 30m --level error` |
| Preview tagged cleanup | `porter sandbox terminate --all --tag run= --dry-run` |
| Clean up tagged sandboxes | `porter sandbox terminate --all --tag run=` |
## Related Docs
* [Sandboxes Overview](/sandboxes/overview)
* [Sandboxes Getting Started](/sandboxes/getting-started)
* [Python Sandbox SDK quickstart](/sandbox/sdk/python/quickstart)
* [TypeScript Sandbox SDK quickstart](/sandbox/sdk/typescript/quickstart)