What Is NVIDIA OpenShell? Running an AI Agent in a Sandbox: Setup, Policy Examples and License

You write what the agent may access in a YAML policy file; OpenShell runs the agent in an isolated sandbox and allows only that much. File and system call access is restricted in the Linux kernel, every network connection passes a policy check before it leaves, and forbidden requests are denied and logged; the agent never sees the real API key, which is added only to requests going to an approved address. It is NVIDIA's open-source (Apache 2.0) runtime; Linux and Apple Silicon Macs are supported, Windows (WSL 2) is experimental. Free; used from the command line.

What it does: Runs an AI agent in a policy-restricted sandbox
Free: Yes, Apache 2.0; model and server costs are yours
No-code: No; command line and YAML
Platforms: Linux, Apple Silicon macOS; Windows experimental
Requires: Docker 28+, Podman 5 or virtualization
Version: v0.1.6 (October 27, 2026), stable release
Turkish: Interface and docs in English

What is NVIDIA OpenShell and what problem does it solve?

An AI agent (an assistant that runs commands on its own, such as Claude Code or OpenCode) is only useful when it can read files and install packages, call APIs and use keys. The problem: the moment you grant those permissions, the agent can also reach all your files, the whole network and all your keys. OpenShell separates the two: the agent runs, but touches only what you allow. You write what it may touch in a policy file; OpenShell denies and logs everything not in the policy.

Run the agent in a sandboxWhat you get: Policy-restricted agent sessionNeeds a separate setup Restrict network access with a policyWhat you get: Allowed requests pass, forbidden requests return 403Needs a separate setup See the log of blocked accessWhat you get: DENIED linesNeeds a separate setup

Can I use it without code?

No. OpenShell is installed and managed from the command line; the policy is a YAML file. A version with a graphical interface is not in the official sources. If you want your agent to use OpenShell, the README offers ready-made skills for coding agents: npx skills add NVIDIA/OpenShell (teaches your agent to drive the CLI, write policies and fix gateway problems).

Who it is for: software teams that run agents on their own servers or computers for long periods with little supervision; security leads who want to limit how far an agent can reach into company data and keys; platform teams that want to apply the same policy to many agents. It is not a necessary tool for someone using a single chat assistant.

How does OpenShell work? Gateway, supervisor and sandbox

You write the policyFile, process and network rules in a single YAML file.

The agent runs in the sandboxFile access is restricted in the kernel with Landlock, system calls with seccomp.

Every connection is checkedThe supervisor compares the request with the policy; if allowed it opens it, otherwise it denies and logs it.

The agent never sees the real key; the key is added only to requests going to an approved address.

Gateway (control plane)

Authenticates you, creates and deletes sandboxes, distributes policy and settings, and connects providers. In a local install it runs on port 17670 as a systemd user service on Linux and a Homebrew service on macOS.

Supervisor

Sits on the trusted side of the boundary: compares requests with the policy, hands credentials only to allowed destinations, resolves DNS and opens allowed connections.

Sandbox

Sits inside the same boundary as the agent and makes no decisions: it reports what the agent wants to do. The agent's only way out is the channel to the supervisor.

Policy prover

Checks network rules proposed by the agent or written by you using formal verification: it flags risky access such as reaching a new address with a key, a new HTTP method or a cloud metadata address; if there is a finding, auto-approval stops and the change waits for human approval.

Provider: links a service name (e.g. OpenRouter, GitHub, Claude Code) to a stored credential. In the docs example, OPENROUTER_API_KEY is kept in the credential store and sent only to openrouter.ai; the agent's environment shows only a placeholder.

Architecture summary: docs.nvidia.com/openshell → Architecture. The sandbox runs on Docker, Podman, Kubernetes or a MicroVM; the channel between the supervisor and the sandbox is a single mutually authenticated HTTP/2 connection.

How to install OpenShell? Linux, Mac, Windows and Kubernetes

