> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/NVIDIA/OpenShell/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tip>
  For a full list of supported platforms and kernel requirements, see the [Support Matrix](/reference/support-matrix).
</Tip>

## Install the OpenShell CLI

<Steps>
  <Step title="Choose an install method">
    Install the CLI using the binary install script (recommended) or via PyPI with `uv`.

    <CodeGroup>
      ```bash binary (recommended) theme={null}
      curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
      ```

      ```bash uv (PyPI) theme={null}
      uv tool install -U openshell
      ```
    </CodeGroup>

    Both methods install the latest stable release by default.

    <Note>
      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>`.
    </Note>
  </Step>

  <Step title="Verify the installation">
    Run the following command to confirm the CLI is installed and see the full command reference:

    ```bash theme={null}
    openshell --help
    ```
  </Step>
</Steps>

## Create your first sandbox

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

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    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.
  </Tab>

  <Tab title="OpenCode">
    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    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.
  </Tab>

  <Tab title="GitHub Copilot">
    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Community Sandbox">
    Use the `--from` flag to pull a pre-built sandbox image from the [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) catalog:

    ```bash theme={null}
    openshell sandbox create --from openclaw
    ```

    Each community sandbox bundles a container image, a tailored policy, and optional agent skills.
  </Tab>
</Tabs>

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.

<Steps>
  <Step title="Create a sandbox">
    ```bash theme={null}
    openshell sandbox create
    ```
  </Step>

  <Step title="Try a blocked request from inside the sandbox">
    Inside the sandbox, outbound traffic is denied by default:

    ```bash theme={null}
    curl -sS https://api.github.com/zen
    # curl: (56) Received HTTP code 403 from proxy after CONNECT
    ```
  </Step>

  <Step title="Apply a read-only GitHub API policy">
    Exit the sandbox and apply a policy that allows GET requests to the GitHub API:

    ```bash theme={null}
    openshell policy set demo --policy examples/sandbox-policy-quickstart/policy.yaml --wait
    ```
  </Step>

  <Step title="Reconnect and verify">
    Reconnect to the sandbox and test the policy:

    ```bash theme={null}
    openshell sandbox connect demo
    ```

    GET is now allowed:

    ```bash theme={null}
    curl -sS https://api.github.com/zen
    # Anything added dilutes everything else.
    ```

    POST is still blocked by the L7 policy:

    ```bash theme={null}
    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"}
    ```
  </Step>
</Steps>

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

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

<Tabs>
  <Tab title="Local">
    ```bash theme={null}
    openshell gateway start
    ```
  </Tab>

  <Tab title="Remote SSH">
    Deploy to a remote host over SSH (only Docker is required on the remote machine):

    ```bash theme={null}
    openshell gateway start --remote user@host
    openshell status
    ```

    After `openshell status` shows the gateway as healthy, all subsequent commands route through the SSH tunnel.
  </Tab>

  <Tab title="Cloud">
    Register a gateway already running behind a reverse proxy:

    ```bash theme={null}
    openshell gateway add https://gateway.example.com
    ```
  </Tab>
</Tabs>

## What's next

<CardGroup cols={2}>
  <Card title="Introduction" icon="book-open" href="/introduction">
    Learn what OpenShell is, the problems it solves, and its protection layers.
  </Card>

  <Card title="Sandbox policies" icon="file-code" href="/sandboxes/policies">
    Write YAML policies to control exactly what each sandbox can access.
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/concepts/architecture">
    Understand the gateway, policy engine, and privacy router in depth.
  </Card>

  <Card title="Community sandboxes" icon="users" href="/sandboxes/community-sandboxes">
    Browse pre-built sandbox images for common agent setups.
  </Card>
</CardGroup>