OpenShell Setup: Sandbox AI Agents on Your Own Machine

OpenShell is NVIDIA's free, Apache-2.0 runtime that runs an AI agent inside a sandbox where a policy you write decides every file it can open, every system call it can make and every host it can reach. It picked up 978 GitHub stars today, on top of about 10,400 total, two days after NVIDIA made it the software half of its new Open Agent Safety Platform. On Linux or an Apple Silicon Mac, a locked-down sandbox takes one install script and one command, and a real coding agent takes about fifteen minutes more.

• OpenShell is a runtime, not an agent: you bring the agent (OpenCode, Claude Code, Pi, your own script) in a container image, and OpenShell confines it with Landlock, seccomp and a policy-checking network proxy.
• Networking is default-deny. A blocked request becomes a drafted rule you approve or reject, and approved rules hot-reload into the running sandbox without a restart.
• Agents never see real API keys. OpenShell stores them in a credential store and injects them only into requests bound for the endpoints a provider profile allows.
• Supported hosts are Linux and Apple Silicon macOS with Docker, Podman or a microVM. Windows works only through WSL 2 and is marked experimental.

The exact steps, start to finish

1. Check your prerequisites. You need Linux (kernel 6.2 or newer for the Landlock ABI OpenShell requires), macOS on Apple Silicon, or Windows with WSL 2, plus Docker 28.0 or newer (Docker Desktop on Mac and Windows). Run these in your Linux, macOS or WSL terminal:

   $ uname -r
   $ docker --version
   $ curl --version

2. Install the CLI, policy prover and local gateway. The script picks a Debian or RPM package on Linux (a Homebrew formula on macOS) and starts the gateway as a service.

   $ curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh

3. Confirm the CLI can reach the gateway.

   $ openshell status

4. Create your first sandbox. The default image is a minimal Ubuntu 24.04 with no agent inside, so this is a safe place to poke around. You land in a shell inside the sandbox; type exit to leave.

   $ openshell sandbox create --name demo

5. Get a free OpenRouter API key. The official first-agent walkthrough runs OpenCode against a free model on OpenRouter. Create an account there and generate an API key. You do not need credits for the free model.
6. Import the OpenRouter provider profile and store your key. The profile only lets /usr/local/bin/opencode talk to openrouter.ai. Replace your-key with the key from step 5.

   $ openshell profile import \
     --url https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/openrouter.yaml
   
   $ OPENROUTER_API_KEY=your-key \
     openshell provider create \
       --name openrouter \
       --type openrouter \
       --from-existing

7. Launch a real agent inside the sandbox. This pulls the OpenCode image, attaches the provider and starts OpenCode on NVIDIA's free Nemotron model. Give it a prompt and watch it work.

   $ openshell sandbox create \
     --name my-agent \
     --from ghcr.io/anomalyco/opencode:latest \
     --provider openrouter \
     -- opencode -m openrouter/nvidia/nemotron-3.5-lightning:free

8. Approve access as the agent asks for it. From a second host terminal, list the rules OpenShell drafted from blocked requests, then approve the ones you actually want.

   $ openshell rule get my-agent --status pending
   $ openshell rule approve my-agent --chunk-id <chunk-id>

What is OpenShell and why is it trending?

Coding agents are most useful when they can read your files, install packages, call APIs and use your credentials. They are most dangerous for exactly the same reasons. Most agents handle this with their own permission prompts, which run inside the same process you are trying to constrain. OpenShell moves the boundary outside the agent. Each agent runs in an isolated sandbox, Linux kernel controls restrict which files it can touch and which system calls it can make, and every network connection goes through a supervisor that checks it against a declarative policy before it leaves.

RelatedStrix Setup: Run an AI Penetration Tester on Your Code

The second idea is the policy workflow. When the agent hits something the policy does not allow, OpenShell denies it, logs it with the binary and destination, and its policy advisor drafts a narrow rule. A formal-verification step called the prover checks what that rule would newly allow, such as sending credentials to a new host, before you review it. You approve with one command and the rule reloads into the live sandbox.

The spike this week has a clear cause. On 28 September NVIDIA announced the Open Agent Safety Platform, pairing OpenShell with a hardware watchdog design called Sentry that runs on BlueField-4 DPUs, and named more than 100 backing organizations. We covered that launch in our news story on the platform. The same day the project shipped v0.1.2, its third release on the new 0.1 line, which the maintainers describe as a stable weekly release cadence.

