Quickstart#
This page gets you from zero to a running, policy-enforced sandbox in two commands.
Prerequisites#
Before you begin, make sure you have:
Python 3.12 or later
uv installed
Docker Desktop running on your machine
Install the OpenShell CLI#
Install the openshell package into a virtual environment.
Activate your virtual environment:
uv venv && source .venv/bin/activate
Install the CLI:
uv pip install openshell
Connect to a Remote Gateway (Optional)#
If you’re running locally, skip this step. The OpenShell CLI creates a gateway automatically when you create your first sandbox.
Note
Deploy an OpenShell gateway on Brev by hitting Deploy on the OpenShell Launchable.
After the instance is running, find the gateway URL in the Brev console under Using Secure Links. Copy the shareable URL for port 8080 — this is the gateway endpoint.
$ openshell gateway add https://<your-port-8080-url>.brevlab.com
$ openshell status
Note
Set up your Spark with NVIDIA Sync first, or make sure SSH access is configured (such as SSH keys added to the host).
Deploy to a DGX Spark machine over SSH:
$ openshell gateway start --remote <username>@<spark-ssid>.local
$ openshell status
After openshell status shows the gateway as healthy, all subsequent commands route through the SSH tunnel.
Create Your First OpenShell Sandbox#
Choose the tab that matches your agent:
Run the following command to create a sandbox with 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, it is picked up automatically. If not, you can configure it from inside the sandbox after it launches.
Run the following command to create a sandbox with 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, it is picked up automatically. If not, you can configure it from inside the sandbox after it launches.
Run the following command to create a sandbox with 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, it is picked up automatically. If not, you can configure it from inside the sandbox after it launches.
Run the following command to create a sandbox with OpenClaw:
$ openshell sandbox create --from openclaw
The --from flag pulls a pre-built sandbox definition from the OpenShell Community catalog. Each definition bundles a container image, a tailored policy, and optional skills into a single package.
You can use the --from flag to pull other OpenShell sandbox images from the NVIDIA Container Registry. For example, to pull the base image, run the following command:
$ openshell sandbox create --from base