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.
- Docker — Docker Desktop (or a Docker daemon) must be running.
Binary (recommended):
curl -fsSL https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | shThe install script auto-detects your platform (Linux x86_64, Linux aarch64, macOS Apple Silicon) and places the openshell binary in /usr/local/bin. See the releases page for manual download options.
From PyPI (requires uv):
uv tool install -U openshellopenshell sandbox create -- claude # or opencode, codex, --from openclawA gateway cluster is created automatically on first use. To deploy on a remote host instead, use openshell gateway start --remote user@host.
The sandbox container includes the following tools by default:
| Category | Tools |
|---|---|
| Agent | claude, opencode, codex |
| Language | python (3.13), node (22) |
| Developer | gh, git, vim, nano |
| Networking | ping, dig, nslookup, nc, traceroute, netstat |
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.
| Agent | Source | Notes |
|---|---|---|
| Claude Code | Built-in | Works out of the box. Requires ANTHROPIC_API_KEY. |
| OpenCode | Built-in | Works out of the box. Requires OPENAI_API_KEY or OPENROUTER_API_KEY. |
| Codex | Built-in | Works out of the box. Requires OPENAI_API_KEY. |
| OpenClaw | Community | Launch with openshell sandbox create --from openclaw. |
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.
Under the hood, the gateway runs as a K3s 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. |
| 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. |
| Command | Description |
|---|---|
openshell sandbox create -- <agent> |
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 <name> |
Delete a sandbox. |
openshell provider create --type claude --from-existing |
Create a credential provider from env vars. |
openshell policy set <name> --policy file.yaml |
Apply or update a policy on a running sandbox. |
openshell policy get <name> |
Show the active policy. |
openshell inference set --provider <p> --model <m> |
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 for all commands, flags, and environment variables.
OpenShell includes a real-time terminal dashboard for monitoring gateways, sandboxes, and providers — inspired by k9s.
openshell term
The TUI gives you a live, keyboard-driven view of your cluster. Navigate with Tab to switch panels, j/k to move through lists, Enter to select, and : for command mode. Cluster health and sandbox status auto-refresh every two seconds.
Use --from to create sandboxes from the OpenShell Community catalog, a local directory, or a container image:
openshell sandbox create --from openclaw # community catalog
openshell sandbox create --from ./my-sandbox-dir # local Dockerfile
openshell sandbox create --from registry.io/img:v1 # container imageSee the community sandboxes catalog and the BYOC example for details.
- Full Documentation — overview, architecture, tutorials, and reference
- Quickstart — detailed install and first sandbox walkthrough
- GitHub Sandbox Tutorial — end-to-end scoped GitHub repo access
- Architecture — detailed architecture docs and design decisions
- Support Matrix — platforms, versions, and kernel requirements
See CONTRIBUTING.md for building from source and contributing to OpenShell.
This project is licensed under the Apache License 2.0.