openshell sandbox

CLI reference for sandbox lifecycle commands: create, connect, list, delete, get, upload, download, and ssh-config. Includes openshell forward, openshell logs, and openshell term.

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