---
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
title: "Quickstart"
description: "Install the OpenShell CLI, connect to a gateway, and create your first sandboxed AI agent."
keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Installation, Quickstart, Gateway, Docker, Kubernetes, Podman"
position: 1
---

This page gets you from a reachable OpenShell gateway to a running, policy-enforced sandbox.

## Prerequisites

Before you begin, make sure you have:

- A reachable OpenShell gateway.
- At least one compute driver configured for the gateway: Kubernetes, Docker, Podman, or MicroVM.
- The OpenShell CLI installed on your workstation.

For a complete list of requirements, refer to [Support Matrix](/reference/support-matrix).
If you have not chosen a compute driver yet, refer to [Installation](/about/installation).

## Install the OpenShell CLI

Run the install script:

```shell
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
```

The install script uses Homebrew, RPM, or a Debian package based on your machine. It starts the local gateway server after installation.

After installing the CLI, run `openshell --help` in your terminal to view the full CLI reference.

<Tip>
Install the public OpenShell agent skills with `npx skills add NVIDIA/OpenShell`. The `openshell-cli` skill guides your agent through common workflows and uses the installed CLI help as the command reference; no OpenShell source checkout is required.
</Tip>

## Import a Provider Profile

A provider profile describes the credentials, endpoints, and client binaries a
provider needs. A gateway serves only the profiles you imported, so import one
before creating a sandbox that uses a provider.

The OpenShell repository ships example profiles in
[`providers/`](https://github.com/NVIDIA/OpenShell/tree/main/providers). Download
the one matching your agent and import it at platform scope:

```shell
curl -LsSfO https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/claude-code.yaml
openshell provider profile import -f claude-code.yaml --global
```

Use `codex.yaml` for Codex, or `openai.yaml` for OpenCode. Confirm the catalog:

```shell
openshell provider list-profiles
```

<Tip>
Read the comment header at the top of each file before importing it. It names
the client binaries the profile expects and the image layout those paths assume.
If your sandbox image installs the agent somewhere else, edit `binaries` first —
otherwise the profile matches nothing and the credential is never injected.
</Tip>

## Create Your First Sandbox

Create a sandbox with the gateway's default workload image:

```shell
openshell sandbox create --name quickstart
```

The default is `nvcr.io/nvidia/base/ubuntu:24.04`. It provides a minimal Ubuntu Noble environment; install workload-specific tools in your own image.

Connect to the sandbox:

```shell
openshell sandbox connect quickstart
```

Run a command without opening an interactive session:

```shell
openshell sandbox exec -n quickstart -- cat /etc/os-release
```

## Run an Agent Image

Build an OCI image containing your agent and its dependencies, then pass its full image reference:

```shell
docker build -t my-agent:latest ./my-agent
openshell sandbox create --from my-agent:latest -- my-agent
```

For a Podman gateway, build and use a Podman-visible name such as `localhost/my-agent:latest`. For a remote gateway, push the image to a registry that the gateway can pull from.

Attach a provider and a policy that authorize the agent's credentials, endpoints, and executable paths. Refer to [Bring Your Own Container](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container), [Providers](/providers), and [Customize Sandbox Policies](/sandboxes/policies).