Skip to content

docs: improve the docs more #308

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
miyoungc merged 2 commits into from
Mar 14, 2026
Merged

docs: improve the docs more #308

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d2c5e56
improve docs
miyoungc Mar 14, 2026
7b1a27f
save
miyoungc Mar 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 46 additions & 16 deletions docs/get-started/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,39 +32,57 @@ This page gets you from zero to a running, policy-enforced sandbox in two comman

Before you begin, make sure you have:

- Python 3.12 or later
- [uv](https://docs.astral.sh/uv/) installed
- Docker Desktop running on your machine
- Python 3.12 or later.
- [uv](https://docs.astral.sh/uv/) installed.
- Docker Desktop running on your machine.

For a complete list of requirements, refer to {doc}`../reference/support-matrix`.

## Install the OpenShell CLI

Install the `openshell` package into a virtual environment.

Activate your virtual environment:

```bash
uv venv && source .venv/bin/activate
```console
$ uv venv && source .venv/bin/activate
```

Install the CLI:

```bash
uv pip install openshell
```console
$ uv pip install openshell
```

## Connect to a Remote Gateway (Optional)
:::{tip}
To find the CLI reference, run:
- `openshell --help` to see all available commands.
- `openshell <command> --help` for detailed usage of any subcommand.

For example:

```console
$ openshell --help
$ openshell gateway --help
$ openshell sandbox create --help
```
:::

## Deploy a Gateway (Optional)

If you're running locally, skip this step. The OpenShell CLI creates a gateway automatically when you create your first sandbox.
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.

:::::{tab-set}

::::{tab-item} Brev

:::{note}
Deploy an OpenShell gateway on Brev by hitting **Deploy** on the [OpenShell Launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3AaK9NmCzWp3pVyUDNNFBt805FT).
Deploy an OpenShell gateway on Brev by clicking **Deploy** on the [OpenShell Launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3AaK9NmCzWp3pVyUDNNFBt805FT).
:::

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

```console
$ openshell gateway add https://<your-port-8080-url>.brevlab.com
Expand Down Expand Up @@ -94,6 +112,7 @@ After `openshell status` shows the gateway as healthy, all subsequent commands r

## Create Your First OpenShell Sandbox

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

::::{tab-set}
Expand All @@ -106,7 +125,10 @@ 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.
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-item} OpenCode
Expand All @@ -117,7 +139,10 @@ 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.
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-item} Codex
Expand All @@ -128,7 +153,10 @@ 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.
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-item} OpenClaw
Expand All @@ -139,12 +167,14 @@ 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](https://github.com/NVIDIA/OpenShell-Community) catalog. Each definition bundles a container image, a tailored policy, and optional skills into a single package.
The `--from` flag pulls a pre-built sandbox definition from the [OpenShell Community](https://github.com/NVIDIA/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](https://registry.nvidia.com/). For example, to pull the `base` image, run the following command:
Use the `--from` flag to pull other OpenShell sandbox images from the [NVIDIA Container Registry](https://registry.nvidia.com/).
For example, to pull the `base` image, run the following command:

```console
$ openshell sandbox create --from base
Expand Down
6 changes: 5 additions & 1 deletion docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,11 @@ Install the CLI and create your first sandbox in two commands.
</div>
```

Refer to the [Quickstart](get-started/quickstart.md) for more details.
Run `openshell --help` in your terminal to see the full CLI reference, including all commands and flags.
Run `openshell <command> --help` for detailed usage of any subcommand.

Proceed to the [Quickstart](get-started/quickstart.md) for more details.


---

Expand Down
Loading