OpenShell CLI

Guide agents through using the

openshell

CLI for sandbox and platform management -- from basic operations to advanced multi-step workflows.

Overview

The OpenShell CLI (

openshell

) is the primary interface for managing sandboxes, providers, policies, inference routes, and gateway registrations. Gateway service lifecycle is handled outside the CLI by packages, systemd, Helm, or development tasks. This skill teaches agents how to orchestrate CLI commands for common and complex workflows.

Companion skill: For creating or modifying sandbox policy YAML content (network rules, L7 inspection, access presets), use the

generate-sandbox-policy

skill. This skill covers the CLI commands for the policy lifecycle;

generate-sandbox-policy

covers policy content authoring.

Self-teaching: The CLI has comprehensive built-in help. When you encounter a command or option not covered in this skill, walk the help tree:

bash

openshell --help                    # Top-level commands
openshell <group> --help            # Subcommands in a group
openshell <group> <cmd> --help      # Flags for a specific command

This is your primary fallback. Use it freely -- the CLI's help output is authoritative and always up-to-date.

Prerequisites

openshell

is on the PATH (install via

cargo install --path crates/openshell-cli

)

A reachable OpenShell gateway backed by Docker, Podman, Kubernetes, or the experimental VM driver
Docker is running only when using BYOC local builds or Docker-backed development workflows
For Kubernetes deployments:
```
kubectl
```
and Helm access to the target cluster

Command Reference

See cli-reference.md for the full command tree with all flags and options. Use it as a quick-reference to avoid round-tripping through

--help

for common commands.

Workflow 1: Getting Started

Use this workflow when the user has a gateway endpoint and wants to get a sandbox running for the first time.

Step 1: Register a gateway

bash

openshell gateway add http://127.0.0.1:8080 --local --name local

Use an

http://

endpoint only for trusted local port-forwarding or a protected private path. For a gateway behind an authenticated reverse proxy, register its HTTPS endpoint with

openshell gateway add https://gateway.example.com

Step 2: Verify the gateway

bash

openshell status

Confirm the gateway is reachable and shows a version.

Step 3: Create a sandbox

The simplest way to get a sandbox running:

bash

openshell sandbox create

This creates a sandbox with defaults and drops you into an interactive shell.

Shortcut for known tools: When the trailing command is a recognized tool, the CLI auto-creates the required provider from local credentials:

bash

openshell sandbox create -- claude        # Auto-creates claude provider
openshell sandbox create -- codex         # Auto-creates codex provider

The agent will be prompted interactively if credentials are missing.

Step 4: Exit and clean up

Exit the sandbox shell (

exit

or Ctrl-D), then:

bash

openshell sandbox delete <name>

Workflow 2: Provider Management

Providers supply credentials to sandboxes (API keys, tokens, etc.). Manage them before creating sandboxes that need them.

Supported types:

claude

opencode

codex

generic

nvidia

gitlab

github

outlook

Create a provider from local credentials

bash

openshell provider create --name my-github --type github --from-existing

The

--from-existing

flag discovers credentials from local state (e.g.,

gh auth

tokens, Claude config files).

Create a provider with explicit credentials

bash

openshell provider create --name my-api --type generic \
  --credential API_KEY=sk-abc123 \
  --config base_url=https://api.example.com

Bare

KEY

(without

=VALUE

) reads the value from the environment variable of that name:

bash

openshell provider create --name my-api --type generic --credential API_KEY

List, inspect, update, delete

bash

openshell provider list
openshell provider get my-github
openshell provider update my-github --type github --from-existing
openshell provider delete my-github

Workflow 3: Sandbox Lifecycle

Create with options

bash

openshell sandbox create \
  --name my-sandbox \
  --provider my-github \
  --provider my-claude \
  --policy ./my-policy.yaml \
  --upload .:/sandbox \
  -- claude

Key flags:

```
--provider
```
: Attach one or more providers (repeatable)
```
--policy
```
: Custom policy YAML (otherwise uses built-in default or
```
OPENSHELL_SANDBOX_POLICY
```
env var)
```
--cpu
```
,
```
--memory
```
: Set per-sandbox compute sizing. Docker/Podman apply limits; Kubernetes applies matching requests and limits.
```
--upload <PATH>[:<DEST>]
```
: Upload local files into the sandbox (default dest:
```
/sandbox
```
)
```
--no-keep
```
: Delete the sandbox after the initial command or shell exits
```
--forward <PORT>
```
: Forward a local port and keep the sandbox alive