Install (pinned version: v0.1.6)› curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | OPENSHELL_VERSION=v0.1.6 sh

Check that the gateway is reachable› openshell status

Open your first sandbox› openshell sandbox create --name demo

The script installs the CLI, the policy prover and the local gateway. On Linux it installs a .deb package for Debian/Ubuntu or an RPM package for Fedora/RHEL and starts the gateway as a systemd user service; on macOS it installs via Homebrew. The docs describe version pinning with the OPENSHELL_VERSION variable; if the variable is empty, the latest stable release is installed.

This command runs a script downloaded from the internet and installs packages with administrator privileges; open the script in your browser and read it before running it.

WSL 2 + Docker Desktop: "Experimental" in the support matrix. You install Linux OpenShell inside WSL 2 with the command from the Linux tab.

Native Windows (Microsoft MXC): built from the windows branch, in development and not production-ready. The install script and release channels do not ship a native Windows binary.

Gateway with Helm (pin the version)

› helm upgrade --install openshell \
  oci://ghcr.io/nvidia/openshell/helm-chart \
  --version 0.1.6

Helm chart versions are written without the leading v of the release tag (per the docs). The cluster's network plugin (CNI) must enforce NetworkPolicy; Kubernetes 1.29+ and Helm 3 are required.

What you need	Requirement in the docs
Operating system	Linux (Debian/Ubuntu, amd64 and arm64) or macOS Apple Silicon; Windows WSL 2 experimental
Runtime	Docker Desktop/Engine 28.0+, or Podman 5.x (cgroups v2), or for MicroVM, KVM (Linux) / Hypervisor.framework (macOS)
Linux kernel	Landlock ABI 3 or higher (introduced in Linux 6.2) must be enabled; seccomp is required. Without them the sandbox will not start
Linux packages	glibc 2.28+ (e.g. Ubuntu 20.04+, RHEL 8+)
Agent	The default image (minimal Ubuntu) contains no agent; you choose an image that includes the agent (`--from`)

The openshell package on PyPI (uv add openshell, PyPI classifier "Alpha") is the Python SDK: it is for connecting your own application to an OpenShell gateway and does not install the CLI. There are also TypeScript, Go and Rust SDKs.

How to use OpenShell? The commands you type and what you get back

The two examples below come from NVIDIA's own tutorials; the outputs are described from the sample lines in the docs. Most commands run in a second terminal on the host machine; the shell inside the sandbox stays open.

Example 1: Give the agent read-only access to the GitHub API

1. Open a sandbox with no network rules (with curl instead of an agent)

› openshell sandbox create \
  --name demo \
  --from registry.example.com/team/agent-tools:1.0 \
  --no-auto-providers

2. Try to reach the outside from inside the sandbox› curl -s https://api.github.com/zen

What you get: the request is denied: curl: (56) Received HTTP code 403 from proxy after CONNECT. By default, no connection leaves the sandbox.

3. Check the denial log on the host› openshell logs demo --since 5m --source sandbox

What you get: a line showing the destination, the program that made the request and the reason: DENIED /usr/bin/curl(64) -> api.github.com:443 … [reason:network connections not allowed by policy].

4. Give curl read-only access to the GitHub API

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

What you get: the rule loads without restarting the sandbox. The same GET request now returns a response; a POST to the same address (e.g. opening an issue) gets 403 and "error":"policy_denied", and an HTTP:POST … DENIED line with the method and path appears in the log. So the agent can read code from GitHub but cannot open issues or push commits.

Example 2: Run a real agent and grant access as needed

1. Import the provider profile and save the key (OPENROUTER_API_KEY must be set in the environment)

› openshell profile import \
  --url https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/openrouter.yaml

openshell provider create \
  --name openrouter \
  --type openrouter \
  --from-existing

2. Start the agent (OpenCode) in the sandbox

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

3. When the agent hits a disallowed address, review the proposed rules› openshell rule get my-agent --status pending

