OpenShell/docs/get-started/quickstart.md

title, description, topics, tags, content

title	description	topics	tags	content
page nav Quickstart Quickstart	Install the OpenShell CLI and create your first sandboxed AI agent in two commands.	Generative AI Cybersecurity	AI Agents Sandboxing Installation Quickstart	type difficulty audience get_started technical_beginner engineer data_scientist

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.

:::::{tab-set}

::::{tab-item} Brev

:::{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

::::

::::{tab-item} 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

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:

::::{tab-set}

:::{tab-item} Claude Code

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. :::

:::{tab-item} OpenCode

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. :::

:::{tab-item} Codex

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. :::

:::{tab-item} OpenClaw

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. :::

:::{tab-item} Community Sandbox

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

:::