Sandbox CLI

Sandbox CLI reference

Sandbox commands live under the sbx group of the unified orkestr 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.

terminal

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.

terminal

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

Quick start

terminal

# 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