4. Approve a proposal that looks right, or reject it with a reason

› openshell rule approve my-agent --chunk-id <chunk-id>

openshell rule reject my-agent \
  --chunk-id <chunk-id> \
  --reason "Not needed for this task."

What you get: when the agent goes to an address the policy does not allow, the request is denied and OpenShell drafts a narrow rule for that address, port and program; the draft first goes through the policy prover, then lands in your approval queue. A rule you approve loads without stopping the agent, and the agent retries the request. openshell rule approve-all skips proposals flagged for security and reports how many it skipped.

What you want to do	Command (docs)
Open a sandbox	`openshell sandbox create --name <name>` (`--from` for the image, agent command after `--`)
Watch the logs	`openshell logs <name> --since 5m --source sandbox`
View the policy	`openshell policy get <name> --base` (base policy, excluding rules added by providers)
Add a network rule	`openshell policy update <name> --rule-name … --binary … --add-endpoint host:port:access:protocol:mode --wait`
Manage proposals	`openshell rule get … --status pending`, `rule approve`, `rule reject`, `rule approve-all`
Connect to an existing sandbox	`openshell sandbox connect <name>`
Delete a sandbox	`openshell sandbox delete <name>` (stops processes, clears added credentials)

When setting up a policy, you can start with enforcement: audit: rule violations are not blocked but are logged. Once you have reviewed the logs and the rules are right, you switch to enforce (recommended in the docs).

What does the OpenShell policy file control?

A policy is a YAML file that starts with version: 1. OpenShell denies everything the policy does not allow. The rule added by the command in Example 1 looks like this in YAML (as in the docs):

network_policies section (docs example)

› network_policies:
  github_api:
    endpoints:
      - host: api.github.com
        port: 443
        protocol: rest
        enforcement: enforce
        access: read-only
    binaries:
      - path: /usr/bin/curl

Section	What it controls	When it applies
`filesystem_policy`	Paths that processes in the sandbox can read, or read and write (Landlock in the kernel)	When the sandbox starts
`landlock`	Whether the sandbox still starts if file rules cannot be applied	When the sandbox starts
`process`	Which user and group processes run as	When the sandbox is created
`network_policies`	Which addresses each program can reach and which requests it can send	Can change at runtime
`network_middlewares`	Extra inspection, transformation or blocking of allowed traffic	Can change at runtime

If you give no policy: OpenShell uses the restrictive default policy (when there is no administrator global policy, registered policy or policy in the image). By default the working folder is read-write; system paths such as /bin, /usr, /lib, /etc are read-only; /tmp is writable; there is no outbound network access. Providers you connect may add network rules, so check the effective policy separately.

Administrator global policy: the gateway administrator can apply a single policy to all sandboxes; it replaces each sandbox's own policy and, while active, blocks policy changes and proposal approvals.

Is OpenShell free? License and commercial use

Allowed

Commercial use, modification, copying and distribution (Apache 2.0)
Patent rights from the contributor granting the license (Apache 2.0 section 3)
Unlimited sandboxes within your organization and on your own servers (the license sets no quota)

Not allowed

Removing copyright and license notices (they must be kept when distributing)
Using the NVIDIA name and trademarks without permission (Apache 2.0 section 6)
Expecting a warranty: the README states the software is provided "as is" and that external content it pulls is subject to its own terms

Cost: the software itself is free; no account or registration is needed. You pay only the model provider the agent uses (e.g. OpenRouter, Anthropic) and for the server; NVIDIA's sample agent runs on a free model on OpenRouter. The README also links a cloud trial on NVIDIA Brev; the price of that cloud trial is not given in the README, so check the price on the Brev page before starting it.

The license summary is based on the Apache License 2.0 text and is not legal advice. The agent and images you run in the sandbox carry their own licenses.

What data does OpenShell collect? Telemetry and keys

Anonymous telemetry (on by default)

