diff --git a/README.md b/README.md index 07cd2826..b30b8134 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,14 @@ [![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. +> **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 @@ -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 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: @@ -63,17 +65,7 @@ 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. +For more details see https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base. ### See network policy in action @@ -81,7 +73,7 @@ Every sandbox starts with **minimal outbound access**. You open additional acces ```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,6 +98,23 @@ See the [full walkthrough](examples/sandbox-policy-quickstart/) or run the autom bash examples/sandbox-policy-quickstart/demo.sh ``` +## 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: + +- **Allows** — the destination and binary match a policy block. +- **Routes for inference** — strips caller credentials, injects backend credentials, and forwards to the managed model. +- **Denies** — blocks the request and logs it. + +| Component | Role | +| ------------------ | -------------------------------------------------------------------------------------------- | +| **Gateway** | Control-plane API that coordinates sandbox lifecycle and acts as the auth boundary. | +| **Sandbox** | Isolated runtime with container supervision and policy-enforced egress routing. | +| **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. | + +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 OpenShell applies defense in depth across four policy domains: @@ -119,46 +128,44 @@ 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`. -## Supported Agents +## Providers -| 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`. | +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. -## How It Works +## GPU Support -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: +OpenShell can pass host GPUs into sandboxes for local inference, fine-tuning, or any GPU workload. Add `--gpu` when creating a sandbox: -- **Allows** — the destination and binary match a policy block. -- **Routes for inference** — strips caller credentials, injects backend credentials, and forwards to the managed model. -- **Denies** — blocks the request and logs it. +```bash +openshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude +``` -Under the hood, the gateway runs as a [K3s](https://k3s.io/) Kubernetes cluster inside Docker — no separate K8s install required. +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. -| Component | Role | -| ------------------ | -------------------------------------------------------------------------------------------- | -| **Gateway** | Control-plane API that coordinates sandbox lifecycle and acts as the auth boundary. | -| **Sandbox** | Isolated runtime with container supervision and policy-enforced egress routing. | -| **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. | +**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 | +| ------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | +| [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 +195,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 +218,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