> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/NVIDIA/OpenShell/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
openshell sandbox create [OPTIONS] [-- COMMAND]
```

<ParamField body="-- COMMAND" type="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.
</ParamField>

<ParamField body="--name" type="string">
  Sandbox name. Auto-generated when omitted.
</ParamField>

<ParamField body="--from" type="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`.
</ParamField>

<ParamField body="--gpu" type="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.
</ParamField>

<ParamField body="--provider" type="string">
  Provider name to attach to this sandbox. Repeatable: `--provider openai --provider anthropic`.
</ParamField>

<ParamField body="--policy" type="string">
  Path to a custom sandbox policy YAML file. Overrides the built-in default and the `OPENSHELL_SANDBOX_POLICY` env var.
</ParamField>

<ParamField body="--upload" type="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.
</ParamField>

<ParamField body="--no-git-ignore" type="boolean">
  Disable `.gitignore` filtering for `--upload`. Uploads all files, including those matched by `.gitignore`.
</ParamField>

<ParamField body="--forward" type="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.
</ParamField>

<ParamField body="--editor" type="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.
</ParamField>

<ParamField body="--no-keep" type="boolean">
  Delete the sandbox after the initial command or shell exits. Conflicts with `--editor` and `--forward`.
</ParamField>

<ParamField body="--tty" type="boolean">
  Force pseudo-terminal allocation for the remote command, even when auto-detection would skip it.
</ParamField>

<ParamField body="--no-tty" type="boolean">
  Disable pseudo-terminal allocation.
</ParamField>

<ParamField body="--remote" type="string" group="BOOTSTRAP FLAGS">
  SSH destination for remote bootstrap (e.g., `user@hostname`). Only used when no gateway exists yet; ignored if a gateway is already active.
</ParamField>

<ParamField body="--ssh-key" type="string" group="BOOTSTRAP FLAGS">
  Path to SSH private key for remote bootstrap.
</ParamField>

<ParamField body="--no-bootstrap" type="boolean" group="BOOTSTRAP FLAGS">
  Never auto-bootstrap a gateway. Errors immediately if no gateway is available.
</ParamField>

<ParamField body="--auto-providers" type="boolean">
  Auto-create missing providers from local environment credentials without prompting.
</ParamField>

<ParamField body="--no-auto-providers" type="boolean">
  Never auto-create providers. Errors if required providers are missing.
</ParamField>

### Examples

```bash theme={null}
# 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.

```bash theme={null}
openshell sandbox connect [NAME] [OPTIONS]
```

<ParamField body="NAME" type="string">
  Sandbox name. Defaults to the last-used sandbox.
</ParamField>

<ParamField body="--editor" type="string">
  Open a remote editor instead of an interactive shell. Valid values: `vscode`, `cursor`. Installs the OpenShell-managed SSH config entry if needed.
</ParamField>

### Examples

```bash theme={null}
# 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.

```bash theme={null}
openshell sandbox list [OPTIONS]
```

<ParamField body="--limit" type="integer" default="100">
  Maximum number of sandboxes to return.
</ParamField>

<ParamField body="--offset" type="integer" default="0">
  Offset into the sandbox list for pagination.
</ParamField>

<ParamField body="--ids" type="boolean">
  Print only sandbox IDs, one per line. Conflicts with `--names`.
</ParamField>

<ParamField body="--names" type="boolean">
  Print only sandbox names, one per line. Conflicts with `--ids`.
</ParamField>

### Examples

```bash theme={null}
openshell sandbox list
openshell sandbox list --names
openshell sandbox list --limit 20 --offset 40
```

***

## openshell sandbox get

Fetch details for a single sandbox.

```bash theme={null}
openshell sandbox get [NAME]
```

<ParamField body="NAME" type="string">
  Sandbox name. Defaults to the last-used sandbox.
</ParamField>

***

## openshell sandbox delete

Delete one or more sandboxes by name.

```bash theme={null}
openshell sandbox delete NAME [NAME...] [OPTIONS]
```

<ParamField body="NAME" type="string" required>
  One or more sandbox names to delete. Required unless `--all` is set.
</ParamField>

<ParamField body="--all" type="boolean">
  Delete all sandboxes. Conflicts with positional `NAME` arguments.
</ParamField>

### Examples

