NVIDIA/OpenShell

OpenShell – a sandboxed runtime for autonomous AI agents

What it is – OpenShell (Apache‑2.0) is a lightweight, policy‑driven platform that lets you run LLM‑powered agents (Claude, OpenCode, Codex, GitHub Copilot, etc.) inside isolated containers. Every sandbox is protected by declarative YAML policies that control filesystem access, network egress, system calls and model‑API routing, so the agent can’t leak credentials or exfiltrate data.

Why it matters – As autonomous agents become more capable they also become a bigger security risk. OpenShell gives developers a way to give an agent the compute it needs (CPU, GPU, or even a MicroVM) while keeping the host and corporate resources safe.

---

Core concepts

Component	Role
Gateway	Control‑plane API that creates, destroys and monitors sandboxes; also the authentication boundary.
Sandbox	Container (Docker/Podman/MicroVM/K8s) that runs the agent and its toolchain.
Policy Engine	Enforces filesystem, process, network and inference policies defined in YAML.
Privacy Router	Intercepts LLM calls, strips user secrets, injects managed provider credentials, and forwards to the chosen model backend.

Quick start (Linux/macOS/WSL‑2)

# Install the binary (recommended)
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh

# Create a sandbox with an agent (e.g., Claude Code)
openshell sandbox create -- claude

# Open a shell inside the sandbox
openshell sandbox connect <sandbox‑name>

The sandbox ships with a minimal toolset (Python 3.14, Node 22, git, vim, networking utilities, etc.).

Controlling what the agent can do

1. Create sandbox – starts with no outbound network.
2. Apply a policy – a short YAML file describes allowed hosts, HTTP methods, file paths, etc.
3. Hot‑reload – openshell policy set … updates network or inference rules on a running sandbox without restarting it.

# examples/sandbox-policy-quickstart/policy.yaml
network:
  allow:
    - host: api.github.com
      methods: [GET]
process:
  deny: ["sudo", "chmod"]
filesystem:
  readOnly: ["/home/user/.config"]

The README shows a live demo where a curl to GitHub is blocked until the policy is applied.

Provider management (credentials)

Providers are named bundles of API keys or service‑account tokens. OpenShell discovers keys for supported agents from your environment and injects them as runtime‑only environment variables – they never touch the sandbox’s filesystem.

openshell provider create --type anthropic --name claude_key   # picks up ANTHROPIC_API_KEY
openshell sandbox create --provider claude_key -- claude

GPU support (experimental)

Add --gpu when creating a sandbox to pass the host GPU through (requires NVIDIA driver, Container Toolkit and a sandbox image that includes the needed CUDA libraries).

openshell sandbox create --gpu -- claude

Extensibility

• Custom sandboxes – openshell sandbox create --from ./my‑sandbox-dir or from any OCI image.
• Helm chart – experimental Kubernetes deployment (helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart).
• Bring‑Your‑Own‑Container – see the examples/bring-your-own-container folder for building GPU‑enabled images.

User‑facing tools

Command	What it does
openshell sandbox create …	Spin up a new sandbox with a chosen agent.
openshell sandbox connect <name>	SSH‑like terminal into the sandbox.
openshell policy set <name> --policy file.yaml	Apply or update a policy on a running sandbox.
openshell provider create …	Register credentials for later injection.
openshell term	TUI (k9s‑style) dashboard for monitoring gateways, sandboxes and providers.

When you’d use OpenShell

• Secure autonomous agents – run code‑generating or decision‑making bots without risking credential leakage.
• RAG pipelines – let an LLM fetch data from internal services while the policy blocks any unintended outbound calls.
• GPU‑accelerated inference – fine‑tune or run local models inside a sandbox, keeping the host environment clean.
• Enterprise compliance – declarative policies give auditors a clear, version‑controlled record of what each agent is allowed to do.

Getting help & contributing

• Discussions – GitHub Discussions for usage questions.
• Issues – bug reports and feature requests (must include a user story and acceptance criteria).
• Agent‑first workflow – the repo ships with .agents/skills/ that let an AI assistant help you diagnose problems, generate policies, or scaffold new features.
• Telemetry – optional anonymous usage stats; can be disabled at runtime or compiled out.

---

Bottom line – OpenShell is a genuine, open‑source platform that lets developers safely run autonomous LLM agents in isolated containers, with fine‑grained, hot‑reloadable policies governing file, process, network and inference behavior. It supports local GPU workloads, Kubernetes deployment, and a rich CLI/TUI for day‑to‑day operations.