openshell sandbox

Alias: sb Manage sandbox lifecycle — create, connect to, list, delete, and inspect sandboxes.

openshell sandbox create

Create a new sandbox. If no gateway is active, a local gateway is bootstrapped automatically.

openshell sandbox create [OPTIONS] [-- COMMAND]

-- COMMAND

string

Command to run inside the sandbox after it is ready. Defaults to an interactive shell when omitted. Everything after -- is passed verbatim to the container.

--name

string

Sandbox name. Auto-generated when omitted.

--from

string

Sandbox source. Accepts:

A community sandbox name (e.g., openclaw) — resolved to ghcr.io/nvidia/openshell-community/sandboxes/<name>:latest.
A path to a local Dockerfile or directory containing one — the image is built and pushed automatically.
A full container image reference (e.g., myregistry.com/img:tag).

Override the community registry prefix with OPENSHELL_COMMUNITY_REGISTRY.

--gpu

boolean

Request GPU resources. Auto-bootstraps a GPU-enabled gateway if none is active. GPU intent is also inferred automatically for community images with gpu in the name.

--provider

string

Provider name to attach to this sandbox. Repeatable: --provider openai --provider anthropic.

--policy

string

Path to a custom sandbox policy YAML file. Overrides the built-in default and the OPENSHELL_SANDBOX_POLICY env var.

--upload

string

Upload local files into the sandbox before the command runs. Format: <LOCAL_PATH>[:<SANDBOX_PATH>]. When SANDBOX_PATH is omitted, files land in /sandbox. .gitignore rules are applied by default.

--no-git-ignore

boolean

Disable .gitignore filtering for --upload. Uploads all files, including those matched by .gitignore.

--forward

string

Forward a local port to the sandbox before the command starts. Format: [bind_address:]port (e.g., 8080 or 0.0.0.0:8080). Keeps the sandbox alive.

--editor

string

Launch a remote editor after the sandbox is ready. Valid values: vscode, cursor. Keeps the sandbox alive and installs the OpenShell-managed SSH config entry.

--no-keep

boolean

Delete the sandbox after the initial command or shell exits. Conflicts with --editor and --forward.

--tty

boolean

Force pseudo-terminal allocation for the remote command, even when auto-detection would skip it.

--no-tty

boolean

Disable pseudo-terminal allocation.

--remote

string

SSH destination for remote bootstrap (e.g., user@hostname). Only used when no gateway exists yet; ignored if a gateway is already active.

--ssh-key

string

Path to SSH private key for remote bootstrap.

--no-bootstrap

boolean

Never auto-bootstrap a gateway. Errors immediately if no gateway is available.

--auto-providers

boolean

Auto-create missing providers from local environment credentials without prompting.

--no-auto-providers

boolean

Never auto-create providers. Errors if required providers are missing.

Examples

# Create a sandbox and launch Claude
openshell sandbox create -- claude

# Create with a named community image
openshell sandbox create --from openclaw

# Create from a local Dockerfile
openshell sandbox create --from ./my-agent

# Create with a custom policy and a provider attached
openshell sandbox create --policy policy.yaml --provider openai -- opencode

# Create on a remote host (bootstraps gateway over SSH)
openshell sandbox create --remote user@10.0.0.5 -- claude

# Create, forward port 8080, and keep alive
openshell sandbox create --forward 8080

# Create a temporary sandbox that cleans up on exit
openshell sandbox create --no-keep -- python script.py

openshell sandbox connect

SSH into a running sandbox. When no name is given, reconnects to the last-used sandbox.

openshell sandbox connect [NAME] [OPTIONS]

NAME

string

Sandbox name. Defaults to the last-used sandbox.

--editor

string

Open a remote editor instead of an interactive shell. Valid values: vscode, cursor. Installs the OpenShell-managed SSH config entry if needed.

Examples

# Connect to a sandbox by name
openshell sandbox connect my-sandbox

# Reconnect to the last-used sandbox
openshell sandbox connect

