You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 4107bb3
Browse filesBrowse the repository at this point in the historyBrowse files
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.
72
72
73
73
### See network policy in action
74
74
@@ -184,31 +184,26 @@ Inference access uses the same provider workflow. Attach an inference-capable pr
184
184
OpenShell can pass host GPUs into sandboxes for local inference, fine-tuning, or any GPU workload. Add `--gpu` when creating a sandbox:
185
185
186
186
```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
188
188
```
189
189
190
190
Docker-backed GPU sandboxes auto-select CDI when available and otherwise fall back to Docker's NVIDIA GPU request path (`--gpus all`).
191
191
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.
|[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
|`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. |
212
207
|`openshell sandbox connect [name]`| SSH into a running sandbox. |
213
208
|`openshell sandbox list`| List all sandboxes. |
214
209
|`openshell provider create --type [type] --from-existing`| Create a credential provider from env vars. |
@@ -234,23 +229,25 @@ openshell term
234
229
235
230
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.
236
231
237
-
## Community Sandboxes and BYOC
232
+
## Workload Images
238
233
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:
240
236
241
237
```bash
242
-
openshell sandbox create --from gemini # community catalog
Build with the container engine used by your local gateway. For a remote
251
248
gateway, push the image to a registry that the gateway can pull from.
252
249
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.
Copy file name to clipboardExpand all lines: deploy/helm/openshell/README.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -311,7 +311,7 @@ discovery endpoint or its TLS CA.
311
311
| 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. |
312
312
| server.providerTokenGrants.spiffe.enabled | bool |`false`| Mount the SPIFFE Workload API socket into gateway and sandbox pods for dynamic provider token grants. |
313
313
| 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. |
315
315
| 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. |
316
316
| server.sandboxImagePullSecrets | list |`[]`| Image pull secrets attached to sandbox pods. Referenced Secrets must exist in the sandbox namespace. |
317
317
| 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. |
Copy file name to clipboardExpand all lines: deploy/rpm/CONFIGURATION.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -220,7 +220,7 @@ overrides that persist across package upgrades.
220
220
|-------------|---------|-------------|
221
221
|`bind_address`|`127.0.0.1:17670` (gateway default) | Address for the primary gRPC/HTTP API listener. |
222
222
|`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. |
|`[openshell.drivers.podman].supervisor_image`|`ghcr.io/nvidia/openshell/supervisor:latest`| Dynamic glibc supervisor image used outside the workload. |
226
226
|`[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. |
Copy file name to clipboardExpand all lines: docs/about/how-it-works.mdx
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,8 @@
1
1
---
2
2
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
3
3
# SPDX-License-Identifier: Apache-2.0
4
-
title: "How OpenShell Works"
5
-
sidebar-title: "How It Works"
4
+
title: "Architecture"
5
+
sidebar-title: "Architecture"
6
6
description: "Understand the OpenShell architecture, runtime boundaries, gateways, sandboxes, and ecosystem integration points."
7
7
keywords: "Generative AI, Cybersecurity, AI Agents, Architecture, Gateway, Sandbox, Providers"
8
8
position: 2
@@ -90,7 +90,7 @@ device plugins without changing the gateway and sandbox contract.
90
90
|[Gateways](/sandboxes/manage-gateways)| Authenticated control plane that owns API access, durable state, sandbox lifecycle, settings delivery, authorization, and relay coordination. |
91
91
|[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. |
92
92
|[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. |
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).
162
165
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
-
171
166
## Validate a package-managed gateway configuration
172
167
173
168
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
194
189
`OPENSHELL_GATEWAY_CONFIG` precedence over `SNAP_COMMON/gateway.toml`.
195
190
See [Gateway Configuration](/reference/gateway-config#gateway-config-preflight)
196
191
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