Quickstart — NVIDIA OpenShell Developer Guide
Quickstart #
This page gets you from zero to a running, policy-enforced sandbox in two commands.
Prerequisites #
Before you begin, make sure you have:
- Docker Desktop running on your machine.
For a complete list of requirements, refer to Support Matrix.
Install the OpenShell CLI #
Run the install script:
$ curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
Copy to clipboard
If you prefer uv:
$ uv tool install -U openshell
Copy to clipboard
After installing the CLI, run openshell --help in your terminal to see the full CLI reference, including all commands and flags.
Tip
You can also clone the NVIDIA OpenShell GitHub repository and use the /openshell-cli skill to load the CLI reference into your agent.
Create Your First OpenShell Sandbox #
Create a sandbox and launch an agent inside it. Choose the tab that matches your agent:
Claude Code
Run the following command to create a sandbox with Claude Code:
$ openshell sandbox create -- claude
Copy to clipboard
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
Run the following command to create a sandbox with OpenCode:
$ openshell sandbox create -- opencode
Copy to clipboard
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
Run the following command to create a sandbox with Codex:
$ openshell sandbox create -- codex
Copy to clipboard
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.
OpenClaw
Run the following command to create a sandbox with OpenClaw:
$ openshell sandbox create --from openclaw
Copy to clipboard
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.
Community Sandbox
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
Copy to clipboard
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, choose the tab that matches your setup.
Brev
Note
Deploy an OpenShell gateway on Brev by clicking Deploy on the OpenShell Launchable.
After the instance starts running, find the gateway URL in the Brev console under Using Secure Links. Copy the shareable URL for port 8080, which is the gateway endpoint.
$ openshell gateway add https://<your-port-8080-url>.brevlab.com
$ openshell status
Copy to clipboard
DGX Spark
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
Copy to clipboard
After openshell status shows the gateway as healthy, all subsequent commands route through the SSH tunnel.