Introduction

OpenShell is the safe, private runtime for autonomous AI agents — sandboxed execution with declarative YAML policies that protect your data, credentials, and infrastructure.

What is OpenShell?

NVIDIA OpenShell is an open-source runtime that executes autonomous AI agents in sandboxed environments with kernel-level isolation. It combines container-based sandbox runtimes with a declarative YAML policy system so you can run agents without giving them unrestricted access to your files, credentials, and networks.

Every sandbox is isolated in its own container with policy-enforced egress routing. Outbound connections pass through a policy engine that either allows, denies, or reroutes the request — no agent action bypasses it.

OpenShell is alpha software in single-player mode: one developer, one environment, one gateway. Multi-tenant enterprise deployments are on the roadmap. Expect rough edges.

The problem it solves

AI agents are most useful when they can read files, install packages, call APIs, and use credentials. That same access is a material risk.

Threat	Without controls	With OpenShell
Data exfiltration	Agent uploads source code or internal files to unauthorized endpoints.	Network policies allow only approved destinations; all other outbound traffic is denied.
Credential theft	Agent reads local secrets such as SSH keys or cloud credentials.	Filesystem restrictions (Landlock) confine access to declared paths only.
Unauthorized API usage	Agent sends prompts or data to unapproved model providers.	Privacy routing and network policies control where inference traffic can go.
Privilege escalation	Agent attempts sudo, setuid paths, or dangerous syscalls.	Unprivileged process identity and seccomp restrictions block escalation paths.

OpenShell is designed for this tradeoff: preserve agent capability while enforcing explicit controls over what the agent can access.

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.
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 time. Dynamic sections (network, inference) can be hot-reloaded on a running sandbox without restarting anything.

How it works

A lightweight gateway coordinates sandbox lifecycle and acts as the auth boundary. Every outbound connection from a sandbox is intercepted by the policy engine, which does one of three things:

• Allows — the destination and HTTP method 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 and sandboxes run as a K3s Kubernetes cluster inside a single Docker container. The openshell gateway commands handle all provisioning.

Common use cases

Secure coding agents

Run Claude Code, OpenCode, Codex, or GitHub Copilot CLI with constrained file and network access. Credentials are injected at runtime — never written to the sandbox filesystem.

Private enterprise development

Route inference traffic to self-hosted or private backends. Keep sensitive context under your control while still using frontier models.

Compliance and audit

Treat policy YAML as version-controlled security controls. Review, diff, and audit exactly what each agent was allowed to do.

Reusable environments

Use community sandbox images for common agent setups, or bring your own containerized runtime with a custom Dockerfile.

Supported agents

OpenShell ships with built-in support for the following agents in the base sandbox image:

Agent	Credential used
Claude Code	ANTHROPIC_API_KEY
OpenCode	OPENAI_API_KEY or OPENROUTER_API_KEY
Codex	OPENAI_API_KEY
GitHub Copilot CLI	GITHUB_TOKEN or COPILOT_GITHUB_TOKEN

Additional agents (OpenClaw, Ollama, and others) are available through the OpenShell Community catalog.

Next steps

Quickstart

Install the CLI and create your first sandboxed agent in two commands.

Architecture

Understand the gateway, sandbox runtime, policy engine, and privacy router in depth.

Sandbox policies

Write and apply YAML policies to control filesystem, network, process, and inference access.

Community sandboxes

Browse pre-built sandbox images for common agent setups.