Only operation categories and counts are sent (such as sandbox startup results and policy decision counts). Sandbox names, host names, file paths, prompts, credentials, provider or model names and user content are not collected. Aggregate trends are published on GitHub every two weeks.

Turning it off

On the gateway, OPENSHELL_TELEMETRY_ENABLED=false; in a Helm install, server.telemetryEnabled=false. The setting also applies to sandboxes. You can also remove telemetry from the build entirely (the docs include Cargo commands).

Your keys

Provider keys are kept in the gateway's credential store; the agent sees a placeholder. When a sandbox is deleted, the credentials added to it are cleared.

The sandbox does not block requests that go with a key to an address you allowed in the policy: approving a rule means giving the agent that permission at that address. Read the address, port, program and method before approving proposals.

Where does OpenShell run, and where doesn't it? Limits

Linux (Debian/Ubuntu, amd64 and arm64)Yes	"Supported" in the support matrix.
macOS Apple SiliconYes	"Supported" with Docker Desktop; the gateway runs as a Homebrew service.
Windows (WSL 2 + Docker Desktop)Experimental	"Experimental" in the support matrix.
Native Windows (MXC)Partly	Built from the `windows` branch; in development, not production-ready.
Intel-based MacUnclear	No row in the support matrix; the docs do not give this detail.
Release cadenceYes	Version 0.1.x: stable releases usually ship weekly; security fixes go to the last two minor release lines; interfaces marked "Experimental" may change in a patch release.

What happens	What to do
The sandbox never starts	If Landlock is disabled in the kernel or the runtime blocks required seccomp operations, startup deliberately stops. Check for Linux 6.2+ and that Landlock is enabled.
`curl: (56) Received HTTP code 403 from proxy after CONNECT`	Not an error, it is the default deny: add a rule to `network_policies` for that program and address.
I exited the sandbox shell and can't reconnect	When the main process stops, the default restart policy leaves the sandbox unreachable; delete it and open a new one. If you want it deleted automatically on exit, add `--no-keep` when creating it.
Policy events don't show in the log	Policy events are written at INFO level; don't filter with `--level warn`.
The policy in the image is broken	OpenShell does not fall back to the default and the agent does not start; fix the image policy.

Frequently asked questions

What is NVIDIA OpenShell?

NVIDIA's open-source runtime for AI agents. It runs the agent in an isolated sandbox and limits file, network and key access with a YAML policy you write; everything not in the policy is denied and logged.

How do I install OpenShell?

On Linux or an Apple Silicon Mac, with the install script: curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | OPENSHELL_VERSION=v0.1.6 sh, then openshell status. Docker 28+, Podman 5 or hardware virtualization is required.

Does OpenShell run on Windows?

It runs experimentally with WSL 2 and Docker Desktop. Native Windows support is built from a separate branch and is not production-ready.

Is OpenShell free?

Yes, it is Apache 2.0 licensed and free; no account is needed. The cost of the model provider the agent uses and of the server is yours.

Does OpenShell block the agent from the internet completely?

The default policy allows no outbound network access. You open access with rules at the level of program, address, port and HTTP method; for example, you can give read-only access to an API.

Does the agent see my API key?

According to the docs, no: the agent sees a placeholder, and OpenShell adds the key only to requests going to the address approved in the provider profile.

What is the openshell package on PyPI?

The Python SDK; it is for connecting your application to an OpenShell gateway and does not install the command-line tool. The CLI comes via the install script, Homebrew, Debian/RPM or snap.

Does OpenShell collect data?

Anonymous telemetry is on by default: only operation categories and counts; file paths, prompts, credentials and content are not collected. It is turned off on the gateway with OPENSHELL_TELEMETRY_ENABLED=false.

Related guides

Sources

Not clear in the official sources: Intel-based Mac support (not in the support matrix) · minimum RAM and CPU (not stated in the docs) · the price of the NVIDIA Brev cloud trial · no Turkish interface (docs and CLI in English). Each is covered in the relevant section with what you can do.