# Open VSCode Remote-SSH
openshell sandbox connect my-sandbox --editor vscode

openshell sandbox list

List sandboxes on the active gateway.

openshell sandbox list [OPTIONS]

--limit

integer

default:"100"

Maximum number of sandboxes to return.

--offset

integer

default:"0"

Offset into the sandbox list for pagination.

--ids

boolean

Print only sandbox IDs, one per line. Conflicts with --names.

--names

boolean

Print only sandbox names, one per line. Conflicts with --ids.

Examples

openshell sandbox list
openshell sandbox list --names
openshell sandbox list --limit 20 --offset 40

openshell sandbox get

Fetch details for a single sandbox.

openshell sandbox get [NAME]

NAME

string

Sandbox name. Defaults to the last-used sandbox.

openshell sandbox delete

Delete one or more sandboxes by name.

openshell sandbox delete NAME [NAME...] [OPTIONS]

NAME

string

required

One or more sandbox names to delete. Required unless --all is set.

--all

boolean

Delete all sandboxes. Conflicts with positional NAME arguments.

Examples

openshell sandbox delete my-sandbox
openshell sandbox delete sandbox-a sandbox-b
openshell sandbox delete --all

openshell sandbox upload

Upload local files to a sandbox.

openshell sandbox upload NAME LOCAL_PATH [DEST] [OPTIONS]

NAME

string

required

Sandbox name.

LOCAL_PATH

string

required

Local file or directory to upload.

DEST

string

Destination path in the sandbox. Defaults to /sandbox.

--no-git-ignore

boolean

Upload everything, ignoring .gitignore rules.

openshell sandbox download

Download files from a sandbox to the local machine.

openshell sandbox download NAME SANDBOX_PATH [DEST]

NAME

string

required

Sandbox name.

SANDBOX_PATH

string

required

Path inside the sandbox to download.

DEST

string

Local destination. Defaults to ..

openshell sandbox ssh-config

Print an SSH Host block suitable for appending to ~/.ssh/config. Enables tools like VSCode Remote-SSH to connect to the sandbox by name.

openshell sandbox ssh-config [NAME]

NAME

string

Sandbox name. Defaults to the last-used sandbox.

openshell forward

Alias: fwd Manage port forwarding to a sandbox. Useful for exposing a web server, database, or any service running inside the sandbox to your local machine.

openshell forward start

Forward a local port to a running sandbox.

openshell forward start PORT [NAME] [OPTIONS]

PORT

string

required

Port to forward. Format: [bind_address:]port (e.g., 8080 or 0.0.0.0:8080).

NAME

string

Sandbox name. Defaults to the last-used sandbox.

-d / --background

boolean

Run the forward in the background and exit immediately.

# Forward port 8080 to the last-used sandbox
openshell forward start 8080

# Forward port 3000 to a named sandbox
openshell forward start 3000 my-sandbox

# Run in the background
openshell forward start 8080 my-sandbox -d

openshell forward stop

Stop a background port forward.

openshell forward stop PORT [NAME]

PORT

integer

required

Port that was forwarded.

NAME

string

Sandbox name. Auto-detected from active forwards if omitted.

openshell forward stop 8080
openshell forward stop 8080 my-sandbox

openshell forward list

List all active port forwards.

openshell forward list

You can also forward a port at sandbox creation time using --forward on openshell sandbox create:

openshell sandbox create --forward 8080 -- claude

openshell logs

Alias: lg View logs from a sandbox. Combines gateway and sandbox log sources.

openshell logs [NAME] [OPTIONS]

NAME

string

Sandbox name. Defaults to the last-used sandbox.

-n

integer

default:"200"

Number of log lines to return.

--tail

boolean

Stream live logs (follow mode).

--since

string

Show only logs from this duration ago. Accepts Go-style durations: 5m, 1h, 30s.

--source

string

default:"all"

Filter by log source. Valid values: gateway, sandbox, all. Repeatable for multiple sources: --source gateway --source sandbox.

--level

string

