# Sandboxes CLI reference


> *Render Sandboxes is in early access.*
>
> APIs, defaults, and limits might change during the early access period. Before using sandboxes in production workloads, discuss your use case with your Render contact.

During Render Sandboxes early access, all sandbox-related Render CLI commands are under the `render ea` namespace.

When Render Sandboxes reaches general availability, these commands will be available directly under the `render` namespace.

## Global options

| Option | Description |
| --- | --- |
| `--confirm` | Skip all confirmation prompts |
| `--output`, `-o` | Set output format to interactive, json, yaml, or text. Auto-switches to text on non-TTY |

## Sandbox lifecycle

###### `ea sandboxes`

Manage sandboxes for your Render workspace.

Sandboxes are ephemeral compute environments for running code, agents, and experiments.

Every sandbox belongs to a sandbox group, which scopes it to a region. Manage
groups with "render ea sandbox-groups".

Snapshot a sandbox with "render ea sandboxes snapshots create" and restore new
sandboxes from it with "render ea sandboxes create `--snapshot-id`".

*Usage:*

```bash
render ea sandboxes
```

*Available commands:*

| Command | Description |
| --- | --- |
| [`copy`](#ea-sandboxes-copy) | Copy files to or from a sandbox |
| [`create`](#ea-sandboxes-create) | Create a new sandbox |
| [`exec`](#ea-sandboxes-exec) | Execute a command in a sandbox |
| [`list`](#ea-sandboxes-list) | List sandboxes |
| [`snapshots`](#ea-sandboxes-snapshots) | Manage sandbox snapshots |
| [`stop`](#ea-sandboxes-stop) | Terminate a sandbox |

*Examples:*

```bash
render ea sandboxes create
render ea sandboxes create --plan=standard --region=oregon
render ea sandboxes create --snapshot-id snp-abc123
render ea sandboxes copy ./main.py sbx-abc123:/app/main.py
render ea sandboxes exec sbx-abc123 -- echo hello
render ea sandboxes snapshots create sbx-abc123
render ea sandboxes snapshots list --group sbg-abc123
render ea sandboxes stop sbx-abc123 --confirm
```

*Options:*

[Global options](#global-options) only

###### `ea sandboxes create`

Create a new sandbox in the current workspace.

The command prints the new sandbox while it is still `creating`. Wait for its status to become `running` before executing commands in it.

*Usage:*

```bash
render ea sandboxes create
```

*Examples:*

```bash
render ea sandboxes create
render ea sandboxes create --plan=standard --region=oregon
render ea sandboxes create --timeout=3600
render ea sandboxes create --network-policy=deny-all
render ea sandboxes create --env-var FOO=bar --env-var BAZ=qux
render ea sandboxes create --env-file .env.production --env-var LOG_LEVEL=debug
render ea sandboxes create --snapshot-id snp-abc123
```

*Options:*

[Global options](#global-options), plus:

| Option | Description |
| --- | --- |
| `--env-file` | Path to an env file to load. Repeat to load multiple files (later files override earlier ones). Every listed file must exist. |
| `--env-var` | Set environment variables in `KEY=VALUE` format (can be specified multiple times). Inline values override values loaded from `--env-file`. |
| `--network-policy` | Outbound network policy: allow-all, deny-all. Defaults to `allow-all`. |
| `--plan` | Compute plan: starter, standard, pro During early access, this flag does not select a different sandbox configuration. |
| `--region` | Region to run the sandbox in. During early access, sandboxes run only in Oregon. |
| `--snapshot-id` | Start from this snapshot instead of the base image. The snapshot must be available and in the same sandbox group. A runtime snapshot requires `--plan` to match its plan. |
| `--timeout` | Maximum sandbox lifetime in seconds. 0 uses the default and maximum of 86400 (24 hours). The sandbox terminates when this timeout elapses. |

###### `ea sandboxes list`

List sandboxes in your workspace.

By default, terminated sandboxes are excluded. Use `--all` to include them, or `--status` to filter by specific statuses.

`--status` is repeatable and accepts `creating`, `running`, `suspended`, `resuming`, `errored`, or `terminated`. If you pass both `--all` and `--status`, the status filter takes precedence.

*Usage:*

```bash
render ea sandboxes list
```

*Examples:*

```bash
render ea sandboxes list
render ea sandboxes list --all
render ea sandboxes list --status=running
render ea sandboxes list --status=running --status=creating
render ea sandboxes list -o json
```

*Options:*

[Global options](#global-options), plus:

| Option | Description |
| --- | --- |
| `--all` | Include terminated sandboxes |
| `--status` | Filter by status (repeatable: creating, running, suspended, resuming, errored, terminated) |

###### `ea sandbox-groups`

Manage sandbox groups for your Render workspace.

Sandbox groups scope a workspace's sandboxes to a region and (optionally) an
environment. Early access guarantees at most one default group per workspace;
Beta will add multi-group support.

*Usage:*

```bash
render ea sandbox-groups
```

*Available commands:*

| Command | Description |
| --- | --- |
| [`list`](#ea-sandbox-groups-list) | List sandbox groups in the active workspace |

*Examples:*

```bash
render ea sandbox-groups list
render ea sandbox-groups list -o json
```

*Options:*

[Global options](#global-options) only

###### `ea sandbox-groups list`

List sandbox groups in your workspace.

Early access guarantees at most one default group per workspace, so this
command typically prints a single row.

*Usage:*

```bash
render ea sandbox-groups list
```

*Examples:*

```bash
# List sandbox groups in the active workspace
render ea sandbox-groups list

# Output as JSON
render ea sandbox-groups list -o json
```

*Options:*

[Global options](#global-options) only

###### `ea sandboxes stop <sandboxId>`

Terminate a running sandbox. This action is irreversible.

Without `--confirm`, this command previews what would be terminated and makes no
changes. Pass `--confirm` to actually terminate the sandbox.

*Usage:*

```bash
render ea sandboxes stop <sandboxId>
```

*Examples:*

```bash
# Preview termination (no changes made)
render ea sandboxes stop sbx-abc123

# Terminate the sandbox
render ea sandboxes stop sbx-abc123 --confirm

# JSON output
render ea sandboxes stop sbx-abc123 --confirm --output json
```

*Options:*

[Global options](#global-options) only

## Runtime execution

###### `ea sandboxes exec <sandboxId> -- <command>`

Run a single command in a running sandbox. Streams stdout and stderr as
the command runs, then exits with the remote command's exit code.

Pass the command after a "--" separator so its own flags aren't parsed by the
CLI.

*Usage:*

```bash
render ea sandboxes exec <sandboxId> -- <command>
```

*Examples:*

```bash
render ea sandboxes exec sbx-abc123 -- echo hello
render ea sandboxes exec sbx-abc123 -- python script.py
```

*Options:*

[Global options](#global-options) only

###### `ea sandboxes copy <src> <dst>`

Copy a file or directory between the local filesystem and a running sandbox.

Prefix the remote side with the sandbox ID and a colon, like scp. A relative
sandbox path resolves inside the sandbox's home directory; an absolute path
addresses the sandbox filesystem root. Directories are transferred as
archives: uploading a local directory recreates it at the sandbox path, and
downloading a sandbox directory recreates it under the local path. "cp" works
as an alias.

Unlike cp, a directory destination is not nested into: copying ./src to
sbx-abc123:/tmp/src puts src's contents at /tmp/src, not at /tmp/src/src. A
single file copied to an existing local directory does land inside it.

*Usage:*

```bash
render ea sandboxes copy <src> <dst>
```

*Aliases:* `cp`

*Examples:*

```bash
render ea sandboxes copy ./main.py sbx-abc123:main.py
render ea sandboxes copy sbx-abc123:output.json ./output.json
render ea sandboxes copy ./src sbx-abc123:/tmp/src
render ea sandboxes cp sbx-abc123:. ./sandbox-home
render ea sandboxes copy sbx-abc123:output.json ./downloads/ --output json
```

*Options:*

[Global options](#global-options) only

## Snapshot management

The CLI provides snapshot commands under `render ea sandboxes snapshots`.

###### `ea sandboxes snapshots`

Manage snapshots of sandboxes in your Render workspace.

A snapshot captures a running sandbox so a new sandbox can be restored from it with "render ea sandboxes create `--snapshot-id`". A filesystem snapshot captures the writable filesystem and restores onto any plan. A runtime snapshot also captures memory and CPU state and restores only onto the plan of the source sandbox.

Snapshots belong to the sandbox group of their source sandbox. Getting, listing, or deleting a snapshot uses the active workspace's default group unless `--group` is provided.

*Usage:*

```bash
render ea sandboxes snapshots
```

*Available commands:*

| Command | Description |
| --- | --- |
| [`create`](#ea-sandboxes-snapshots-create) | Snapshot a running sandbox |
| [`delete`](#ea-sandboxes-snapshots-delete) | Delete a sandbox snapshot |
| [`get`](#ea-sandboxes-snapshots-get) | Get a sandbox snapshot |
| [`list`](#ea-sandboxes-snapshots-list) | List sandbox snapshots |

*Examples:*

```bash
# Snapshot a running sandbox
render ea sandboxes snapshots create sbx-abc123

# List the snapshots in the default sandbox group
render ea sandboxes snapshots list

# List the snapshots in a specific sandbox group
render ea sandboxes snapshots list --group sbg-abc123

# Get one snapshot
render ea sandboxes snapshots get snp-abc123

# Delete a snapshot
render ea sandboxes snapshots delete snp-abc123 --confirm

# Delete a snapshot in a specific group
render ea sandboxes snapshots delete snp-abc123 --group sbg-abc123 --confirm
```

*Options:*

[Global options](#global-options) only

###### `ea sandboxes snapshots create <sandboxId>`

Capture a snapshot of a running sandbox.

The command returns as soon as the API accepts the request, while the snapshot
status is still "creating". Poll with "render ea sandboxes snapshots get" until
the status is "available" before starting a sandbox from it.

The sandbox keeps running after the capture.

*Usage:*

```bash
render ea sandboxes snapshots create <sandboxId>
```

*Examples:*

```bash
# Snapshot the filesystem (default)
render ea sandboxes snapshots create sbx-abc123

# Also capture memory and CPU state
render ea sandboxes snapshots create sbx-abc123 --kind runtime

# JSON output
render ea sandboxes snapshots create sbx-abc123 --output json
```

*Options:*

[Global options](#global-options), plus:

| Option | Description |
| --- | --- |
| `--kind` | Snapshot kind: filesystem (default), runtime |

###### `ea sandboxes snapshots get <snapshotId>`

Get one sandbox snapshot by ID.

Uses the active workspace's default sandbox group unless `--group` is provided.
An expired snapshot is reported as not found.

Displays the snapshot's status and details.

*Usage:*

```bash
render ea sandboxes snapshots get <snapshotId>
```

*Examples:*

```bash
# Get a snapshot
render ea sandboxes snapshots get snp-abc123

# Get a snapshot in a specific group
render ea sandboxes snapshots get snp-abc123 --group sbg-abc123

# JSON output
render ea sandboxes snapshots get snp-abc123 --output json
```

*Options:*

[Global options](#global-options), plus:

| Option | Description |
| --- | --- |
| `--group` | Sandbox group the snapshot belongs to (defaults to the active workspace's default group) |

###### `ea sandboxes snapshots list`

List the snapshots in a sandbox group, newest first.

Uses the active workspace's default sandbox group unless `--group` is provided.
Deleted and expired snapshots are not listed.

*Usage:*

```bash
render ea sandboxes snapshots list
```

*Examples:*

```bash
# List every snapshot in the default sandbox group
render ea sandboxes snapshots list

# List snapshots in a specific group
render ea sandboxes snapshots list --group sbg-abc123

# Only snapshots that are ready to start a sandbox from
render ea sandboxes snapshots list --status available

# JSON output
render ea sandboxes snapshots list --output json
```

*Options:*

[Global options](#global-options), plus:

| Option | Description |
| --- | --- |
| `--group` | Sandbox group to list (defaults to the active workspace's default group) |
| `--status` | Filter by status (repeatable: creating, available, failed) |

###### `ea sandboxes snapshots delete <snapshotId>`

Delete one sandbox snapshot by ID. This action is irreversible.

Uses the active workspace's default sandbox group unless `--group` is provided.
Without `--confirm`, this command previews what would be deleted and makes no
changes. A snapshot that is still being created cannot be deleted yet. An
expired snapshot is reported as not found.

*Usage:*

```bash
render ea sandboxes snapshots delete <snapshotId>
```

*Examples:*

```bash
# Preview deletion (no changes made)
render ea sandboxes snapshots delete snp-abc123

# Delete the snapshot
render ea sandboxes snapshots delete snp-abc123 --confirm

# Delete a snapshot in a specific group
render ea sandboxes snapshots delete snp-abc123 --group sbg-abc123 --confirm

# JSON output
render ea sandboxes snapshots delete snp-abc123 --confirm --output json
```

*Options:*

[Global options](#global-options), plus:

| Option | Description |
| --- | --- |
| `--group` | Sandbox group the snapshot belongs to (defaults to the active workspace's default group) |