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. It ships public agent skills for using and operating OpenShell, plus separate repository-aware workflows for contributors and maintainers.
Quickstart
Prerequisites
A supported host — Linux, macOS (Apple Silicon), or Windows with WSL 2 (experimental).
A local runtime — Docker, Podman, or host virtualization enabled for MicroVM-backed sandboxes.
Install
Binary (recommended):
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
The installer installs the latest stable release by default. To install a specific version, set OPENSHELL_VERSION. A dev release is also available that tracks the latest commit on main.
The openshell package on PyPI provides the Python SDK only. It does not install the openshell CLI. Add the SDK to a Python project with uv:
uv add openshell
Helm chart:
Experimental — the Kubernetes deployment path is under active development. Expect rough edges and breaking changes.
Deploy the OpenShell gateway into a Kubernetes cluster from the OCI chart published to GHCR:
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.
# 1. Create a sandbox (starts with minimal outbound access)
openshell sandbox create
# 2. Inside the sandbox — blocked
sandbox$ curl -sS https://api.github.com/zen
curl: (56) Received HTTP code 403 from proxy after CONNECT
# 3. Back on the host — apply a read-only GitHub API policy
sandbox$ exit
openshell policy set demo --policy examples/sandbox-policy-quickstart/policy.yaml --wait
# 4. Reconnect — GET allowed, POST blocked by L7
openshell sandbox connect demo
sandbox$ curl -sS https://api.github.com/zen
Anything added dilutes everything else.
sandbox$ curl -sS -X POST https://api.github.com/repos/octocat/hello-world/issues -d '{"title":"oops"}'
{"error":"policy_denied","detail":"POST /repos/octocat/hello-world/issues not permitted by policy"}
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.
Binds credentials to endpoints — injects provider credentials only after policy admits a request to a profile-authorized endpoint.
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.
Provider Access
Profile-defined endpoints, binary policy, and endpoint-bound credential injection for model APIs and other services.
OpenShell runs a gateway control plane that manages sandbox lifecycle through a configured compute driver. Supported compute platforms include Docker, Podman, MicroVM, and Kubernetes.
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.
Providers
Grants endpoint-bound credentials and network access.
Hot-reloadable at runtime.
Policies are declarative YAML files. Static sections (filesystem, process) are locked at creation; network policy and provider attachments can be updated on a running sandbox.
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, Copilot) 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.
Inference access uses the same provider workflow. Attach an inference-capable provider to a sandbox, call the provider's native endpoint, and select the model in the client. Provider profiles contribute the endpoint policy and bind credential placeholders to the authorized destination.
GPU Support (Experimental)
Experimental — GPU passthrough works on supported hosts but is under active development. Expect rough edges and breaking changes.
OpenShell can pass host GPUs into sandboxes for local inference, fine-tuning, or any GPU workload. Add --gpu when creating a sandbox:
openshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude
Docker-backed GPU sandboxes auto-select CDI when available and otherwise fall back to Docker's NVIDIA GPU request path (--gpus all).
Requirements: NVIDIA drivers and the NVIDIA Container Toolkit 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 for building a custom sandbox image with GPU support.
See the full documentation for command guides, tutorials, and reference material.
Terminal UI
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 gateway and sandboxes. Navigate with Tab to switch panels, j/k to move through lists, Enter to select, and : for command mode. Gateway health and sandbox status auto-refresh every two seconds.
Community Sandboxes and BYOC
Use --from to create sandboxes from the OpenShell Community catalog or a container image:
OpenShell provides four portable skills for users and operators: CLI workflows (openshell-cli), gateway troubleshooting (debug-openshell-cluster), inference troubleshooting (debug-inference), and policy generation (generate-sandbox-policy). Install them with the Agent Skills CLI:
npx skills add NVIDIA/OpenShell
These public, installable skills live in skills/ and use the installed CLI help and published documentation as their sources of truth. They do not require an OpenShell source checkout.
Built With Agents
OpenShell is developed using the same agent-driven workflows it enables. Contributor and maintainer skills live separately in .agents/skills/; they automate work on the OpenShell repository and are not included when users install the public skills:
Spike and build: Investigate a problem with create-spike; a human accepts it with state:accepted or roadmap placement, or declines it. Accepted work can remain human-owned or enter the optional, human-gated agent:* planning and implementation workflow.
Triage and route: Community issues are assessed with triage-issue. Agents establish technical validity and impact; humans decide whether the project should act and where the work sits on the roadmap.
Security review:review-security-issue produces a severity assessment and remediation plan. fix-security-issue implements it.
Repository maintenance:sync-agent-infra, update-docs-from-commits, and other internal workflows keep code, documentation, and agent infrastructure consistent.
Agent implementation is human-directed: a user may request a phase directly, or maintainers may use the optional agent:* workflow to queue and approve planning and implementation. See AGENTS.md for the full workflow chain documentation.
RFC Board — RFC proposals tracked on the OpenShell Roadmap with the rfc label
Support Matrix — platforms, versions, and kernel requirements
Brev Launchable — try OpenShell on cloud compute without local setup
Agent Instructions — system prompt and workflow documentation for agent contributors
Contributing
OpenShell is built agent-first. Issues should include a user story, problem statement, impact, and acceptance criteria. The impact should explain the consequences of the current behavior and why existing workarounds are insufficient. Feature requests also require a workflow-level proposed design and alternatives; bug reports add reproduction steps, environment details, and relevant logs. Once work is authorized through the project workflow or a direct request, contributors should use the skills in .agents/skills/ to investigate the current code and behavior, implement the change, and verify it. If an issue contains earlier diagnostics, verify them rather than relying on them. See CONTRIBUTING.md for the full agent skills table, contribution workflow, and development setup.
Telemetry
OpenShell collects anonymous telemetry to help improve the project for developers. This data is not used to track individual user behavior. It helps us understand aggregate usage of sandbox, provider, and policy workflows so we can prioritize product improvements and share usage trends with the community.
Disable telemetry at runtime by setting OPENSHELL_TELEMETRY_ENABLED=false on the gateway deployment. For Helm installs, set server.telemetryEnabled=false. OpenShell propagates this deployment setting into sandbox supervisor environments so sandbox-side telemetry collection is disabled as well.
You can also compile telemetry out entirely. Telemetry support is a default-on telemetry Cargo feature, and each crate that carries it also defines a defaults-without-telemetry alias covering every other default feature. Build telemetry-free artifacts with --no-default-features --features defaults-without-telemetry:
The resulting binaries contain no telemetry endpoint, no telemetry HTTP client, and no emission code. With telemetry compiled out, the gateway emits nothing and reports telemetry disabled to th
What is this?OpenShell is an open-source runtime for running autonomous AI agents inside isolated sandboxes. Declarative YAML policies protect your files, credentials, and infrastructure from unauthorized access and data exfiltration.
Is this something I install on my own machine, or a hosted service I sign into?It is a local CLI ('openshell') plus a gateway control plane that manages sandbox lifecycle through compute drivers: Docker, Podman, MicroVM, and Kubernetes. Each sandbox is an isolated container with policy-enforced egress routing.
How do I install it and start my first sandbox?Run the installer — it installs the latest stable release by default (a dev release tracks main). Then create your first sandbox with 'openshell sandbox create', which can launch an agent right away.
Do I need Docker or Podman installed beforehand?Yes — you need a local runtime: Docker, Podman, or host virtualization enabled for MicroVM-backed sandboxes. Note that the 'openshell' package on PyPI ships only the Python SDK, not the CLI.
Is the Kubernetes deployment path stable enough for production?Not yet — deploying the gateway via the Helm chart is experimental, under active development, and expects rough edges and breaking changes.
Does it work on Windows, or is it Linux and Mac only?Supported hosts are Linux, macOS (Apple Silicon), and Windows with WSL 2 — the Windows path is marked experimental. Sandboxes themselves run on Docker, Podman, MicroVM, or Kubernetes.
How does it keep my API keys away from the agent?Keys are managed as providers — named credential bundles injected into sandboxes only as runtime environment variables, never written to the sandbox filesystem. The CLI auto-discovers credentials for Claude, Codex, OpenCode, and Copilot from your shell.
Which AI agents can run inside a sandbox?Claude Code, OpenCode, Codex, and GitHub Copilot CLI work out of the box with auto-discovered credentials. OpenClaw and Hermes Agent run via the NemoClaw blueprint, and community sandboxes like Ollama or Pi launch with 'openshell sandbox create --from ollama'.
Can a sandbox use my GPU for local inference?Yes, but it is experimental: add --gpu when creating a sandbox. The host needs NVIDIA drivers and the NVIDIA Container Toolkit, and since the default base image lacks GPU libraries, most workloads need a custom BYOC sandbox image.
Is there a dashboard to watch my sandboxes live?Yes — 'openshell term' opens a real-time terminal UI inspired by k9s with live views of gateways, sandboxes, and providers. Tab switches panels, j/k moves through lists, and health and status auto-refresh every two seconds.
What tools come preinstalled in a sandbox?Agent CLIs (claude, opencode, codex, copilot), Python 3.14 and Node 22, developer tools like gh, git, vim, and nano, plus networking utilities. You can also start from a community catalog image or your own via --from.
OpenShell is an open-source runtime for running autonomous AI agents inside isolated sandboxes. Declarative YAML policies protect your files, credentials, and infrastructure from unauthorized access and data exfiltration.