# Sandbox CLI reference

Sandbox commands live under the `sbx` group of the unified [orkestr CLI](https://orkestr.eu/docs/cli) - the same `orkestr` binary that deploys your apps. It is built for scripts and agent harnesses: `exec` streams output and inherits the exit code, and read commands take `--json` for machine-readable output.

## Install

The CLI ships as the `orkestr-cli` package on PyPI (Python 3.10+). One install, one binary for both deploys and sandboxes.

```bash
pip install orkestr-cli   # requires Python 3.10+
```

## Authentication

Run `orkestr login` once with an API token from the console - the same login authenticates sandbox commands. A default-scoped token works, or mint one scoped to `sandboxes:read` and `sandboxes:write`. Point at a different host with `orkestr set-url` or the `ORKESTR_API_URL` environment variable.

```bash
orkestr login                      # paste an API token from the console
orkestr sbx list                   # the same login drives sandboxes
```

## Quick start

```bash
# create a Python sandbox with restricted egress
orkestr sbx create python-3.12 --network restricted

# run a one-off command, stream its output, inherit its exit code
orkestr sbx exec sbx_01HXYZ... "python -c 'print(2**10)'"

# park it between turns, then pick it back up
orkestr sbx pause sbx_01HXYZ...
orkestr sbx resume sbx_01HXYZ...

# done
orkestr sbx kill sbx_01HXYZ...
```

## Create and inspect

`orkestr sbx create [template]`

Create a sandbox and print its id. Template defaults to `python-3.12`. Flags: `--size small|medium|large`, `--network off|restricted|open`, `--region <code>`, `--timeout <seconds>`, `--pause-on-timeout`, `--auto-resume`.

```
$ orkestr sbx create python-3.12 --network restricted
created sbx_01HXYZ...  (python-3.12, restricted, fsn1)
expires 2026-07-17T12:10:00.000Z
```

`orkestr sbx list`

List your sandboxes as a table. Filter with `--status running|paused`.

```
$ orkestr sbx list
ID                              STATUS     TEMPLATE          REGION  NETWORK
sbx_01HXYZ...                   running    python-3.12       fsn1    restricted
```

`orkestr sbx info <id>`

Show one sandbox: status, template, region, network, expiry.

## Run code

`orkestr sbx exec <id> <cmd...>`

Run a command in the sandbox, stream stdout/stderr, and exit with the command's own exit code - so it composes in scripts and CI. Flags: `--cwd <dir>`, `--timeout <seconds>`.

```
$ orkestr sbx exec sbx_01HXYZ... "python -c 'print(2**10)'"
1024
```

`orkestr sbx shell <id>`

Line-buffered interactive exec loop against a running sandbox. Type commands, each runs via exec; Ctrl-D, "exit", or "quit" leaves.

```
$ orkestr sbx shell sbx_01HXYZ...
connected to sbx_01HXYZ... (python-3.12). Type commands; Ctrl-D to exit.
sbx_01HXYZ... $ whoami
root
```

`orkestr sbx metrics <id>`

Live CPU / memory usage plus cumulative lifetime billing (vCPU-seconds, GB-seconds).

```
$ orkestr sbx metrics sbx_01HXYZ...
status        running
cpu           3% of 1 core(s)
memory        84 / 1024 MB
lifetime      12.4 vCPU-s, 6.1 GB-s
```

## Lifecycle

`orkestr sbx pause <id>`

Snapshot the sandbox and stop the meter. Filesystem and process state are preserved for resume.

`orkestr sbx resume <id>`

Resume a paused sandbox back to running.

`orkestr sbx kill <id>`

Terminate the sandbox and release its resources.

## Global flags

- `--json` - machine-readable JSON output on read commands (`list`, `info`, `metrics`, `create`). Works per command (`orkestr sbx list --json`) or globally (`orkestr --json sbx list`)
- `--help` - usage for any command or group
- `--version` - print the CLI version
- `--api-url` / `ORKESTR_API_URL` - override the API host

> **See also**
>
> The CLI is a wrapper - anything it can't do, the [Python](https://orkestr.eu/docs/sandboxes/python-sdk) and [JS](https://orkestr.eu/docs/sandboxes/js-sdk) SDKs and the [REST API](https://orkestr.eu/docs/sandboxes/api-reference) can. The full CLI (deploys, projects, functions and more) is on the [CLI reference](https://orkestr.eu/docs/cli); for editor and agent integrations, see the [MCP server](https://orkestr.eu/docs/sandboxes/mcp).