OpenShell CLI Reference#

Environment Variables#

Variable	Description
`OPENSHELL_GATEWAY`	Gateway name to operate on (resolved from stored metadata).
`OPENSHELL_GATEWAY_ENDPOINT`	Gateway endpoint URL (e.g. https://gateway.example.com). Connects directly without looking up gateway metadata.

Command Tree#

openshell
├── sandbox
│   ├── create [COMMAND]
│   ├── get [NAME]
│   ├── list
│   ├── delete [NAME]
│   ├── connect [NAME]
│   ├── upload <NAME> <LOCAL_PATH> [DEST]
│   ├── download <NAME> <SANDBOX_PATH> [DEST]
│   └── ssh-config [NAME]
├── forward
│   ├── start <PORT> [NAME]
│   ├── stop <PORT> [NAME]
│   └── list
├── logs [NAME]
├── policy
│   ├── set [NAME]
│   ├── get [NAME]
│   └── list [NAME]
├── provider
│   ├── create
│   ├── get <NAME>
│   ├── list
│   ├── update <NAME>
│   └── delete <NAME>
├── gateway
│   ├── start
│   ├── stop
│   ├── destroy
│   ├── add <ENDPOINT>
│   ├── login [NAME]
│   ├── select [NAME]
│   └── info
├── status
├── inference
│   ├── set
│   ├── update
│   └── get
├── term
└── completions <SHELL>

Sandbox Commands#

Manage sandboxes.

`openshell sandbox create [COMMAND]`#

Create a sandbox.

Flag	Description
`--name <NAME>`	Optional sandbox name (auto-generated when omitted).
`--from <FROM>`	Sandbox source: a community sandbox name (e.g., `openclaw`), a path to a Dockerfile or directory containing one, or a full container image reference (e.g., `myregistry.com/img:tag`).
`--upload <UPLOAD>`	Upload local files into the sandbox before running.
`--no-git-ignore`	Disable `.gitignore` filtering for `--upload`.
`--no-keep`	Delete the sandbox after the initial command or shell exits.
`--editor <EDITOR>`	Launch a remote editor after the sandbox is ready. Keeps the sandbox alive and installs OpenShell-managed SSH config.
`--remote <REMOTE>`	SSH destination for remote bootstrap (e.g., user@hostname). Only used when no cluster exists yet; ignored if a cluster is already active.
`--ssh-key <SSH_KEY>`	Path to SSH private key for remote bootstrap.
`--provider <PROVIDERS>`	Provider names to attach to this sandbox.
`--policy <POLICY>`	Path to a custom sandbox policy YAML file. Overrides the built-in default and the `OPENSHELL_SANDBOX_POLICY` env var.
`--forward <FORWARD>`	Forward a local port to the sandbox before the initial command or shell starts. Keeps the sandbox alive.
`--tty`	Allocate a pseudo-terminal for the remote command. Defaults to auto-detection (on when stdin and stdout are terminals). Use –tty to force a PTY even when auto-detection fails, or –no-tty to disable.
`--no-tty`	Disable pseudo-terminal allocation.
`--no-bootstrap`	Never bootstrap a gateway automatically; error if none is available.
`--auto-providers`	Auto-create missing providers from local credentials.
`--no-auto-providers`	Never auto-create providers; error if required providers are missing.
`[COMMAND]`	Command to run after “–” (defaults to an interactive shell).

`openshell sandbox get [NAME]`#

Fetch a sandbox by name.

Flag	Description
`[NAME]`	Sandbox name (defaults to last-used sandbox).

`openshell sandbox list`#

List sandboxes.

Flag	Default	Description
`--limit <LIMIT>`	`100`	Maximum number of sandboxes to return.
`--offset <OFFSET>`	`0`	Offset into the sandbox list.
`--ids`		Print only sandbox ids (one per line).
`--names`		Print only sandbox names (one per line).

`openshell sandbox delete [NAME]`#

Delete a sandbox by name.

Flag	Description
`[NAME]`	Sandbox names.
`--all`	Delete all sandboxes.

`openshell sandbox connect [NAME]`#

Connect to a sandbox.

When no name is given, reconnects to the last-used sandbox.

Flag	Description
`[NAME]`	Sandbox name (defaults to last-used sandbox).
`--editor <EDITOR>`	Launch a remote editor instead of an interactive shell. Installs OpenShell-managed SSH config if needed.

`openshell sandbox upload <NAME> <LOCAL_PATH> [DEST]`#

Upload local files to a sandbox.

Flag	Description
`<NAME>`	Sandbox name.
`<LOCAL_PATH>`	Local path to upload.
`[DEST]`	Destination path in the sandbox (defaults to `/sandbox`).
`--no-git-ignore`	Disable `.gitignore` filtering (uploads everything).

`openshell sandbox download <NAME> <SANDBOX_PATH> [DEST]`#

Download files from a sandbox.

Flag	Description
`<NAME>`	Sandbox name.
`<SANDBOX_PATH>`	Sandbox path to download.
`[DEST]`	Local destination (defaults to `.`).

`openshell sandbox ssh-config [NAME]`#

Print an SSH config entry for a sandbox.

Outputs a Host block suitable for appending to ~/.ssh/config, enabling tools like VSCode Remote-SSH to connect to the sandbox.

Flag	Description
`[NAME]`	Sandbox name (defaults to last-used sandbox).

Forward Commands#

Manage port forwarding to a sandbox.

`openshell forward start <PORT> [NAME]`#

Start forwarding a local port to a sandbox.

Flag	Description
`<PORT>`	Port to forward (used as both local and remote port).
`[NAME]`	Sandbox name (defaults to last-used sandbox).
`-d`, `--background`	Run the forward in the background and exit immediately.

`openshell forward stop <PORT> [NAME]`#

Stop a background port forward.

Flag	Description
`<PORT>`	Port that was forwarded.
`[NAME]`	Sandbox name (defaults to last-used sandbox).

`openshell forward list`#

List active port forwards.

Policy Commands#

Manage sandbox policy.

`openshell policy set [NAME]`#

Update policy on a live sandbox.

Flag	Default	Description
`[NAME]`		Sandbox name (defaults to last-used sandbox).
`--policy <POLICY>`		Path to the policy YAML file.
`--wait`		Wait for the sandbox to load the policy.
`--timeout <TIMEOUT>`	`60`	Timeout for –wait in seconds.

`openshell policy get [NAME]`#

Show current active policy for a sandbox.

Flag	Default	Description
`[NAME]`		Sandbox name (defaults to last-used sandbox).
`--rev <REV>`	`0`	Show a specific policy revision (default: latest).
`--full`		Print the full policy as YAML.

`openshell policy list [NAME]`#

List policy history for a sandbox.

Flag	Default	Description
`[NAME]`		Sandbox name (defaults to last-used sandbox).
`--limit <LIMIT>`	`20`	Maximum number of revisions to return.

Provider Commands#

Manage provider configuration.

`openshell provider create`#

Create a provider config.

Flag	Description
`--name <NAME>`	Provider name.
`--type <PROVIDER_TYPE>`	Provider type.
`--from-existing`	Load provider credentials/config from existing local state.
`--credential <KEY[=VALUE]>`	Provider credential pair (`KEY=VALUE`) or env lookup key (`KEY`).
`--config <KEY=VALUE>`	Provider config key/value pair.

`openshell provider get <NAME>`#

Fetch a provider by name.

Flag	Description
`<NAME>`	Provider name.

`openshell provider list`#

List providers.

Flag	Default	Description
`--limit <LIMIT>`	`100`	Maximum number of providers to return.
`--offset <OFFSET>`	`0`	Offset into the provider list.
`--names`		Print only provider names, one per line.

`openshell provider update <NAME>`#

Update an existing provider’s credentials or config.

Flag	Description
`<NAME>`	Provider name.
`--from-existing`	Re-discover credentials from existing local state (e.g. env vars, config files).
`--credential <KEY[=VALUE]>`	Provider credential pair (`KEY=VALUE`) or env lookup key (`KEY`).
`--config <KEY=VALUE>`	Provider config key/value pair.

`openshell provider delete <NAME>`#

Delete providers by name.

Flag	Description
`<NAME>`	Provider names.

Gateway Commands#

Manage the gateway lifecycle.

`openshell gateway start`#

Deploy/start the gateway.

Flag	Default	Description
`--name <NAME>`	`openshell`	Gateway name. Env: `OPENSHELL_GATEWAY`.
`--remote <REMOTE>`		SSH destination for remote deployment (e.g., user@hostname).
`--ssh-key <SSH_KEY>`		Path to SSH private key for remote deployment.
`--port <PORT>`	`8080`	Host port to map to the gateway (default: 8080).
`--gateway-host <GATEWAY_HOST>`		Override the gateway host written into cluster metadata.
`--recreate`		Destroy and recreate the gateway from scratch if one already exists.
`--plaintext`		Listen on plaintext HTTP instead of mTLS.
`--disable-gateway-auth`		Disable gateway authentication (mTLS client certificate requirement).
`--registry-token <REGISTRY_TOKEN>`		Authentication token for pulling container images from ghcr.io. Env: `OPENSHELL_REGISTRY_TOKEN`.
`--gpu`		Enable NVIDIA GPU passthrough.

`openshell gateway stop`#

Stop the gateway (preserves state).

Flag	Description
`--name <NAME>`	Gateway name (defaults to active gateway). Env: `OPENSHELL_GATEWAY`.
`--remote <REMOTE>`	Override SSH destination (auto-resolved from gateway metadata).
`--ssh-key <SSH_KEY>`	Path to SSH private key for remote gateway.

`openshell gateway destroy`#

Destroy the gateway and its state.

Flag	Description
`--name <NAME>`	Gateway name (defaults to active gateway). Env: `OPENSHELL_GATEWAY`.
`--remote <REMOTE>`	Override SSH destination (auto-resolved from gateway metadata).
`--ssh-key <SSH_KEY>`	Path to SSH private key for remote gateway.

`openshell gateway add <ENDPOINT>`#

Add an existing gateway.

Registers a gateway endpoint so it appears in openshell gateway select.

Without extra flags the gateway is treated as an edge-authenticated (cloud) gateway and a browser is opened for authentication.

Pass --remote <ssh-dest> to register a remote mTLS gateway whose Docker daemon is reachable over SSH. Pass --local to register a local mTLS gateway running in Docker on this machine. In both cases the CLI extracts mTLS certificates from the running container automatically.

An ssh:// endpoint (e.g., ssh://user@host:8080) is shorthand for --remote user@host with the endpoint derived from the URL.

Flag	Description
`<ENDPOINT>`	Gateway endpoint URL (e.g., `https://10.0.0.5:8080` or `ssh://user@host:8080`).
`--name <NAME>`	Gateway name (auto-derived from the endpoint hostname when omitted).
`--remote <REMOTE>`	Register a remote mTLS gateway accessible via SSH.
`--ssh-key <SSH_KEY>`	SSH private key for the remote host (used with `--remote` or `ssh://`).
`--local`	Register a local mTLS gateway running in Docker on this machine.

`openshell gateway login [NAME]`#

Authenticate with an edge-authenticated gateway.

Opens a browser for the edge proxy’s login flow and stores the token locally. Use this to re-authenticate when a token expires.

Flag	Description
`[NAME]`	Gateway name (defaults to the active gateway).

`openshell gateway select [NAME]`#

Select the active gateway.

When called without a name, opens an interactive chooser on a TTY and lists available gateways in non-interactive mode.

Flag	Description
`[NAME]`	Gateway name (omit to choose interactively or list in non-interactive mode).

`openshell gateway info`#

Show gateway deployment details.

Flag	Description
`--name <NAME>`	Gateway name (defaults to active gateway). Env: `OPENSHELL_GATEWAY`.

Inference Commands#

Manage inference configuration.

`openshell inference set`#

Set gateway-level inference provider and model.

Flag	Description
`--provider <PROVIDER>`	Provider name.
`--model <MODEL>`	Model identifier to force for generation calls.
`--system`	Configure the system inference route instead of the user-facing route. System inference is used by platform functions (e.g. the agent harness) and is not accessible to user code.

`openshell inference update`#

Update gateway-level inference configuration (partial update).

Flag	Description
`--provider <PROVIDER>`	Provider name (unchanged if omitted).
`--model <MODEL>`	Model identifier (unchanged if omitted).
`--system`	Target the system inference route.

`openshell inference get`#

Get gateway-level inference provider and model.

Flag	Description
`--system`	Show the system inference route instead of the user-facing route. When omitted, both routes are displayed.

Additional Commands#

`openshell logs [NAME]`#

View sandbox logs.

Flag	Default	Description
`[NAME]`		Sandbox name (defaults to last-used sandbox).
`-n <N>`	`200`	Number of log lines to return.
`--tail`		Stream live logs.
`--since <SINCE>`		Only show logs from this duration ago (e.g. 5m, 1h, 30s).
`--source <SOURCE>`	`all`	Filter by log source: “gateway”, “sandbox”, or “all” (default). Can be specified multiple times: –source gateway –source sandbox.
`--level <LEVEL>`		Minimum log level to display: error, warn, info (default), debug, trace.

`openshell status`#

Show gateway status and information.

`openshell term`#

Launch the OpenShell interactive TUI.

Flag	Default	Description
`--theme <THEME>`	`auto`	Color theme for the TUI: auto, dark, or light. Env: `OPENSHELL_THEME`.

`openshell completions <SHELL>`#

Generate shell completions.

Flag	Description
`<SHELL>`	Shell to generate completions for.

OpenShell CLI Reference#

Environment Variables#

Command Tree#

Sandbox Commands#

openshell sandbox create [COMMAND]#

openshell sandbox get [NAME]#

openshell sandbox list#

openshell sandbox delete [NAME]#

openshell sandbox connect [NAME]#

openshell sandbox upload <NAME> <LOCAL_PATH> [DEST]#

openshell sandbox download <NAME> <SANDBOX_PATH> [DEST]#

openshell sandbox ssh-config [NAME]#

Forward Commands#

openshell forward start <PORT> [NAME]#

openshell forward stop <PORT> [NAME]#

openshell forward list#

Policy Commands#

openshell policy set [NAME]#

openshell policy get [NAME]#

openshell policy list [NAME]#

Provider Commands#

openshell provider create#

openshell provider get <NAME>#

openshell provider list#

openshell provider update <NAME>#

openshell provider delete <NAME>#