Skip to content

Commit 425afb3

Browse files
drewdrew
authored
docs(readme): improve clarity, structure, and contributor discoverability (#336)
1 parent f71fd33 commit 425afb3

File tree

1 file changed

+74
-48
lines changed

1 file changed

+74
-48
lines changed

‎README.md‎

Lines changed: 74 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,14 @@
22

33
[![License](https://img.shields.io/badge/License-Apache_2.0-blue)](https://github.com/NVIDIA/OpenShell/blob/main/LICENSE)
44
[![PyPI](https://img.shields.io/badge/PyPI-openshell-orange?logo=pypi)](https://pypi.org/project/openshell/)
5+
[![Security Policy](https://img.shields.io/badge/Security-Report%20a%20Vulnerability-red)](SECURITY.md)
6+
[![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)
57

68
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.
79

8-
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.
10+
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.
911

10-
> **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.
12+
> **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.
1113
1214
## Quickstart
1315

@@ -49,10 +51,10 @@ uv tool install -U openshell
4951
### Create a sandbox
5052

5153
```bash
52-
openshell sandbox create -- claude # or opencode, codex, --from openclaw
54+
openshell sandbox create -- claude # or opencode, codex
5355
```
5456

55-
A gateway cluster is created automatically on first use. To deploy on a remote host instead, use `openshell gateway start --remote user@host`.
57+
A gateway is created automatically on first use. To deploy on a remote host instead, pass `--remote user@host` to the create command.
5658

5759
The sandbox container includes the following tools by default:
5860

@@ -63,25 +65,15 @@ The sandbox container includes the following tools by default:
6365
| Developer | `gh`, `git`, `vim`, `nano` |
6466
| Networking | `ping`, `dig`, `nslookup`, `nc`, `traceroute`, `netstat` |
6567

66-
### Explore with your agent
67-
68-
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.
69-
70-
```bash
71-
git clone https://github.com/NVIDIA/OpenShell.git # or git@github.com:NVIDIA/OpenShell.git
72-
cd OpenShell
73-
# Point your agent here — it will discover the skills in .agents/skills/ automatically
74-
```
75-
76-
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.
68+
For more details see https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base.
7769

7870
### See network policy in action
7971

8072
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.
8173

8274
```bash
8375
# 1. Create a sandbox (starts with minimal outbound access)
84-
openshell sandbox create --name demo --keep --no-auto-providers
76+
openshell sandbox create
8577

8678
# 2. Inside the sandbox — blocked
8779
sandbox$ curl -sS https://api.github.com/zen
@@ -106,6 +98,23 @@ See the [full walkthrough](examples/sandbox-policy-quickstart/) or run the autom
10698
bash examples/sandbox-policy-quickstart/demo.sh
10799
```
108100

101+
## How It Works
102+
103+
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:
104+
105+
- **Allows** — the destination and binary match a policy block.
106+
- **Routes for inference** — strips caller credentials, injects backend credentials, and forwards to the managed model.
107+
- **Denies** — blocks the request and logs it.
108+
109+
| Component | Role |
110+
| ------------------ | -------------------------------------------------------------------------------------------- |
111+
| **Gateway** | Control-plane API that coordinates sandbox lifecycle and acts as the auth boundary. |
112+
| **Sandbox** | Isolated runtime with container supervision and policy-enforced egress routing. |
113+
| **Policy Engine** | Enforces filesystem, network, and process constraints from application layer down to kernel. |
114+
| **Privacy Router** | Privacy-aware LLM routing that keeps sensitive context on sandbox compute. |
115+
116+
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.
117+
109118
## Protection Layers
110119

111120
OpenShell applies defense in depth across four policy domains:
@@ -119,46 +128,44 @@ OpenShell applies defense in depth across four policy domains:
119128

120129
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`.
121130

122-
## Supported Agents
131+
## Providers
123132

124-
| Agent | Source | Notes |
125-
| ------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------ |
126-
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Built-in | Works out of the box. Requires `ANTHROPIC_API_KEY`. |
127-
| [OpenCode](https://opencode.ai/) | Built-in | Works out of the box. Requires `OPENAI_API_KEY` or `OPENROUTER_API_KEY`. |
128-
| [Codex](https://developers.openai.com/codex) | Built-in | Works out of the box. Requires `OPENAI_API_KEY`. |
129-
| [OpenClaw](https://openclaw.ai/) | [Community](https://github.com/NVIDIA/OpenShell-Community) | Launch with `openshell sandbox create --from openclaw`. |
133+
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.
130134

131-
## How It Works
135+
## GPU Support
132136

133-
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:
137+
OpenShell can pass host GPUs into sandboxes for local inference, fine-tuning, or any GPU workload. Add `--gpu` when creating a sandbox:
134138

135-
- **Allows** — the destination and binary match a policy block.
136-
- **Routes for inference** — strips caller credentials, injects backend credentials, and forwards to the managed model.
137-
- **Denies** — blocks the request and logs it.
139+
```bash
140+
openshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude
141+
```
138142

139-
Under the hood, the gateway runs as a [K3s](https://k3s.io/) Kubernetes cluster inside Docker — no separate K8s install required.
143+
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.
140144

141-
| Component | Role |
142-
| ------------------ | -------------------------------------------------------------------------------------------- |
143-
| **Gateway** | Control-plane API that coordinates sandbox lifecycle and acts as the auth boundary. |
144-
| **Sandbox** | Isolated runtime with container supervision and policy-enforced egress routing. |
145-
| **Policy Engine** | Enforces filesystem, network, and process constraints from application layer down to kernel. |
146-
| **Privacy Router** | Privacy-aware LLM routing that keeps sensitive context on sandbox compute. |
145+
**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.
146+
147+
## Supported Agents
148+
149+
| Agent | Source | Notes |
150+
| ------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
151+
| [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`. |
152+
| [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`. |
153+
| [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`. |
154+
| [OpenClaw](https://openclaw.ai/) | [Community](https://github.com/NVIDIA/OpenShell-Community) | Launch with `openshell sandbox create --from openclaw`. |
147155

148156
## Key Commands
149157

150-
| Command | Description |
151-
| --------------------------------------------------------- | ----------------------------------------------- |
152-
| `openshell sandbox create -- <agent>` | Create a sandbox and launch an agent. |
153-
| `openshell sandbox connect [name]` | SSH into a running sandbox. |
154-
| `openshell sandbox list` | List all sandboxes. |
155-
| `openshell sandbox delete <name>` | Delete a sandbox. |
156-
| `openshell provider create --type claude --from-existing` | Create a credential provider from env vars. |
157-
| `openshell policy set <name> --policy file.yaml` | Apply or update a policy on a running sandbox. |
158-
| `openshell policy get <name>` | Show the active policy. |
159-
| `openshell inference set --provider <p> --model <m>` | Configure the `inference.local` endpoint. |
160-
| `openshell logs [name] --tail` | Stream sandbox logs. |
161-
| `openshell term` | Launch the real-time terminal UI for debugging. |
158+
| Command | Description |
159+
| ---------------------------------------------------------- | ----------------------------------------------- |
160+
| `openshell sandbox create -- <agent>` | Create a sandbox and launch an agent. |
161+
| `openshell sandbox connect [name]` | SSH into a running sandbox. |
162+
| `openshell sandbox list` | List all sandboxes. |
163+
| `openshell provider create --type [type]] --from-existing` | Create a credential provider from env vars. |
164+
| `openshell policy set <name> --policy file.yaml` | Apply or update a policy on a running sandbox. |
165+
| `openshell policy get <name>` | Show the active policy. |
166+
| `openshell inference set --provider <p> --model <m>` | Configure the `inference.local` endpoint. |
167+
| `openshell logs [name] --tail` | Stream sandbox logs. |
168+
| `openshell term` | Launch the real-time terminal UI for debugging. |
162169

163170
See the full [CLI reference](https://github.com/NVIDIA/OpenShell/blob/main/docs/reference/cli.md) for all commands, flags, and environment variables.
164171

@@ -188,6 +195,18 @@ openshell sandbox create --from registry.io/img:v1 # container image
188195

189196
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.
190197

198+
## Explore with Your Agent
199+
200+
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.
201+
202+
```bash
203+
git clone https://github.com/NVIDIA/OpenShell.git # or git@github.com:NVIDIA/OpenShell.git
204+
cd OpenShell
205+
# Point your agent here — it will discover the skills in .agents/skills/ automatically
206+
```
207+
208+
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.
209+
191210
## Built With Agents
192211

193212
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 +218,16 @@ OpenShell is developed using the same agent-driven workflows it enables. The `.a
199218

200219
All implementation work is human-gated — agents propose plans, humans approve, agents build. See [AGENTS.md](AGENTS.md) for the full workflow chain documentation.
201220

221+
## Getting Help
222+
223+
- **Questions and discussion:** [GitHub Discussions](https://github.com/NVIDIA/OpenShell/discussions)
224+
- **Bug reports:** [GitHub Issues](https://github.com/NVIDIA/OpenShell/issues) — use the bug report template
225+
- **Security vulnerabilities:** See [SECURITY.md](SECURITY.md) — do not use GitHub Issues
226+
- **Agent-assisted help:** Clone the repo and use the agent skills in `.agents/skills/` for self-service diagnostics
227+
202228
## Learn More
203229

204-
- [Full Documentation](https://github.com/NVIDIA/OpenShell/tree/main/docs) — overview, architecture, tutorials, and reference
230+
- [Full Documentation](https://docs.nvidia.com/openshell/latest/index.html) — overview, architecture, tutorials, and reference
205231
- [Quickstart](https://github.com/NVIDIA/OpenShell/blob/main/docs/get-started/quickstart.md) — detailed install and first sandbox walkthrough
206232
- [GitHub Sandbox Tutorial](https://github.com/NVIDIA/OpenShell/blob/main/docs/tutorials/github-sandbox.md) — end-to-end scoped GitHub repo access
207233
- [Architecture](https://github.com/NVIDIA/OpenShell/tree/main/architecture) — detailed architecture docs and design decisions

0 commit comments

Comments
 (0)