How do you install OpenShell on Linux?

Run the one-line script from the checklist. On Debian and Ubuntu it installs a Debian package, on Fedora and RHEL an RPM, and it needs glibc 2.28 or newer. The gateway then runs as a systemd user service on https://127.0.0.1:17670. These are the commands you will use to check on it and read its logs:

$ systemctl --user status openshell-gateway
$ systemctl --user restart openshell-gateway
$ journalctl --user -u openshell-gateway -f

A user service stops when you log out. To keep the gateway running on a server, enable linger:

$ sudo loginctl enable-linger $USER

If you prefer Snap, set OPENSHELL_INSTALL_METHOD=snap before running the script. The snap needs Docker Engine from your distribution or Docker's own repository; the Docker snap is not compatible.

How do you install it on a Mac or on Windows?

On Apple Silicon the same script installs a Homebrew formula and runs the gateway as a Homebrew service at https://localhost:17670. Homebrew is required, and Docker Desktop provides the Linux kernel the sandbox needs.

$ brew services list
$ brew services restart openshell

Windows has no native build. The support matrix lists Windows with WSL 2 and Docker Desktop as experimental, so open your WSL Ubuntu shell and run the Linux script there. For this guide we downloaded the v0.1.2 static CLI (about 10 MB) into WSL 2 on a Windows 10 laptop. It ran immediately, reported openshell 0.1.2, and openshell status answered "No gateway configured", which is exactly what you see before the gateway service is installed and registered. The full Linux package is about 74 MB.

What does a policy actually look like?

OpenShell's own five-minute policy tutorial shows the model well. A fresh sandbox cannot reach anything, so curl https://api.github.com/zen fails with a 403 from the proxy. From the host you then add one rule that lets curl read the GitHub API and nothing else:

RelatedHindsight Setup: Give Your AI Agent Memory That Learns

$ openshell policy update demo \
  --rule-name github_api \
  --binary /usr/bin/curl \
  --add-endpoint api.github.com:443:read-only:rest:enforce \
  --wait

The same GET now works, while a POST to create an issue is refused because the proxy inspects the HTTP method, not just the hostname. That per-binary, per-method control is the real difference from a container with networking switched on or off. You can review every denial with openshell logs demo --since 5m --source sandbox.

How does OpenShell compare with other ways to contain an agent?

What are the gotchas before you rely on it?

The kernel requirements are strict and fail closed. The sandbox needs Landlock ABI 3 (Linux 6.2 or newer) and specific seccomp features, and it actively probes for them before it starts a workload. An older or locked-down kernel does not get weaker protection, it gets a sandbox that refuses to launch. RHEL 9 and other pre-5.19 kernels run in a reduced "legacy read-only" mode where a few socket calls return errors, which can break server-style workloads.

The default image is empty on purpose. openshell sandbox create gives you a minimal Ubuntu with no agent, so the real work is building or choosing an image that contains your agent and its tools, then writing a policy for what it needs. Provider profiles also name exact binary paths, so a profile written for /usr/local/bin/opencode does nothing for an agent installed elsewhere. Copy and edit the profile rather than importing it unchanged, as the example file itself advises.

Two smaller notes. The gateway sends anonymous operational telemetry by default; set OPENSHELL_TELEMETRY_ENABLED=false on the gateway to turn it off. And the project moves fast: v0.1.0 landed on 25 September with its own upgrade guide, followed by two patch releases in three days, so pin a version with OPENSHELL_VERSION in anything you automate.

Our take

OpenShell gets the design right. Putting the policy check outside the agent, keeping keys out of the sandbox, and turning every denial into a reviewable rule is a better model than trusting an agent's own "may I?" prompts. The CLI is clean and well documented, and the first-network-policy tutorial makes the idea click in minutes. The honest caveat is setup friction: it wants Linux or an Apple Silicon Mac, a recent kernel, Docker and an agent image, and Windows users are on an experimental path. If you already run coding agents with broad access on a Linux box, install it this week and start with the OpenRouter example. If you are on Windows, try it in WSL 2, but do not bet production on it yet.

Original analysis by GenZTech, based on the OpenShell repository and documentation and our own test of the v0.1.2 CLI in WSL 2.