Skip to content

Commit 4107bb3

Browse files
committed
docs: reorganize guides and require user-owned images
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
1 parent 8d1d892 commit 4107bb3

58 files changed

Lines changed: 1211 additions & 323 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 27 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -55,20 +55,20 @@ For deploying OpenShell on OpenShift, see [`deploy/helm/openshell/README.md#inst
5555

5656
### Create a sandbox
5757

58+
Build an OCI image with the agent and tools your workflow needs, then pass its
59+
image reference explicitly:
60+
5861
```bash
59-
openshell sandbox create -- claude # or opencode, codex, copilot
62+
docker build -t registry.example.com/team/claude-code:1.0 ./agent-image
63+
docker push registry.example.com/team/claude-code:1.0
64+
openshell sandbox create \
65+
--from registry.example.com/team/claude-code:1.0 \
66+
-- claude
6067
```
6168

62-
The sandbox container includes the following tools by default:
63-
64-
| Category | Tools |
65-
| ---------- | -------------------------------------------------------- |
66-
| Agent | `claude`, `opencode`, `codex`, `copilot` |
67-
| Language | `python` (3.14), `node` (22) |
68-
| Developer | `gh`, `git`, `vim`, `nano` |
69-
| Networking | `ping`, `dig`, `nslookup`, `nc`, `traceroute`, `netstat` |
70-
71-
For more details see https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base.
69+
OpenShell supplies the sandbox runtime and policy controls. You supply and
70+
maintain the workload image, including its agent, runtimes, certificates, and
71+
development tools.
7272

7373
### See network policy in action
7474

@@ -184,31 +184,26 @@ Inference access uses the same provider workflow. Attach an inference-capable pr
184184
OpenShell can pass host GPUs into sandboxes for local inference, fine-tuning, or any GPU workload. Add `--gpu` when creating a sandbox:
185185

186186
```bash
187-
openshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude
187+
openshell sandbox create --gpu --from registry.example.com/team/gpu-agent:1.0 -- claude
188188
```
189189

190190
Docker-backed GPU sandboxes auto-select CDI when available and otherwise fall back to Docker's NVIDIA GPU request path (`--gpus all`).
191191

192-
**Requirements:** NVIDIA drivers and the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) must be installed on the host. The sandbox image itself must include the appropriate GPU drivers and libraries for your workload — the default `base` image does not. See the [BYOC example](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container) for building a custom sandbox image with GPU support.
192+
**Requirements:** NVIDIA drivers and the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) must be installed on the host. The sandbox image itself must include the appropriate GPU drivers and libraries for your workload. See the [bring your own container example](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container) for building an image with GPU support.
193193

194-
## Supported Agents
194+
## Run Your Agent
195195

196-
| Agent | Source | Notes |
197-
| ------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
198-
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Works out of the box. Provider uses `ANTHROPIC_API_KEY`. |
199-
| [OpenCode](https://opencode.ai/) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Works out of the box. Provider uses `OPENAI_API_KEY` or `OPENROUTER_API_KEY`. |
200-
| [Codex](https://developers.openai.com/codex) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Works out of the box. Provider uses `OPENAI_API_KEY`. |
201-
| [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Works out of the box. Provider uses `GITHUB_TOKEN` or `COPILOT_GITHUB_TOKEN`. |
202-
| [OpenClaw](https://openclaw.ai/) | [NemoClaw](https://github.com/NVIDIA/NemoClaw) | Run OpenClaw more securely inside NVIDIA OpenShell with the NemoClaw blueprint. |
203-
| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | [NemoClaw](https://github.com/NVIDIA/NemoClaw) | Run Hermes Agent more securely inside NVIDIA OpenShell with the NemoClaw blueprint. |
204-
| [Ollama](https://ollama.com/) | [Community](https://github.com/NVIDIA/OpenShell-Community) | Launch with `openshell sandbox create --from ollama`. |
205-
| [Pi](https://pi.dev/) | [Community](https://github.com/NVIDIA/OpenShell-Community) | Launch with `openshell sandbox create --from pi`. |
196+
OpenShell can run an agent that works in a Linux container. Build a versioned
197+
image with the agent and its dependencies, publish it where the gateway can
198+
pull it, then attach the providers and policy that the workflow requires. See
199+
[Run an Agent](https://docs.nvidia.com/openshell/latest/about/run-an-agent) for
200+
the complete workflow.
206201

207202
## Key Commands
208203

209204
| Command | Description |
210205
| ---------------------------------------------------------- | ----------------------------------------------- |
211-
| `openshell sandbox create -- <agent>` | Create a sandbox and launch an agent. |
206+
| `openshell sandbox create --from <image> -- <agent>` | Create a sandbox from your image and launch its agent. |
212207
| `openshell sandbox connect [name]` | SSH into a running sandbox. |
213208
| `openshell sandbox list` | List all sandboxes. |
214209
| `openshell provider create --type [type] --from-existing` | Create a credential provider from env vars. |
@@ -234,23 +229,25 @@ openshell term
234229

235230
The TUI gives you a live, keyboard-driven view of your gateway and sandboxes. Navigate with `Tab` to switch panels, `j`/`k` to move through lists, `Enter` to select, and `:` for command mode. Gateway health and sandbox status auto-refresh every two seconds.
236231

237-
## Community Sandboxes and BYOC
232+
## Workload Images
238233

239-
Use `--from` to create sandboxes from the [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) catalog or a container image:
234+
Use `--from` to create sandboxes from an OCI image or root filesystem archive
235+
that you maintain:
240236

241237
```bash
242-
openshell sandbox create --from gemini # community catalog
243238
docker build -t my-sandbox:latest ./my-sandbox-dir # Docker gateway
244239
openshell sandbox create --from my-sandbox:latest # Docker built image
245240
podman build -t localhost/my-sandbox:latest ./my-sandbox-dir # Podman gateway
246241
openshell sandbox create --from localhost/my-sandbox:latest # Podman built image
247-
openshell sandbox create --from registry.io/img:v1 # container image
242+
docker build -t registry.example.com/team/agent:v1 ./my-sandbox-dir
243+
docker push registry.example.com/team/agent:v1
244+
openshell sandbox create --from registry.example.com/team/agent:v1
248245
```
249246

250247
Build with the container engine used by your local gateway. For a remote
251248
gateway, push the image to a registry that the gateway can pull from.
252249

253-
See the [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) catalog and the [BYOC example](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container) for details.
250+
See the [bring your own container example](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container) for details.
254251

255252
## Use OpenShell with Your Agent
256253

‎TESTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,7 @@ the current checkout.
207207
The phase-1 scenario verifies the complete CLI-to-gateway-to-driver path without
208208
depending on how the gateway was installed or which driver is configured. It
209209
requires machine-readable gRPC status, creates a uniquely named detached
210-
sandbox with `--from base`, verifies the sandbox is `Ready` by finding its
210+
sandbox with an explicit test image, verifies the sandbox is `Ready` by finding its
211211
unique name in paginated JSON list output, executes `echo` with a run-specific
212212
marker, deletes the sandbox, and verifies that its name no longer appears.
213213
Driver suites enable the same profile

‎architecture/build.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ OpenShell builds these main artifacts:
2323
| VM driver/runtime assets | `crates/openshell-driver-vm` |
2424
| Published docs site | `docs/` rendered by Fern config in `fern/` |
2525

26-
Sandbox community images are built outside this repository.
26+
Users build and publish the workload images that run inside sandboxes.
2727

2828
## Build Features
2929

‎architecture/compute-runtimes.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -401,9 +401,8 @@ readiness.
401401

402402
## Images
403403

404-
The gateway image and Helm chart are built from this repository. Sandbox images
405-
are maintained separately in the OpenShell Community repository or supplied by
406-
users.
404+
The gateway image and Helm chart are built from this repository. Users build,
405+
publish, and maintain the workload images used by their sandboxes.
407406

408407
Custom sandbox images must include the agent runtime and any system
409408
dependencies, but they should not need to include the gateway. GPU-capable

‎crates/openshell-sdk/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ client
113113
}),
114114
spec: Some(SandboxWorkloadTemplateSpec {
115115
workload: Some(SandboxWorkloadConfig {
116-
image: "ghcr.io/nvidia/openshell-community/sandboxes/python:latest".to_string(),
116+
image: "registry.example.com/team/python-agent:1.0".to_string(),
117117
..Default::default()
118118
}),
119119
..Default::default()

‎deploy/helm/openshell/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -311,7 +311,7 @@ discovery endpoint or its TLS CA.
311311
| server.policyValidationFailureMode | string | `"fail_closed"` | Posture when a candidate sandbox policy fails validation. `fail_closed` deactivates the previous policy; `retain_last_valid` keeps it active. |
312312
| server.providerTokenGrants.spiffe.enabled | bool | `false` | Mount the SPIFFE Workload API socket into gateway and sandbox pods for dynamic provider token grants. |
313313
| server.providerTokenGrants.spiffe.workloadApiSocketPath | string | `"/spiffe-workload-api/spire-agent.sock"` | Path to the SPIFFE Workload API socket mounted into gateway and sandbox pods. |
314-
| server.sandboxImage | string | `"ghcr.io/nvidia/openshell-community/sandboxes/base:latest"` | Default sandbox image used when requests do not specify one. |
314+
| server.sandboxImage | string | `"docker.io/library/alpine:3.22"` | Minimal fallback image used when requests do not specify one. Supply your own image for agent workloads. |
315315
| server.sandboxImagePullPolicy | string | `nil` | Pull policy for sandbox pods. Leave unset to use the Kubernetes image default (Always for :latest, IfNotPresent otherwise). Prefer always, if_not_present, or never; the chart also accepts legacy Kubernetes spellings Always, IfNotPresent, and Never. |
316316
| server.sandboxImagePullSecrets | list | `[]` | Image pull secrets attached to sandbox pods. Referenced Secrets must exist in the sandbox namespace. |
317317
| server.sandboxJwt.gatewayId | string | `""` | Stable gateway identity embedded in iss/aud of every minted token. Defaults to the release name so HA replicas share identity. |

‎deploy/rpm/CONFIGURATION.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,7 @@ overrides that persist across package upgrades.
220220
|-------------|---------|-------------|
221221
| `bind_address` | `127.0.0.1:17670` (gateway default) | Address for the primary gRPC/HTTP API listener. |
222222
| `compute_driver` | `"podman"` (RPM default) | When unset, the gateway auto-detects Kubernetes, then Podman, then Docker. The RPM default pins to Podman; legacy `compute_drivers` lists are rejected. |
223-
| `[openshell.drivers.podman].default_image` | `ghcr.io/nvidia/openshell-community/sandboxes/base:latest` | Default sandbox image. |
223+
| `[openshell.drivers.podman].default_image` | `docker.io/library/alpine:3.22` | Minimal fallback image. Supply your own image for agent workloads. |
224224
| `[openshell.drivers.podman].sandbox_runtime_image` | `ghcr.io/nvidia/openshell/sandbox:latest` | Static musl sandbox runtime image mounted into Podman workloads. |
225225
| `[openshell.drivers.podman].supervisor_image` | `ghcr.io/nvidia/openshell/supervisor:latest` | Dynamic glibc supervisor image used outside the workload. |
226226
| `[openshell.gateway].guest_tls_ca`, `guest_tls_cert`, `guest_tls_key` | auto-generated paths | Gateway-owned client TLS material injected into the selected local driver and mounted into sandbox containers. |
@@ -244,7 +244,7 @@ compute_driver = "podman"
244244

245245
[openshell.drivers.podman]
246246
network_name = "openshell"
247-
default_image = "ghcr.io/nvidia/openshell-community/sandboxes/base:latest"
247+
default_image = "docker.io/library/alpine:3.22"
248248
image_pull_policy = "if_not_present"
249249
health_check_interval_secs = 10
250250
stop_timeout_secs = 10
@@ -260,7 +260,7 @@ To update cached images:
260260

261261
```shell
262262
podman pull ghcr.io/nvidia/openshell/supervisor:latest
263-
podman pull ghcr.io/nvidia/openshell-community/sandboxes/base:latest
263+
podman pull registry.example.com/team/agent:1.0
264264
```
265265

266266
Or set `image_pull_policy = "always"` in
@@ -272,7 +272,7 @@ To pin specific image versions instead of `:latest`, set these values in
272272
```toml
273273
sandbox_runtime_image = "ghcr.io/nvidia/openshell/sandbox:v0.0.37"
274274
supervisor_image = "ghcr.io/nvidia/openshell/supervisor:v0.0.37"
275-
default_image = "ghcr.io/nvidia/openshell-community/sandboxes/base:v0.0.37"
275+
default_image = "registry.example.com/team/agent:1.0"
276276
```
277277

278278
For air-gapped environments:
@@ -281,9 +281,9 @@ For air-gapped environments:
281281

282282
```shell
283283
podman pull ghcr.io/nvidia/openshell/supervisor:latest
284-
podman pull ghcr.io/nvidia/openshell-community/sandboxes/base:latest
284+
podman pull registry.example.com/team/agent:1.0
285285
podman save -o supervisor.tar ghcr.io/nvidia/openshell/supervisor:latest
286-
podman save -o sandbox.tar ghcr.io/nvidia/openshell-community/sandboxes/base:latest
286+
podman save -o sandbox.tar registry.example.com/team/agent:1.0
287287
```
288288

289289
1. Transfer the tarballs to the air-gapped host and load them:

‎deploy/rpm/TROUBLESHOOTING.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -176,7 +176,7 @@ sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER
176176
**Image pull failure.** Verify ghcr.io is reachable:
177177

178178
```shell
179-
podman pull ghcr.io/nvidia/openshell-community/sandboxes/base:latest
179+
podman pull registry.example.com/team/agent:1.0
180180
```
181181

182182
### Images not updating
@@ -185,7 +185,7 @@ The default image pull policy is `if_not_present` -- images are pulled once
185185
and cached. To update:
186186

187187
```shell
188-
podman pull ghcr.io/nvidia/openshell-community/sandboxes/base:latest
188+
podman pull registry.example.com/team/agent:1.0
189189
podman pull ghcr.io/nvidia/openshell/supervisor:latest
190190
```
191191

@@ -239,7 +239,7 @@ To pick up new container images after an upgrade:
239239

240240
```shell
241241
podman pull ghcr.io/nvidia/openshell/supervisor:latest
242-
podman pull ghcr.io/nvidia/openshell-community/sandboxes/base:latest
242+
podman pull registry.example.com/team/agent:1.0
243243
```
244244

245245
### Migrating a TLS-enabled local driver to schema version 2

‎docs/about/how-it-works.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
22
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
33
# SPDX-License-Identifier: Apache-2.0
4-
title: "How OpenShell Works"
5-
sidebar-title: "How It Works"
4+
title: "Architecture"
5+
sidebar-title: "Architecture"
66
description: "Understand the OpenShell architecture, runtime boundaries, gateways, sandboxes, and ecosystem integration points."
77
keywords: "Generative AI, Cybersecurity, AI Agents, Architecture, Gateway, Sandbox, Providers"
88
position: 2
@@ -90,7 +90,7 @@ device plugins without changing the gateway and sandbox contract.
9090
| [Gateways](/sandboxes/manage-gateways) | Authenticated control plane that owns API access, durable state, sandbox lifecycle, settings delivery, authorization, and relay coordination. |
9191
| [Providers](/sandboxes/manage-providers) | Credential and provider records that map logical agent needs to platform or user-managed secrets without exposing raw credentials to the agent process. |
9292
| [Policies](/sandboxes/policies) | Declarative controls for filesystem access, process identity, network egress, L7 rules, credential injection, and runtime policy updates. |
93-
| [Provider-backed Inference](/sandboxes/inference-routing) | Per-sandbox provider attachment, native model endpoints, and endpoint-bound credential injection. |
93+
| [Inference](/sandboxes/inference-routing) | Per-sandbox provider attachment, native model endpoints, and endpoint-bound credential injection. |
9494

9595
## Gateways and Sandboxes
9696

‎docs/about/installation.mdx‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Installation, Se
88
position: 3
99
---
1010

11+
Install OpenShell on a local workstation, choose the compute driver that runs
12+
your sandboxes, and verify the package-managed gateway configuration.
13+
1114
## Install OpenShell
1215

1316
Install OpenShell with a single command:
@@ -160,14 +163,6 @@ sudo systemctl restart snap.openshell.gateway
160163

161164
Kubernetes deployments use the OpenShell Helm chart. For step-by-step installation, refer to [Kubernetes Setup](/kubernetes/setup). For chart values and packaging details, refer to the [Helm chart README](https://github.com/NVIDIA/OpenShell/blob/main/deploy/helm/openshell/README.md).
162165

163-
## Next Steps
164-
165-
- To create your first sandbox, refer to the [Quickstart](/get-started/quickstart).
166-
- To run the gateway as a container without the installer, refer to [Running the Gateway as a Container](/about/container-gateway).
167-
- To register, select, and inspect gateways, refer to [Gateways](/sandboxes/manage-gateways).
168-
- To supply API keys or tokens, refer to [Manage Providers](/sandboxes/manage-providers).
169-
- To control what the agent can access, refer to [Policies](/sandboxes/policies).
170-
171166
## Validate a package-managed gateway configuration
172167

173168
Debian and Ubuntu packages validate the selected gateway configuration before
@@ -194,3 +189,12 @@ Snap replays its effective daemon arguments through preflight and gives a nonemp
194189
`OPENSHELL_GATEWAY_CONFIG` precedence over `SNAP_COMMON/gateway.toml`.
195190
See [Gateway Configuration](/reference/gateway-config#gateway-config-preflight)
196191
for preflight details and manual schema-v1 migration steps.
192+
193+
## Next Steps
194+
195+
- To launch an agent, refer to [Run an Agent](/about/run-an-agent).
196+
- To create your first sandbox, refer to the [Quickstart](/get-started/quickstart).
197+
- To run the gateway as a container without the installer, refer to [Running the Gateway as a Container](/reference/container-gateway).
198+
- To register, select, and inspect gateways, refer to [Gateways](/sandboxes/manage-gateways).
199+
- To supply API keys or tokens, refer to [Manage Providers](/sandboxes/manage-providers).
200+
- To control what the agent can access, refer to [Policies](/sandboxes/policies).

0 commit comments

Comments
 (0)