> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bonya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandboxes

> list, get, delete, and exec — inspecting and managing sandboxes you already have

This page covers the **Sandboxes** command group: `list`, `get`, `delete`, and `exec`. For creating a sandbox, see [`create`](https://docs.bonya.ai/cli-reference/create); for a shell, see [`console`](https://docs.bonya.ai/cli-reference/console).

## `bonya list`

> [!NOTE]
>
> Aliases: `ls`, `l`

Lists sandboxes.

```shell theme={null}
bonya list [--state running,suspended] [--name web] [--limit 20]
```

| Flag | Default | Description |
| - | - | - |
| `--state` | (all) | Comma-separated state filter. Valid values: `creating`, `running`, `suspending`, `suspended`, `resuming`, `failed`. |
| `--name` | (all) | Only list sandboxes with this exact (case-sensitive) name. |
| `--limit` | `0` (unlimited) | Maximum number of sandboxes to return. |

```shell List everything theme={null}
bonya list
```

```shell Only running sandboxes theme={null}
bonya list --state running
```

```shell Multiple states theme={null}
bonya list --state running,suspended
```

```shell As JSON, filtered with jq theme={null}
bonya list --json | jq -r '.[] | select(.last_observed_status=="running") | .id'
```

On a real terminal, `bonya list` looks like this:

## `bonya get [sandbox]`

> [!NOTE]
>
> Aliases: `show`, `info`

Shows one sandbox's details — id, name, status, template, version, and operation id.

```shell theme={null}
bonya get web
bonya get sbx-4f1c9a2b3c4d5e6f7a8b9c0d1e2f3a4b
bonya get                # picker
```

| Flag | Default | Description |
| - | - | - |
| `--by-name` | `false` | Treat the argument as a name even if it looks like an id. |

## `bonya delete [sandbox]`

> [!NOTE]
>
> Aliases: `rm`, `del`

Tears down a sandbox. This is not reversible.

```shell theme={null}
bonya delete web
bonya delete web --force
bonya delete                # picker
```

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Skip the confirmation prompt. |
| `--by-name` | `false` | Treat the argument as a name even if it looks like an id. |

> [!NOTE]
>
> On an interactive terminal, `delete` asks "Delete \<name>? This cannot be undone." before proceeding, unless `--force` is passed. Non-interactively there is no prompt at all — naming the sandbox on the command line is itself the confirmation, so `--force` has no effect there.

Deleting an already-deleted sandbox is not an error — the result reports `Already deleted: <id>` instead of `Deleted <id>`.

## `bonya exec [sandbox] [flags] -- cmd [args...]`

> [!NOTE]
>
> Aliases: `run`, `x`

Runs a command in a sandbox and exits with the remote command's exit code.

```shell theme={null}
bonya exec web -- ls /workspace
bonya exec -- ls /workspace          # prompts for the sandbox
bonya exec                           # prompts for both sandbox and command
```

`exec` takes any number of arguments, so it's valid to run it with **no** sandbox and **no** command — it prompts for whichever is missing (interactively only; see [non-interactive behavior](https://docs.bonya.ai/cli-reference/configuration.md#non-interactive-behavior)).

| Flag | Default | Description |
| - | - | - |
| `--env` | — | Environment variable in `KEY=VALUE` form. Repeatable. |
| `--cwd` | — | Remote working directory. |
| `--tty` | `false` | Allocate a pseudo-TTY and forward stdin interactively. |
| `--cols` | terminal size | TTY columns. Only meaningful with `--tty`. |
| `--rows` | terminal size | TTY rows. Only meaningful with `--tty`. |
| `--by-name` | `false` | Treat the sandbox argument as a name even if it looks like an id. |

With `--tty` and no explicit `--cols`/`--rows`, the terminal size defaults to your own and resizes propagate as you resize your window. Without `--tty`, stdout and stderr are captured and printed separately (buffered, not streamed).

> [!WARNING]
>
> A remote command that exits non-zero is a **faithful result**, not a CLI failure — `bonya exec`'s own exit code mirrors it exactly, with no extra error message. Don't treat a non-zero `bonya exec` exit code as a CLI bug; check what the remote command itself reported.

```shell Basic command theme={null}
bonya exec web -- printf 'hello\n'
```

```shell With an environment variable theme={null}
bonya exec web --env MODE=development -- python3 -c 'import os; print(os.environ["MODE"])'
```

```shell Fully interactive TTY theme={null}
bonya exec web --tty -- bash
```

```shell Piped stdin still works theme={null}
echo hi | bonya exec web --tty -- cat
```

```shell Working directory theme={null}
bonya exec web --cwd /workspace -- pwd
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.