List and inspect sandboxes

bash

openshell sandbox list
openshell sandbox get my-sandbox

Connect to a running sandbox

bash

openshell sandbox connect my-sandbox

Opens an interactive SSH shell. To configure VS Code Remote-SSH:

bash

openshell sandbox ssh-config my-sandbox >> ~/.ssh/config

Upload and download files

bash

# Upload local files to sandbox
openshell sandbox upload my-sandbox ./src /sandbox/src

# Download files from sandbox
openshell sandbox download my-sandbox /sandbox/output ./local-output

View logs

bash

# Recent logs
openshell logs my-sandbox

# Stream live logs
openshell logs my-sandbox --tail

# Filter by source and level
openshell logs my-sandbox --tail --source sandbox --level warn

# Logs from the last 5 minutes
openshell logs my-sandbox --since 5m

Delete sandboxes

bash

openshell sandbox delete my-sandbox
openshell sandbox delete sandbox-1 sandbox-2 sandbox-3   # Multiple at once

Workflow 4: Policy Iteration Loop

This is the most important multi-step workflow. It enables a tight feedback cycle where sandbox policy is refined based on observed activity.

Key concept: Policies have static fields (immutable after creation:

filesystem_policy

landlock

process

) and one dynamic field (

network_policies

). Only

network_policies

can be updated without recreating the sandbox.

Create sandbox with initial policy
        │
        ▼
   Monitor logs ◄──────────────────┐
        │                          │
        ▼                          │
  Observe denied actions           │
        │                          │
        ▼                          │
  Pull current policy              │
        │                          │
        ▼                          │
  Modify policy YAML               │
  (use generate-sandbox-policy)    │
        │                          │
        ▼                          │
  Push updated policy              │
        │                          │
        ▼                          │
  Verify reload succeeded ─────────┘

Step 1: Create sandbox with initial policy

bash

openshell sandbox create --name dev --policy ./initial-policy.yaml -- claude

Sandboxes stay alive by default for iteration. Add

--no-keep

only when the sandbox should be deleted automatically after the initial session.

Step 2: Monitor logs for denied actions

In a separate terminal or as the agent:

bash

openshell logs dev --tail --source sandbox

Look for log lines with

action: deny

-- these indicate blocked network requests. The logs include:

Destination host and port (what was blocked)
Binary path (which process attempted the connection)
Deny reason (why it was blocked)

Step 3: Pull the current policy

bash

openshell policy get dev --full > current-policy.yaml

The

--full

flag outputs valid YAML that can be directly re-submitted. This is the round-trip format.

Step 4: Modify the policy

Edit

current-policy.yaml

to allow the blocked actions. For policy content authoring, delegate to the
generate-sandbox-policy
skill. That skill handles:

Network endpoint rule structure
L4 vs L7 policy decisions
Access presets (
```
read-only
```
,
```
read-write
```
,
```
full
```
)
TLS termination configuration
Enforcement modes (
```
audit
```
vs
```
enforce
```
)
Binary matching patterns

Only

network_policies

can be modified at runtime. If

filesystem_policy

landlock

, or

process

need changes, the sandbox must be recreated.

Step 5: Push the updated policy

bash

openshell policy set dev --policy current-policy.yaml --wait

The

--wait

flag blocks until the sandbox confirms the policy is loaded (polls every second). Exit codes:

0: Policy loaded successfully
1: Policy load failed
124: Timeout (default 60 seconds)

Step 6: Verify the update

bash

openshell policy list dev

Check that the latest revision shows status

loaded

. If

failed

, check the error column for details.

Step 7: Repeat

Return to Step 2. Continue monitoring logs and refining the policy until all required actions are allowed and no unnecessary permissions exist.

Policy revision history

View all revisions to understand how the policy evolved:

bash

openshell policy list dev --limit 50

Fetch a specific historical revision:

bash

openshell policy get dev --rev 3 --full

Workflow 5: BYOC (Bring Your Own Container)

Build a custom container image and run it as a sandbox.

Step 1: Create a sandbox from a Dockerfile

bash

openshell sandbox create --from ./Dockerfile --name my-app

The

--from

