mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-04 08:28:19 +08:00
101 lines
3.8 KiB
Plaintext
101 lines
3.8 KiB
Plaintext
---
|
|
# 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).
|