mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-14 04:59:28 +08:00
50230616d5
* feat(sandbox): default to official Alpine sandbox image default_sandbox_image() now returns docker.io/library/alpine:3.22, a generic version-qualified official image, so a fresh install no longer depends on the community sandbox image catalog. All compute drivers (docker, podman, kubernetes, vm) inherit this fallback. Part of #3116. Signed-off-by: Akram Signed-off-by: Akram <akram.benaissi@gmail.com> * feat(deploy): default deployment configs to the official Alpine sandbox image Update the shared gateway default_image, Helm chart values, the standalone Kubernetes manifest, and the dev gateway task scripts to use docker.io/library/alpine:3.22 instead of the community base image, consistent with default_sandbox_image(). GPU e2e image-build base is left unchanged (CUDA needs a glibc base). Part of #3116. Signed-off-by: Akram Signed-off-by: Akram <akram.benaissi@gmail.com> * feat(driver): default to numeric non-root identity for USER-less images With the default sandbox image now Alpine, images that declare no OCI USER must start instead of being rejected. When the image declares no USER and the policy requests none, the Podman and Docker drivers now supply a numeric non-root identity (DEFAULT_SANDBOX_UID/GID = 1000) instead of rejecting, matching the numeric-identity behavior of the Kubernetes and VM drivers. The supervisor's resolved-identity path runs the sandbox as a synthesized non-root account without the account existing in the image. Images that declare a USER keep the OCI resolution path unchanged. Part of #3116. Signed-off-by: Akram <akram.benaissi@gmail.com> Signed-off-by: Evan Lezar <elezar@nvidia.com> * test(conformance): use Alpine workload image Signed-off-by: Evan Lezar <elezar@nvidia.com> * refactor(policy): drop community image /app path from default policy The restrictive default policy granted read-only access to /app, a directory that only existed in the community base image. A generic Alpine default has no /app, so remove it. Landlock best-effort already ignores absent paths; this just stops advertising a community-specific layout in the default. Part of #3116. Signed-off-by: Akram Signed-off-by: Akram <akram.benaissi@gmail.com> * docs(config): document Alpine default images Signed-off-by: Evan Lezar <elezar@nvidia.com> * fix(podman): report early sandbox termination Signed-off-by: Evan Lezar <elezar@nvidia.com> * fix(podman): initialize rootless workspace ownership Signed-off-by: Evan Lezar <elezar@nvidia.com> * fix(sandbox): qualify NVIDIA Ubuntu default Signed-off-by: Drew Newberry <anewberry@nvidia.com> * fix(podman): initialize rootful default workspace Signed-off-by: Drew Newberry <anewberry@nvidia.com> * feat(sftp): add native sandbox adapter Signed-off-by: Drew Newberry <anewberry@nvidia.com> * fix(sftp): gate runtime helper support to Linux Signed-off-by: Drew Newberry <anewberry@nvidia.com> * fix(sftp): support standard OpenSSH file operations Signed-off-by: Drew Newberry <anewberry@nvidia.com> * fix(sftp): harden rename and special file handling Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(runtime): remove community image dependencies Signed-off-by: Drew Newberry <anewberry@nvidia.com> * test(e2e): build provider readiness tool fixture Signed-off-by: Drew Newberry <anewberry@nvidia.com> * fix(e2e): use a dedicated Noble fixture for Docker tests Signed-off-by: Evan Lezar <elezar@nvidia.com> --------- Signed-off-by: Akram Signed-off-by: Akram <akram.benaissi@gmail.com> Signed-off-by: Evan Lezar <elezar@nvidia.com> Signed-off-by: Drew Newberry <anewberry@nvidia.com> Co-authored-by: Evan Lezar <elezar@nvidia.com> Co-authored-by: Drew Newberry <anewberry@nvidia.com>
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).
|