Quickstart

Install the OpenShell CLI and create your first policy-enforced AI agent sandbox in two commands.

This page gets you from zero to a running, policy-enforced sandbox.

Prerequisites

Before you begin, make sure Docker Desktop (or a Docker daemon) is running on your machine. No other software is required.

For a full list of supported platforms and kernel requirements, see the Support Matrix.

Install the OpenShell CLI

1. Choose an install method

   Install the CLI using the binary install script (recommended) or via PyPI with uv.

   binary (recommended)

   curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
   

   Both methods install the latest stable release by default.

   To install a specific version, set the OPENSHELL_VERSION environment variable before running the install script, or pin the version with uv tool install openshell==<version>.

2. Verify the installation

   Run the following command to confirm the CLI is installed and see the full command reference:

   openshell --help
   

Create your first sandbox

Create a sandbox and launch an agent inside it. Choose the tab for your agent:

Claude Code

openshell sandbox create -- claude

The CLI prompts you to create a provider from local credentials. Type yes to continue.

If ANTHROPIC_API_KEY is set in your environment, the CLI picks it up automatically. If not, you can configure it from inside the sandbox after it launches.

OpenCode

openshell sandbox create -- opencode

The CLI prompts you to create a provider from local credentials. Type yes to continue.

If OPENAI_API_KEY or OPENROUTER_API_KEY is set in your environment, the CLI picks it up automatically. If not, you can configure it from inside the sandbox after it launches.

Codex

openshell sandbox create -- codex

The CLI prompts you to create a provider from local credentials. Type yes to continue.

If OPENAI_API_KEY is set in your environment, the CLI picks it up automatically. If not, you can configure it from inside the sandbox after it launches.

GitHub Copilot

openshell sandbox create -- copilot

The CLI prompts you to create a provider from local credentials. Type yes to continue.

If GITHUB_TOKEN or COPILOT_GITHUB_TOKEN is set in your environment, the CLI picks it up automatically. If not, you can configure it from inside the sandbox after it launches.

Community Sandbox

Use the --from flag to pull a pre-built sandbox image from the OpenShell Community catalog:

openshell sandbox create --from openclaw

Each community sandbox bundles a container image, a tailored policy, and optional agent skills.

A gateway is created automatically on first use. The sandbox container includes the following tools by default:

Category	Tools
Agent	claude, opencode, codex, copilot
Language	python (3.13), node (22)
Developer	gh, git, vim, nano
Networking	ping, dig, nslookup, nc, traceroute, netstat

See network policy in action

Every sandbox starts with minimal outbound access. You open additional access with a short YAML policy that the proxy enforces at the HTTP method and path level — no restart required.

1. Create a sandbox

   openshell sandbox create
   
2. Try a blocked request from inside the sandbox

   Inside the sandbox, outbound traffic is denied by default:

   curl -sS https://api.github.com/zen
   # curl: (56) Received HTTP code 403 from proxy after CONNECT
   
3. Apply a read-only GitHub API policy

   Exit the sandbox and apply a policy that allows GET requests to the GitHub API:

   openshell policy set demo --policy examples/sandbox-policy-quickstart/policy.yaml --wait
   
4. Reconnect and verify

   Reconnect to the sandbox and test the policy:

   openshell sandbox connect demo
   

   GET is now allowed:

   curl -sS https://api.github.com/zen
   # Anything added dilutes everything else.
   

   POST is still blocked by the L7 policy:

   curl -sS -X POST https://api.github.com/repos/octocat/hello-world/issues -d '{"title":"oops"}'
   # {"error":"policy_denied","detail":"POST /repos/octocat/hello-world/issues not permitted by policy"}
   

You can run the full automated demo with bash examples/sandbox-policy-quickstart/demo.sh.

Deploy a gateway (optional)

Running openshell sandbox create without a gateway auto-bootstraps a local one. To start the gateway explicitly or deploy to a remote host:

Local

openshell gateway start

Remote SSH

Deploy to a remote host over SSH (only Docker is required on the remote machine):

openshell gateway start --remote user@host
openshell status

After openshell status shows the gateway as healthy, all subsequent commands route through the SSH tunnel.

Cloud

Register a gateway already running behind a reverse proxy:

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

What’s next

Introduction

Learn what OpenShell is, the problems it solves, and its protection layers.

Sandbox policies

Write YAML policies to control exactly what each sandbox can access.

Architecture

Understand the gateway, policy engine, and privacy router in depth.

Community sandboxes

Browse pre-built sandbox images for common agent setups.