flag accepts a Dockerfile path, a directory containing a Dockerfile, a full image reference (e.g.

myregistry.com/img:tag

), or a community sandbox name (e.g.

openclaw

When given a Dockerfile or directory, the image is built locally via Docker and delivered through the selected compute driver. Docker and Podman-backed gateways can use local images directly. Kubernetes gateways usually need the image available to the cluster through a registry or driver-supported image push path.

When

--from

is specified, the CLI:

Clears default
```
run_as_user
```
/
```
run_as_group
```
(custom images may not have the
```
sandbox
```
user)
Uses a supervisor bootstrap pattern (init container copies the sandbox supervisor into a shared volume)

Step 2: Forward ports (if the container runs a service)

bash

# Foreground (blocks)
openshell forward start 8080 my-app

# Background (returns immediately)
openshell forward start 8080 my-app -d

The service is now reachable at

localhost:8080

Step 3: Manage port forwards

bash

# List active forwards
openshell forward list

# Stop a forward
openshell forward stop 8080 my-app

Step 4: Iterate

To update the container:

bash

openshell sandbox delete my-app
openshell sandbox create --from ./Dockerfile --name my-app --forward 8080

Shortcut: Create with port forward in one command

bash

openshell sandbox create --from ./Dockerfile --forward 8080 -- ./start-server.sh

The

--forward

flag starts a background port forward before the command runs, so the service is reachable immediately.

Limitations

Distroless /
```
FROM scratch
```
images are not supported (the supervisor needs glibc,
```
/proc
```
, and a shell)
Missing
```
iproute2
```
or required capabilities blocks startup in proxy mode

Workflow 6: Agent-Assisted Sandbox Session

This workflow supports a human working in a sandbox while an agent monitors activity and refines the policy in parallel.

Step 1: Create sandbox with providers and keep alive

bash

openshell sandbox create \
  --name work-session \
  --provider github \
  --provider claude \
  --policy ./dev-policy.yaml \
  # sandbox create keeps the sandbox alive by default

Step 2: User connects in a separate shell

Tell the user to run:

bash

openshell sandbox connect work-session

Or for VS Code:

bash

openshell sandbox ssh-config work-session >> ~/.ssh/config
# Then connect via VS Code Remote-SSH to the host "work-session"

Step 3: Agent monitors logs

While the user works, monitor the sandbox logs:

bash

openshell logs work-session --tail --source sandbox --level warn

Watch for

deny

actions that indicate the user's work is being blocked by policy.

Step 4: Agent refines policy

When denied actions are observed:

Prefer incremental updates for additive network changes:

openshell policy update work-session --add-endpoint api.github.com:443:read-only:rest:enforce --binary /usr/bin/gh --wait

openshell policy update work-session --add-allow 'api.github.com:443:POST:/repos/*/issues' --wait

Use full YAML replacement when the change is broad or touches non-network fields:
```
openshell policy get work-session --full > policy.yaml
```
Modify the policy to allow the blocked actions (use
```
generate-sandbox-policy
```
skill for content)
```
openshell policy set work-session --policy policy.yaml --wait
```
Verify:
```
openshell policy list work-session
```

The user does not need to disconnect -- policy updates are hot-reloaded within ~30 seconds (or immediately when using

--wait

, which polls for confirmation).

Step 5: Clean up when done

bash

openshell sandbox delete work-session

Workflow 7: Gateway Inference

Configure the gateway's managed inference route for

inference.local

Set gateway inference

First ensure the provider record exists:

bash

openshell provider list

Then point gateway inference at that provider and model:

bash

openshell inference set \
  --provider nvidia \
  --model nvidia/nemotron-3-nano-30b-a3b

This updates the gateway-managed

inference.local

route. There is no per-route create/list/update/delete workflow for sandbox inference.

Inspect current inference config

bash

openshell inference get

How sandboxes use it

Agents send HTTPS requests to
```
inference.local
```
.
The sandbox intercepts those requests locally and routes them through the gateway inference config.
Sandbox policy is separate from gateway inference configuration.

Workflow 8: Gateway Management

List and switch gateways

bash

openshell gateway select            # See all gateways (no args shows list)
openshell gateway select production # Switch active gateway
openshell status                    # Verify connectivity

Registration

bash

openshell gateway add http://127.0.0.1:8080 --local --name local
openshell gateway add https://gateway.example.com --name production
openshell gateway remove local                         # Remove local registration

Platform-specific deployment inspection

bash

# Inspect a Kubernetes Helm release and gateway pod
helm -n openshell status openshell
kubectl -n openshell get pods,svc
kubectl -n openshell logs statefulset/openshell --tail=100

For Docker, Podman, and VM-backed gateways, inspect the gateway process or container logs and the selected runtime directly.

Self-Teaching via

--help

When you encounter a command or option not covered in this skill:

Start broad:
```
openshell --help
```
to see all command groups.

Narrow down:

openshell <group> --help

to see subcommands (e.g.,

openshell sandbox --help

Get specific:

openshell <group> <cmd> --help

for flags and usage (e.g.,

openshell sandbox create --help

The CLI help is always authoritative. If the help output contradicts this skill, follow the help output -- the CLI may have been updated since this skill was written.

Example: discovering an unfamiliar command

bash

$ openshell sandbox --help
# Shows: create, get, list, delete, connect, upload, download, ssh-config, image

$ openshell sandbox upload --help
# Shows: positional arguments (name, path, dest), usage examples

Quick Reference

Task	Command
Register local port-forwarded gateway	`openshell gateway add http://127.0.0.1:8080 --local --name local`
Check gateway health	`openshell status`
List/switch gateways	`openshell gateway select [name]`
Create sandbox (interactive)	`openshell sandbox create`
Create sandbox with tool	`openshell sandbox create -- claude`
Create with custom policy	`openshell sandbox create --policy ./p.yaml`
Connect to sandbox	`openshell sandbox connect <name>`
Stream live logs	`openshell logs <name> --tail`
Incremental policy update	`openshell policy update <name> --add-endpoint host:443:read-only:rest:enforce --binary /usr/bin/curl --wait`
Pull current policy	`openshell policy get <name> --full > p.yaml`
Push updated policy	`openshell policy set <name> --policy p.yaml --wait`
Policy revision history	`openshell policy list <name>`
Create sandbox from Dockerfile	`openshell sandbox create --from ./Dockerfile`
Forward a port	`openshell forward start <port> <name> -d`
Upload files to sandbox	`openshell sandbox upload <name> <path>`
Download files from sandbox	`openshell sandbox download <name> <path>`
Create provider	`openshell provider create --name N --type T --from-existing`
List providers	`openshell provider list`
Configure gateway inference	`openshell inference set --provider P --model M`
View gateway inference	`openshell inference get`
Delete sandbox	`openshell sandbox delete <name>`
Remove gateway registration	`openshell gateway remove <name>`
Self-teach any command	`openshell <group> <cmd> --help`

Companion Skills

Skill	When to use
`generate-sandbox-policy`	Creating or modifying policy YAML content (network rules, L7 inspection, access presets, endpoint configuration)
`debug-openshell-cluster`	Diagnosing gateway deployment, runtime, or health failures
`debug-inference`	Diagnosing `inference.local` , host-backed local inference, and provider base URL issues
`tui-development`	Developing features for the OpenShell TUI ( `openshell term` )

openshell-cli

NPX Install

Tags

SKILL.md Content

OpenShell CLI

Overview

Prerequisites

Command Reference

Workflow 1: Getting Started

Step 1: Register a gateway

Step 2: Verify the gateway

Step 3: Create a sandbox

Step 4: Exit and clean up

Workflow 2: Provider Management

Create a provider from local credentials

Create a provider with explicit credentials

List, inspect, update, delete

Workflow 3: Sandbox Lifecycle

Create with options

List and inspect sandboxes

Connect to a running sandbox

Upload and download files

View logs

Delete sandboxes

Workflow 4: Policy Iteration Loop

Step 1: Create sandbox with initial policy

Step 2: Monitor logs for denied actions

Step 3: Pull the current policy

Step 4: Modify the policy

Step 5: Push the updated policy

Step 6: Verify the update

Step 7: Repeat

Policy revision history

Workflow 5: BYOC (Bring Your Own Container)

Step 1: Create a sandbox from a Dockerfile

Step 2: Forward ports (if the container runs a service)

Step 3: Manage port forwards

Step 4: Iterate

Shortcut: Create with port forward in one command

Limitations

Workflow 6: Agent-Assisted Sandbox Session

Step 1: Create sandbox with providers and keep alive

Step 2: User connects in a separate shell

Step 3: Agent monitors logs

Step 4: Agent refines policy

Step 5: Clean up when done

Workflow 7: Gateway Inference

Set gateway inference

Inspect current inference config

How sandboxes use it

Workflow 8: Gateway Management

List and switch gateways

Registration

Platform-specific deployment inspection

Self-Teaching via --help

Example: discovering an unfamiliar command

Quick Reference

Companion Skills

Self-Teaching via
`--help`