NVIDIA OpenShell is an open-source runtime that lets AI agents work inside sandboxes with filesystem, process and network boundaries. Operators define which resources an agent may access, and runtime controls enforce that scope beyond instructions in a prompt. It is relevant when an agent runs tools, handles working files or calls APIs; output accuracy and authorization for business actions still require separate judgment. Official overview
What do the three architectural layers control?
NVIDIA's original article describes a sandbox, policy engine and privacy router. Current documentation describes the implementation through the sandbox, trusted supervisor, gateway and providers. The three-part view explains responsibilities; it is not a claim that three independent services execute in sequence. Original architecture article, current architecture
Original Gwarket diagram, November 5, 2026. The denial path represents enforcement; L7 audit mode logs violations without blocking them. Policy checks and credentials belong to the trusted side, rather than requiring two independently deployed services.
Sandbox: restrict the working environment
The agent and its tools run in a constrained workload. The current Linux implementation uses Landlock for filesystem restrictions, process controls and seccomp mechanisms. Network requests travel through a controlled channel to the external supervisor. This turns access boundaries into properties of the environment. Isolation architecture
That matters for code access and generated files. It does not establish whether an allowed document contains trustworthy information. Our distinction is between permission to access material and judgment about its contents.
Policy engine: make the allowed scope inspectable
YAML policies can constrain paths, process identity, destinations, calling programs and API requests. Filesystem and process settings are fixed at creation or startup, while network rules can change during execution. A live policy update does not mean every restriction can be changed without restarting. Policy controls and timing
Observation and blocking are different. With L7 inspection active, audit records rule violations but forwards traffic; enforce blocks requests that fail the rules. Logs alone do not establish that a write action was prevented. Audit versus enforce
Privacy and inference: check endpoints and credentials
Current inference documentation uses native provider APIs. A provider profile defines authorized endpoints and programs; an attachment grants a sandbox access, and real credentials are substituted only at an authorized endpoint. The client or workload selects the model and base URL. Attaching a provider does not select or rewrite the model. Current inference mechanism
Our first judgment: decide where the data may go before choosing a model. The original local/cloud routing concept should not become a promise that OpenShell automatically identifies every sensitive item and keeps it local. List the permitted materials, destinations and authorization owner, then compare that list with the actual configuration.
How to start: establish the prerequisites first
As of November 5, 2026, the latest GitHub release is v0.1.7, published November 3 UTC (November 4 in Taiwan). OpenShell uses Apache 2.0; the software license does not determine the cost of model services or compute. Release, versioned README
| Check | Current documented requirement |
|---|---|
| Host | Debian/Ubuntu Linux (x86_64/ARM64), or Apple Silicon macOS with Docker Desktop; Windows through WSL 2 and Docker Desktop is experimental |
| Infrastructure | A suitable Docker, Podman, Kubernetes or MicroVM deployment, not merely an installed CLI |
| Agent | An image containing the agent and tools; the default base sandbox has no agent installed |
| Models and services | Appropriate provider profiles, credentials and destination policies |
Support matrix, first-agent guide
The native Windows MXC path is documented separately in the windows branch. It has different requirements and limitations from WSL 2; consult its Windows guide.
The README starts with CLI and local gateway installation, followed by a basic sandbox. This is an official command example for reference, with installation and compatibility details in the linked guide:
openshell sandbox create --name demo
Creating this base sandbox does not finish agent, model, network or credential setup. The first-agent guide separately uses OpenCode to explain provider configuration, image selection, access attachments and proposals for additional destinations. Versioned quickstart, official agent example
Which work warrants these controls?
Our second judgment: evaluate the scope you can authorize, rather than choosing by agent name. For summarizing public text, begin with a way to review the result. For a long-running agent that writes files, installs tools or connects services, list the filesystem, process, destination and credential requirements before evaluating runtime controls.
Consider a fictional task: read product specifications and draft a proposal. Separate read access to specifications, write access to drafts, an approved model endpoint and permission to send the proposal. Those are distinct decisions. A sandbox does not decide which customer should receive a business commitment.
Investigate a denied connection before widening access
Issue #5093 reports an example involving v0.1.2: JVM and Bazel clients used IPv4-mapped IPv6 addresses and were denied despite an allowed endpoint. The issue was closed on November 5. Closure does not establish that every installed release includes the associated change; check the version and linked changes. Repository report and status
Use that report to narrow an investigation: compare versions, address forms and denial logs before changing policy. A connection failure alone does not prove an agent is unsupported, and allowing every destination conceals the distinction between a policy decision and an implementation problem.
Next steps
- AI agents versus chat: decide whether the work needs tool execution.
- Codex permissions: separate folder, network and approval questions.
Sources and verification date
Verified November 5, 2026, against release v0.1.7, its README and official documentation labeled Latest (v0.1.7). Living documentation and issue status may change.
- NVIDIA's original architecture article: the three-part conceptual model, rather than a current installation checklist.
- Architecture, policies, inference: current boundaries and configuration responsibilities.
- Support matrix, first agent, security practices: prerequisites, official examples and enforcement modes.
- Release v0.1.7, README, Issue #5093: version, license and a specific community report.
The destination checklist, task breakdown and investigation priorities are Gwarket's editorial judgments. The diagram is original explanatory artwork.