Tutorial: Four steps to build an agent sandbox with strategy教程：四步给智能体建一个带策略的沙箱

Official support for Linux, Apple Silicon's macOS, and Windows + WSL 2 (labelled experimental). It also requires one of Docker, Podman, or host virtualization - because the sandbox itself depends on these for isolation.

Note for Windows users: This is not a native Windows tool and must be operated in WSL 2. Run wsl --version to confirm the WSL version, and then confirm whether the WSL integration of Docker Desktop is turned on.

The diagram is the system architecture diagram in the official warehouse: the user interface is connected to the gateway, and the gateway uses the prover for policy verification; the supervisor and the sandbox load are separated at runtime, and the only external channel of the load is the intermediated connection. If you read this picture, all the concepts behind it will go smoothly.

Official installation script: curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh. Once installed, it will be ready with both a command-line client and a local gateway - the gateway is the control plane for sandboxing, policies, and access, without which it won't be able to run.

If the network environment is inconvenient to use this script, the Linux x86_64 static client provided in this website can also be used directly: after decompression, a single file executable program openshell (about 9.96 MB) can be thrown into path. However, note that this package is only a CLI, and the gateway still needs to be deployed separately according to the official documentation.

Run the openshell -help make sure it works, then build the sandbox.

Execute openshell sandbox create --name demo. The default image is minimalist Ubuntu, which does not contain any agents - this is a deliberate design: build the empty room first, and then decide who can enter and what can be touched.

Once the sandbox is built, you can start by observing. The core ability of OpenShell is "policy", which governs three types of rules: which paths can be read and written by the file system, which hosts can be connected to the network, and what processes can do. These rules are not self-consciously obeyed by the agent, but are enforced at the kernel level - every file access, every system call, every external connection is checked at runtime.

Another key design is credential: the agent never sees the real key. OpenShell only injects credentials on requests to approved endpoints, so even if an agent is prompted to inject, it doesn't have a key to take with it.

Use OpenCode with a free OpenRouter model to run according to the “Run Your First Agent” section of the official documentation. The point of this step is not the agent itself, but to see what happens when it needs new permissions.

By default, the agent wants to access a new host or call a new API method, and the request stops and waits for approval. You can use the advisor to see the suggestions and the prover to see the results of the formal verification - it will clearly tell you what access rights will be newly granted for this policy change, such as "Can access a new host with credentials". These changes deserve a look before they're released.

This Validate and Reactivate process is the most valuable part of it. It changes permission management from “looking at logs in hindsight” to “knowing beforehand what will happen.”

If you want to save time, you can also let the agent learn this tool yourself: npx skills add NVIDIA/OpenShell will equip your programming agent with the skills to drive the OpenShell CLI, write sandbox strategies, troubleshoot gateways and inference routing, without additional clone source code.

Lastly, telemetry: OpenShell collects anonymous action categories and counts by default, without sandbox names, host names, file paths, prompts, credentials, or model names. To turn off, set open shell_telemetry_enabled = false on the gateway.