```bash theme={null}
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.

```bash theme={null}
openshell sandbox upload NAME LOCAL_PATH [DEST] [OPTIONS]
```

<ParamField body="NAME" type="string" required>
  Sandbox name.
</ParamField>

<ParamField body="LOCAL_PATH" type="string" required>
  Local file or directory to upload.
</ParamField>

<ParamField body="DEST" type="string">
  Destination path in the sandbox. Defaults to `/sandbox`.
</ParamField>

<ParamField body="--no-git-ignore" type="boolean">
  Upload everything, ignoring `.gitignore` rules.
</ParamField>

***

## openshell sandbox download

Download files from a sandbox to the local machine.

```bash theme={null}
openshell sandbox download NAME SANDBOX_PATH [DEST]
```

<ParamField body="NAME" type="string" required>
  Sandbox name.
</ParamField>

<ParamField body="SANDBOX_PATH" type="string" required>
  Path inside the sandbox to download.
</ParamField>

<ParamField body="DEST" type="string">
  Local destination. Defaults to `.`.
</ParamField>

***

## 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.

```bash theme={null}
openshell sandbox ssh-config [NAME]
```

<ParamField body="NAME" type="string">
  Sandbox name. Defaults to the last-used sandbox.
</ParamField>

***

## 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.

```bash theme={null}
openshell forward start PORT [NAME] [OPTIONS]
```

<ParamField body="PORT" type="string" required>
  Port to forward. Format: `[bind_address:]port` (e.g., `8080` or `0.0.0.0:8080`).
</ParamField>

<ParamField body="NAME" type="string">
  Sandbox name. Defaults to the last-used sandbox.
</ParamField>

<ParamField body="-d / --background" type="boolean">
  Run the forward in the background and exit immediately.
</ParamField>

```bash theme={null}
# 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.

```bash theme={null}
openshell forward stop PORT [NAME]
```

<ParamField body="PORT" type="integer" required>
  Port that was forwarded.
</ParamField>

<ParamField body="NAME" type="string">
  Sandbox name. Auto-detected from active forwards if omitted.
</ParamField>

```bash theme={null}
openshell forward stop 8080
openshell forward stop 8080 my-sandbox
```

### openshell forward list

List all active port forwards.

```bash theme={null}
openshell forward list
```

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

  ```bash theme={null}
  openshell sandbox create --forward 8080 -- claude
  ```
</Tip>

***

## openshell logs

Alias: `lg`

View logs from a sandbox. Combines gateway and sandbox log sources.

```bash theme={null}
openshell logs [NAME] [OPTIONS]
```

<ParamField body="NAME" type="string">
  Sandbox name. Defaults to the last-used sandbox.
</ParamField>

<ParamField body="-n" type="integer" default="200">
  Number of log lines to return.
</ParamField>

<ParamField body="--tail" type="boolean">
  Stream live logs (follow mode).
</ParamField>

<ParamField body="--since" type="string">
  Show only logs from this duration ago. Accepts Go-style durations: `5m`, `1h`, `30s`.
</ParamField>

<ParamField body="--source" type="string" default="all">
  Filter by log source. Valid values: `gateway`, `sandbox`, `all`. Repeatable for multiple sources: `--source gateway --source sandbox`.
</ParamField>

<ParamField body="--level" type="string">
  Minimum log level to display. Valid values: `error`, `warn`, `info`, `debug`, `trace`. Defaults to showing all levels.
</ParamField>

### Examples

```bash theme={null}
# 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.

```bash theme={null}
openshell term [OPTIONS]
```

<ParamField body="--theme" type="string" default="auto">
  Color theme. Valid values: `auto`, `dark`, `light`. `auto` detects the terminal background. Also reads `OPENSHELL_THEME`.
</ParamField>

### 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.

<Note>
  `openshell term` requires an active gateway. Run `openshell gateway start` first if you have not deployed one.
</Note>

***

## openshell settings

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

```bash theme={null}
openshell settings <subcommand> [OPTIONS]
```

### openshell settings get

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

```bash theme={null}
openshell settings get [NAME] [OPTIONS]
```

<ParamField body="NAME" type="string">
  Sandbox name. Defaults to the last-used sandbox.
</ParamField>

<ParamField body="--global" type="boolean">
  Show gateway-global settings instead of sandbox-level settings.
</ParamField>

<ParamField body="--json" type="boolean">
  Output settings as JSON.
</ParamField>

### openshell settings set

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

```bash theme={null}
openshell settings set [NAME] --key KEY --value VALUE [OPTIONS]
```

<ParamField body="NAME" type="string">
  Sandbox name. Defaults to the last-used sandbox.
</ParamField>

<ParamField body="--key" type="string" required>
  Setting key.
</ParamField>

<ParamField body="--value" type="string" required>
  Setting value. Bool keys accept `true`/`false`/`yes`/`no`/`1`/`0`.
</ParamField>

<ParamField body="--global" type="boolean">
  Apply at gateway-global scope.
</ParamField>

<ParamField body="--yes" type="boolean">
  Skip the confirmation prompt for global setting updates.
</ParamField>

### openshell settings delete

Delete a setting key.

```bash theme={null}
openshell settings delete [NAME] --key KEY [OPTIONS]
```

<ParamField body="NAME" type="string">
  Sandbox name. Defaults to the last-used sandbox.
</ParamField>

<ParamField body="--key" type="string" required>
  Setting key to delete.
</ParamField>

<ParamField body="--global" type="boolean">
  Delete at gateway-global scope.
</ParamField>

<ParamField body="--yes" type="boolean">
  Skip the confirmation prompt.
</ParamField>

### Examples

```bash theme={null}
# 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
```