Minimum log level to display. Valid values: error, warn, info, debug, trace. Defaults to showing all levels.

Examples

# Fetch last 200 lines from the last-used sandbox
openshell logs

# Stream live logs from a named sandbox
openshell logs my-sandbox --tail

# Show only the last 5 minutes of logs
openshell logs --since 5m

# Show only sandbox-sourced debug logs
openshell logs my-sandbox --source sandbox --level debug

openshell term

Launch the OpenShell interactive TUI — a real-time, keyboard-driven dashboard for gateways, sandboxes, and providers.

openshell term [OPTIONS]

--theme

string

default:"auto"

Color theme. Valid values: auto, dark, light. auto detects the terminal background. Also reads OPENSHELL_THEME.

Keyboard shortcuts

Key	Action
`Tab` / `Shift+Tab`	Cycle focus between panels
`j` / `↓`	Move cursor down
`k` / `↑`	Move cursor up
`h` / `l` / `←` / `→`	Switch tabs within a panel
`Enter`	Select / open detail
`c`	Open create form (providers panel)
`u`	Open update form (providers panel)
`d`	Delete selected item
`:`	Enter command mode
`q`	Quit
`Ctrl+C`	Force quit

The TUI auto-refreshes every two seconds. Logs stream live when viewing a sandbox’s log panel.

openshell term requires an active gateway. Run openshell gateway start first if you have not deployed one.

openshell settings

Manage per-sandbox and gateway-global settings key/value pairs.

openshell settings <subcommand> [OPTIONS]

openshell settings get

Show effective settings for a sandbox or the gateway-global scope.

openshell settings get [NAME] [OPTIONS]

NAME

string

Sandbox name. Defaults to the last-used sandbox.

--global

boolean

Show gateway-global settings instead of sandbox-level settings.

--json

boolean

Output settings as JSON.

openshell settings set

Set a single setting key for a sandbox or gateway-global scope.

openshell settings set [NAME] --key KEY --value VALUE [OPTIONS]

NAME

string

Sandbox name. Defaults to the last-used sandbox.

--key

string

required

Setting key.

--value

string

required

Setting value. Bool keys accept true/false/yes/no/1/0.

--global

boolean

Apply at gateway-global scope.

--yes

boolean

Skip the confirmation prompt for global setting updates.

openshell settings delete

Delete a setting key.

openshell settings delete [NAME] --key KEY [OPTIONS]

NAME

string

Sandbox name. Defaults to the last-used sandbox.

--key

string

required

Setting key to delete.

--global

boolean

Delete at gateway-global scope.

--yes

boolean

Skip the confirmation prompt.

Examples

# Show settings for a sandbox
openshell settings get my-sandbox

# Show gateway-global settings
openshell settings get --global

# Set a setting at sandbox scope
openshell settings set my-sandbox --key log_level --value debug

# Set a setting at gateway-global scope
openshell settings set --global --key log_level --value warn

# Delete a global setting
openshell settings delete --global --key log_level

Documentation Index

​openshell sandbox

​openshell sandbox create

​Examples

​openshell sandbox connect

​Examples

​openshell sandbox list

​Examples

​openshell sandbox get

​openshell sandbox delete

​Examples

​openshell sandbox upload

​openshell sandbox download

​openshell sandbox ssh-config

​openshell forward

​openshell forward start

​openshell forward stop

​openshell forward list

​openshell logs

​Examples

​openshell term

​Keyboard shortcuts

​openshell settings

​openshell settings get

​openshell settings set

​openshell settings delete

​Examples

openshell sandbox

openshell sandbox create

Examples

openshell sandbox connect

Examples

openshell sandbox list

Examples

openshell sandbox get

openshell sandbox delete

Examples

openshell sandbox upload

openshell sandbox download

openshell sandbox ssh-config

openshell forward

openshell forward start

openshell forward stop

openshell forward list

openshell logs

Examples

openshell term

Keyboard shortcuts

openshell settings

openshell settings get

openshell settings set

openshell settings delete

Examples