From 5cf9767e0349d628dcb221d59bbe8ab59caefa05 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Sun, 15 Mar 2026 21:16:55 -0700 Subject: [PATCH 1/3] docs(readme): improve clarity, structure, and contributor discoverability Reorder sections so How It Works follows Quickstart. Add Security Policy and Good First Issues badges. Add contributing callout after alpha notice. Add Getting Help section. Add providers blurb under How It Works. Link Supported Agents source column to the community base image. Move Explore with Your Agent before Built With Agents. Update Full Documentation URL to docs.nvidia.com. --- README.md | 112 +++++++++++++++++++++++++++++------------------------- 1 file changed, 61 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 07cd2826..0ff66a3e 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,12 @@ [![License](https://img.shields.io/badge/License-Apache_2.0-blue)](https://github.com/NVIDIA/OpenShell/blob/main/LICENSE) [![PyPI](https://img.shields.io/badge/PyPI-openshell-orange?logo=pypi)](https://pypi.org/project/openshell/) +[![Security Policy](https://img.shields.io/badge/Security-Report%20a%20Vulnerability-red)](SECURITY.md) +[![Good First Issues](https://img.shields.io/github/issues/NVIDIA/OpenShell/good%20first%20issue?label=good%20first%20issues&color=7057ff)](https://github.com/NVIDIA/OpenShell/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) OpenShell is the safe, private runtime for autonomous AI agents. It provides sandboxed execution environments that protect your data, credentials, and infrastructure — governed by declarative YAML policies that prevent unauthorized file access, data exfiltration, and uncontrolled network activity. -OpenShell is built agent-first. The project ships with agent skills for everything from cluster debugging to policy generation, and we expect contributors to use them. +OpenShell is built agent-first. The project ships with agent skills for everything from cluster debugging to policy generation, and we expect contributors to use them. > **Alpha software — single-player mode.** OpenShell is proof-of-life: one developer, one environment, one cluster. We are building toward multi-tenant enterprise deployments, but the starting point is getting your own environment up and running. Expect rough edges. Bring your agent. @@ -49,10 +51,10 @@ uv tool install -U openshell ### Create a sandbox ```bash -openshell sandbox create -- claude # or opencode, codex, --from openclaw +openshell sandbox create -- claude # or opencode, codex ``` -A gateway cluster is created automatically on first use. To deploy on a remote host instead, use `openshell gateway start --remote user@host`. +A gateway cluster is created automatically on first use. To deploy on a remote host instead, pass `--remote user@host`. The sandbox container includes the following tools by default: @@ -63,25 +65,13 @@ The sandbox container includes the following tools by default: | Developer | `gh`, `git`, `vim`, `nano` | | Networking | `ping`, `dig`, `nslookup`, `nc`, `traceroute`, `netstat` | -### Explore with your agent - -Clone the repo and point your coding agent at it. The project includes agent skills that can answer questions, walk you through workflows, and diagnose problems — no issue filing required. - -```bash -git clone https://github.com/NVIDIA/OpenShell.git # or git@github.com:NVIDIA/OpenShell.git -cd OpenShell -# Point your agent here — it will discover the skills in .agents/skills/ automatically -``` - -Your agent can load skills for CLI usage (`openshell-cli`), cluster troubleshooting (`debug-openshell-cluster`), policy generation (`generate-sandbox-policy`), and more. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full skills table. - ### See network policy in action Every sandbox starts with **minimal outbound access**. You open additional access with a short YAML policy that the proxy enforces at the HTTP method and path level, without restarting anything. ```bash # 1. Create a sandbox (starts with minimal outbound access) -openshell sandbox create --name demo --keep --no-auto-providers +openshell sandbox create # 2. Inside the sandbox — blocked sandbox$ curl -sS https://api.github.com/zen @@ -106,28 +96,6 @@ See the [full walkthrough](examples/sandbox-policy-quickstart/) or run the autom bash examples/sandbox-policy-quickstart/demo.sh ``` -## Protection Layers - -OpenShell applies defense in depth across four policy domains: - -| Layer | What it protects | When it applies | -| ---------- | --------------------------------------------------- | --------------------------- | -| Filesystem | Prevents reads/writes outside allowed paths. | Locked at sandbox creation. | -| Network | Blocks unauthorized outbound connections. | Hot-reloadable at runtime. | -| Process | Blocks privilege escalation and dangerous syscalls. | Locked at sandbox creation. | -| Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. | - -Policies are declarative YAML files. Static sections (filesystem, process) are locked at creation; dynamic sections (network, inference) can be hot-reloaded on a running sandbox with `openshell policy set`. - -## Supported Agents - -| Agent | Source | Notes | -| ------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------ | -| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Built-in | Works out of the box. Requires `ANTHROPIC_API_KEY`. | -| [OpenCode](https://opencode.ai/) | Built-in | Works out of the box. Requires `OPENAI_API_KEY` or `OPENROUTER_API_KEY`. | -| [Codex](https://developers.openai.com/codex) | Built-in | Works out of the box. Requires `OPENAI_API_KEY`. | -| [OpenClaw](https://openclaw.ai/) | [Community](https://github.com/NVIDIA/OpenShell-Community) | Launch with `openshell sandbox create --from openclaw`. | - ## How It Works OpenShell isolates each sandbox in its own container with policy-enforced egress routing. A lightweight gateway coordinates sandbox lifecycle, and every outbound connection is intercepted by the policy engine, which does one of three things: @@ -145,20 +113,43 @@ Under the hood, the gateway runs as a [K3s](https://k3s.io/) Kubernetes cluster | **Policy Engine** | Enforces filesystem, network, and process constraints from application layer down to kernel. | | **Privacy Router** | Privacy-aware LLM routing that keeps sensitive context on sandbox compute. | +Agents need credentials — API keys, tokens, service accounts. OpenShell manages these as **providers**: named credential bundles that are injected into sandboxes at creation. The CLI auto-discovers credentials for recognized agents (Claude, Codex, OpenCode) from your shell environment, or you can create providers explicitly with `openshell provider create`. Credentials never leak into the sandbox filesystem; they are injected as environment variables at runtime. + +## Protection Layers + +OpenShell applies defense in depth across four policy domains: + +| Layer | What it protects | When it applies | +| ---------- | --------------------------------------------------- | --------------------------- | +| Filesystem | Prevents reads/writes outside allowed paths. | Locked at sandbox creation. | +| Network | Blocks unauthorized outbound connections. | Hot-reloadable at runtime. | +| Process | Blocks privilege escalation and dangerous syscalls. | Locked at sandbox creation. | +| Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. | + +Policies are declarative YAML files. Static sections (filesystem, process) are locked at creation; dynamic sections (network, inference) can be hot-reloaded on a running sandbox with `openshell policy set`. + +## Supported Agents + +| Agent | Source | Notes | +| ------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | +| [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`. | +| [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`. | +| [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`. | +| [OpenClaw](https://openclaw.ai/) | [Community](https://github.com/NVIDIA/OpenShell-Community) | Launch with `openshell sandbox create --from openclaw`. | + ## Key Commands -| Command | Description | -| --------------------------------------------------------- | ----------------------------------------------- | -| `openshell sandbox create -- ` | Create a sandbox and launch an agent. | -| `openshell sandbox connect [name]` | SSH into a running sandbox. | -| `openshell sandbox list` | List all sandboxes. | -| `openshell sandbox delete ` | Delete a sandbox. | -| `openshell provider create --type claude --from-existing` | Create a credential provider from env vars. | -| `openshell policy set --policy file.yaml` | Apply or update a policy on a running sandbox. | -| `openshell policy get ` | Show the active policy. | -| `openshell inference set --provider

--model ` | Configure the `inference.local` endpoint. | -| `openshell logs [name] --tail` | Stream sandbox logs. | -| `openshell term` | Launch the real-time terminal UI for debugging. | +| Command | Description | +| ---------------------------------------------------------- | ----------------------------------------------- | +| `openshell sandbox create -- ` | Create a sandbox and launch an agent. | +| `openshell sandbox connect [name]` | SSH into a running sandbox. | +| `openshell sandbox list` | List all sandboxes. | +| `openshell provider create --type [type]] --from-existing` | Create a credential provider from env vars. | +| `openshell policy set --policy file.yaml` | Apply or update a policy on a running sandbox. | +| `openshell policy get ` | Show the active policy. | +| `openshell inference set --provider

--model ` | Configure the `inference.local` endpoint. | +| `openshell logs [name] --tail` | Stream sandbox logs. | +| `openshell term` | Launch the real-time terminal UI for debugging. | See the full [CLI reference](https://github.com/NVIDIA/OpenShell/blob/main/docs/reference/cli.md) for all commands, flags, and environment variables. @@ -188,6 +179,18 @@ openshell sandbox create --from registry.io/img:v1 # container image See the [community sandboxes](https://github.com/NVIDIA/OpenShell/blob/main/docs/sandboxes/community-sandboxes.md) catalog and the [BYOC example](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container) for details. +## Explore with Your Agent + +Clone the repo and point your coding agent at it. The project includes agent skills that can answer questions, walk you through workflows, and diagnose problems — no issue filing required. + +```bash +git clone https://github.com/NVIDIA/OpenShell.git # or git@github.com:NVIDIA/OpenShell.git +cd OpenShell +# Point your agent here — it will discover the skills in .agents/skills/ automatically +``` + +Your agent can load skills for CLI usage (`openshell-cli`), cluster troubleshooting (`debug-openshell-cluster`), policy generation (`generate-sandbox-policy`), and more. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full skills table. + ## Built With Agents OpenShell is developed using the same agent-driven workflows it enables. The `.agents/skills/` directory contains workflow automation that powers the project's development cycle: @@ -199,9 +202,16 @@ OpenShell is developed using the same agent-driven workflows it enables. The `.a All implementation work is human-gated — agents propose plans, humans approve, agents build. See [AGENTS.md](AGENTS.md) for the full workflow chain documentation. +## Getting Help + +- **Questions and discussion:** [GitHub Discussions](https://github.com/NVIDIA/OpenShell/discussions) +- **Bug reports:** [GitHub Issues](https://github.com/NVIDIA/OpenShell/issues) — use the bug report template +- **Security vulnerabilities:** See [SECURITY.md](SECURITY.md) — do not use GitHub Issues +- **Agent-assisted help:** Clone the repo and use the agent skills in `.agents/skills/` for self-service diagnostics + ## Learn More -- [Full Documentation](https://github.com/NVIDIA/OpenShell/tree/main/docs) — overview, architecture, tutorials, and reference +- [Full Documentation](https://docs.nvidia.com/openshell/latest/index.html) — overview, architecture, tutorials, and reference - [Quickstart](https://github.com/NVIDIA/OpenShell/blob/main/docs/get-started/quickstart.md) — detailed install and first sandbox walkthrough - [GitHub Sandbox Tutorial](https://github.com/NVIDIA/OpenShell/blob/main/docs/tutorials/github-sandbox.md) — end-to-end scoped GitHub repo access - [Architecture](https://github.com/NVIDIA/OpenShell/tree/main/architecture) — detailed architecture docs and design decisions From 0f91e0336cdd7482e399665a8ccd5b0dba3b8ea7 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Sun, 15 Mar 2026 21:48:11 -0700 Subject: [PATCH 2/3] docs(readme): add Providers, GPU Support sections and restructure Add dedicated Providers section explaining credential management. Add GPU Support section covering --gpu flag, auto-inference, host requirements, and custom image note. Move Providers after Protection Layers. Link to BYOC example for GPU sandbox images. --- README.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0ff66a3e..aaa7c27e 100644 --- a/README.md +++ b/README.md @@ -104,8 +104,6 @@ OpenShell isolates each sandbox in its own container with policy-enforced egress - **Routes for inference** — strips caller credentials, injects backend credentials, and forwards to the managed model. - **Denies** — blocks the request and logs it. -Under the hood, the gateway runs as a [K3s](https://k3s.io/) Kubernetes cluster inside Docker — no separate K8s install required. - | Component | Role | | ------------------ | -------------------------------------------------------------------------------------------- | | **Gateway** | Control-plane API that coordinates sandbox lifecycle and acts as the auth boundary. | @@ -113,7 +111,7 @@ Under the hood, the gateway runs as a [K3s](https://k3s.io/) Kubernetes cluster | **Policy Engine** | Enforces filesystem, network, and process constraints from application layer down to kernel. | | **Privacy Router** | Privacy-aware LLM routing that keeps sensitive context on sandbox compute. | -Agents need credentials — API keys, tokens, service accounts. OpenShell manages these as **providers**: named credential bundles that are injected into sandboxes at creation. The CLI auto-discovers credentials for recognized agents (Claude, Codex, OpenCode) from your shell environment, or you can create providers explicitly with `openshell provider create`. Credentials never leak into the sandbox filesystem; they are injected as environment variables at runtime. +Under the hood, all these components run as a [K3s](https://k3s.io/) Kubernetes cluster inside a single Docker container — no separate K8s install required. The `openshell gateway` commands take care of provisioning the container and cluster. ## Protection Layers @@ -128,6 +126,22 @@ OpenShell applies defense in depth across four policy domains: Policies are declarative YAML files. Static sections (filesystem, process) are locked at creation; dynamic sections (network, inference) can be hot-reloaded on a running sandbox with `openshell policy set`. +## Providers + +Agents need credentials — API keys, tokens, service accounts. OpenShell manages these as **providers**: named credential bundles that are injected into sandboxes at creation. The CLI auto-discovers credentials for recognized agents (Claude, Codex, OpenCode) from your shell environment, or you can create providers explicitly with `openshell provider create`. Credentials never leak into the sandbox filesystem; they are injected as environment variables at runtime. + +## GPU Support + +OpenShell can pass host GPUs into sandboxes for local inference, fine-tuning, or any GPU workload. Add `--gpu` when creating a sandbox: + +```bash +openshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude +``` + +The CLI auto-bootstraps a GPU-enabled gateway on first use. GPU intent is also inferred automatically for community images with `gpu` in the name (e.g., `--from nvidia-gpu`). + +**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. + ## Supported Agents | Agent | Source | Notes | From 6e8162dfcda957a1f28b1bd6fdf38cedf100e694 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Sun, 15 Mar 2026 21:57:53 -0700 Subject: [PATCH 3/3] docs(readme): minor wording tweaks for clarity Update alpha notice to say 'gateway' instead of 'cluster'. Clarify auto-bootstrap language. Add link to base sandbox source after tools table. Simplify GPU inference note. --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index aaa7c27e..b30b8134 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ OpenShell is the safe, private runtime for autonomous AI agents. It provides san OpenShell is built agent-first. The project ships with agent skills for everything from cluster debugging to policy generation, and we expect contributors to use them. -> **Alpha software — single-player mode.** OpenShell is proof-of-life: one developer, one environment, one cluster. We are building toward multi-tenant enterprise deployments, but the starting point is getting your own environment up and running. Expect rough edges. Bring your agent. +> **Alpha software — single-player mode.** OpenShell is proof-of-life: one developer, one environment, one gateway. We are building toward multi-tenant enterprise deployments, but the starting point is getting your own environment up and running. Expect rough edges. Bring your agent. ## Quickstart @@ -54,7 +54,7 @@ uv tool install -U openshell openshell sandbox create -- claude # or opencode, codex ``` -A gateway cluster is created automatically on first use. To deploy on a remote host instead, pass `--remote user@host`. +A gateway is created automatically on first use. To deploy on a remote host instead, pass `--remote user@host` to the create command. The sandbox container includes the following tools by default: @@ -65,6 +65,8 @@ The sandbox container includes the following tools by default: | Developer | `gh`, `git`, `vim`, `nano` | | Networking | `ping`, `dig`, `nslookup`, `nc`, `traceroute`, `netstat` | +For more details see https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base. + ### See network policy in action Every sandbox starts with **minimal outbound access**. You open additional access with a short YAML policy that the proxy enforces at the HTTP method and path level, without restarting anything. @@ -138,7 +140,7 @@ OpenShell can pass host GPUs into sandboxes for local inference, fine-tuning, or openshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude ``` -The CLI auto-bootstraps a GPU-enabled gateway on first use. GPU intent is also inferred automatically for community images with `gpu` in the name (e.g., `--from nvidia-gpu`). +The CLI auto-bootstraps a GPU-enabled gateway on first use. GPU intent is also inferred automatically for community images with `gpu` in the name. **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.