> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/NVIDIA/OpenShell/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://k3s.io/) Kubernetes cluster inside a single Docker container. The `openshell gateway` commands handle all provisioning.
## Common use cases
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.
Route inference traffic to self-hosted or private backends. Keep sensitive context under your control while still using frontier models.
Treat policy YAML as version-controlled security controls. Review, diff, and audit exactly what each agent was allowed to do.
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](https://github.com/NVIDIA/OpenShell-Community) catalog.
## Next steps
Install the CLI and create your first sandboxed agent in two commands.
Understand the gateway, sandbox runtime, policy engine, and privacy router in depth.
Write and apply YAML policies to control filesystem, network, process, and inference access.
Browse pre-built sandbox images for common agent setups.