OpenShell runs inside a Docker container. Each sandbox is an isolated environment managed through the gateway. Four components work together to keep agents secure.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.
Components
The table below describes each component and its role in the system.| Component | Role |
|---|---|
| Gateway | Control-plane API that coordinates sandbox lifecycle and state, acts as the auth boundary, and brokers requests across the platform. |
| Sandbox | Isolated runtime that includes container supervision and policy-enforced egress routing. |
| Policy Engine | Policy definition and enforcement layer for filesystem, network, and process constraints. Defense in depth enforces policies from the application layer down to infrastructure and kernel layers. |
| Privacy Router | Privacy-aware LLM routing layer that keeps sensitive context on sandbox compute and routes based on cost and privacy policy. |
How a request flows
Every outbound connection from agent code passes through the same decision path.Agent opens a connection
The agent process opens an outbound connection — an API call, package install, git clone, or any other network request.
Proxy intercepts
The proxy inside the sandbox intercepts the connection and identifies which binary opened it.
inference.local special handling
If the target is
https://inference.local, the proxy handles it as managed inference before policy evaluation. OpenShell strips the sandbox-supplied credentials, injects the configured backend credentials, and forwards the request to the managed model endpoint.Policy engine evaluates
For every other destination, the proxy queries the policy engine with the destination, port, and calling binary.
Allow or deny
The policy engine returns one of two decisions:
- Allow — the destination and binary match a policy block. Traffic flows directly to the external service.
- Deny — no policy block matched. The connection is blocked and logged.
Deployment modes
OpenShell can run locally, on a remote host, or behind a cloud proxy. The architecture is identical in all cases — only the Docker container location and authentication mode change.| Mode | Description | Command |
|---|---|---|
| Local | The gateway runs inside Docker on your workstation. The CLI provisions it automatically on first use. | openshell gateway start |
| Remote | The gateway runs on a remote host via SSH. Only Docker is required on the remote machine. | openshell gateway start --remote user@host |
| Cloud | A gateway already running behind a reverse proxy (e.g. Cloudflare Access). Register and authenticate via browser. | openshell gateway add https://gateway.example.com |
openshell gateway select.
K3s cluster inside Docker
All components — Gateway, Sandbox, Policy Engine, and Privacy Router — run as a K3s Kubernetes cluster inside a single Docker container. No separate Kubernetes install is required. Theopenshell gateway commands take care of provisioning the container and the cluster.
The openshell-bootstrap crate handles cluster setup, image loading, and mTLS PKI generation on first start.
Because the cluster runs inside a single Docker container, OpenShell requires only Docker Desktop (or a Docker daemon) on the host machine — no Kubernetes knowledge needed to get started.
Next steps
Sandboxes
Learn how OpenShell enforces isolation across all protection layers.
Quickstart
Install the CLI and create your first sandbox.