OpenShell: Control autonomous agents with kernel isolation and policy verification
A secure runtime for autonomous agents that limits file, network, and credential access with kernel isolation and policy verification.
GitHub NVIDIA/OpenShell Updated 2026-09-30 Branch main Stars 10.6K Forks 1.4K
Rust Go Autonomous AI agent security Kernel-level enforcement Kubernetes Linux/macOS Apple Silicon

🧭 Decision Guide

Try it if you

  • You need OpenCode to access files, install packages, and call APIs without opening the entire host network.
    README sections How It Works and Run Your First Agent: OpenShell declares and enforces file, system-call, and network policies for agents.
  • Your team needs to review new credential access to hosts or new API methods before approving a policy.
    README section Formally verified policy changes: formal verification flags these new accesses and waits for human review.
  • You run Kubernetes and can make the CNI enforce NetworkPolicy.
    README section Kubernetes: deploy the gateway with Helm, and Your CNI must enforce NetworkPolicy.

Skip it if you

  • Your environment is not Linux, Apple Silicon macOS, or Windows WSL 2, and does not provide the Docker, Podman, or host virtualization listed by the README.
    README Quickstart lists only these operating systems and runtime backends.
  • You need an agent out of the box and cannot accept that the default sandbox contains only minimal Ubuntu with no agent.
    README Quickstart explicitly says the default sandbox image is minimal Ubuntu with no agent installed.
  • Your Kubernetes CNI cannot enforce NetworkPolicy.
    README Kubernetes explicitly requires Your CNI must enforce NetworkPolicy.

Requirements

  • Linux, macOS on Apple Silicon, or Windows with experimental WSL 2.
  • Docker, Podman, or host virtualization.
  • For Kubernetes deployment, use Helm and ensure the CNI enforces NetworkPolicy.
  • Use the same OpenShell release for the SDK and gateway when possible.
  • The project provides Rust, Go, Python, and TypeScript SDKs; the TypeScript SDK uses GitHub Packages.

First step (verbatim from README)

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

Watch out

  • The installer sets up the CLI and local gateway, but does not install an agent in the default sandbox.
    README Quickstart: The installer sets up the CLI and a local gateway; the default image has no agent.
  • The Windows path is marked experimental and should not be treated as stable platform support.
    README Quickstart: Windows with WSL 2 (experimental).
  • Unless disabled, the gateway collects anonymous operational categories and counts.
    README Telemetry; set OPENSHELL_TELEMETRY_ENABLED=false or Helm server.telemetryEnabled=false to disable it.
  • SDKs do not install the CLI, and the Rust installation line leaves the --tag argument empty.
    README SDKs: SDKs do not install the CLI; the Rust line is cargo add openshell-sdk --git https://github.com/NVIDIA/OpenShell --tag .

Not stated in the README

  • The README does not state sandbox resource consumption, concurrency limits, or maximum agent counts.
  • The README does not specify the Linux kernel version range covered by kernel-level enforcement.
  • The README does not quantify formal-verification latency, policy language support, or false-positive behavior.
  • The README does not explain functional differences between Docker, Podman, and host virtualization.
  • The README does not name the specific OpenCode or OpenRouter free model or provide stability data.
  • The README does not describe high availability, upgrade, or failure-recovery procedures for a Kubernetes gateway.
  • The README does not establish whether 10 contributors and 5 releases provide sufficient production support.
  • The README does not define the compliance boundary between Apache License 2.0 and external retrieved materials for a specific business.

💡 Deep Analysis

6
Yes I maintain Python and TypeScript applications and want to connect to an OpenShell gateway through SDKs, embedding agent runtime capabilities into existing services instead of installing the CLI in the application process. Is this integration path viable?
For: An AI platform engineer maintaining Python and TypeScript applications who needs to connect to an OpenShell gateway through SDKs without depending on the CLI

Yes. The README explicitly positions the SDKs as application interfaces to an OpenShell gateway and provides installation paths for Python and TypeScript, but the SDK does not install the CLI for you.

  • The SDK section lists uv add openshell for Python and npm install @nvidia/openshell-sdk for TypeScript, giving both languages a direct integration path.
  • It states: “SDKs connect applications to an OpenShell gateway. They do not install the CLI.” The gateway therefore remains a separately deployed service.
  • Go and Rust SDKs are also available, and the README recommends using the same OpenShell release for the SDK and gateway whenever possible; version pairing is part of the integration contract.
  • The TypeScript package is hosted in GitHub Packages, so the build environment must handle package-source access and authentication.

This fits an existing Python or TypeScript service that needs embedded control-plane access, but not a fully self-contained local agent runner based only on the SDK.

  • SDKs: “SDKs connect applications to an OpenShell gateway. They do not install the CLI.”
  • SDKs: Python `uv add openshell`
  • SDKs: TypeScript `npm install @nvidia/openshell-sdk` (GitHub Packages)
  • SDKs: “Use the same OpenShell release for the SDK and the gateway when possible.”
Not stated in the README:The README does not describe API coverage, authentication, async behavior, or connection-failure handling for the Python and TypeScript SDKs.;It does not specify the token permissions or enterprise-proxy configuration required for GitHub Packages.
Yes I need autonomous agents to call approved external APIs and inference providers, but I cannot place general-purpose cloud keys inside the sandbox. Does OpenShell’s credential and policy model satisfy this constraint?
For: An enterprise security engineer who needs agents to access approved APIs and inference services without exposing general-purpose cloud keys

Yes. OpenShell binds credentials to approved endpoints and identifies newly introduced hosts, credentials, and API methods during policy changes. That directly addresses the requirement to call services without exposing a general-purpose key to the agent.

  • How It Works states that agents never see real credentials; OpenShell adds them only to requests bound for approved endpoints.
  • The Providers section describes credentials that work only at approved endpoints and includes inference provider configuration, allowing model access to enter the same governance model.
  • Policy changes are checked with formal verification; a new credentialed host or API method is flagged for human review before approval.
  • These controls govern requests routed through OpenShell. They do not make external services, malicious dependencies, or business authorization safe by themselves.

Therefore, OpenShell fits as a credential-proxy and egress-control layer, but it does not replace enterprise identity governance, data classification, supply-chain scanning, or business-level authorization for external APIs.

  • How It Works: “Agents never see real credentials; OpenShell adds them only to requests bound for approved endpoints.”
  • Explore Further / Providers: “credentials that work only at approved endpoints, including inference”
  • How It Works: “flag risky new access ... reaching a new host with credentials or calling a new API method”
Not stated in the README:The README does not identify supported cloud vendors, authentication protocols, credential-rotation mechanisms, or short-lived-token lifetimes.;It does not define the exact endpoint-binding behavior for redirects, DNS, proxy services, or API gateways.
Yes I use OpenCode on Apple Silicon macOS and need the agent to install packages, read project files, and access a code repository. Is OpenShell suitable if I do not want to expose the host and all credentials to the agent?
For: A developer running OpenCode on Apple Silicon macOS who needs a coding agent to install dependencies and access a code repository

Yes, because OpenShell provides a sandbox, filesystem policy, network policy, and endpoint-bound credentials on a supported local platform instead of giving OpenCode unrestricted host access.

  • The Quickstart explicitly supports Apple Silicon macOS and requires Docker, Podman, or host virtualization.
  • Each agent runs in an isolated sandbox; kernel controls restrict files and system calls, while every outbound network connection is checked by policy.
  • The agent never sees real credentials; OpenShell adds them only to requests bound for approved endpoints.
  • The default sandbox is a minimal Ubuntu image with no agent installed, so running OpenCode requires following “Run Your First Agent” and approving the required access.

This fits the local coding scenario, but the README does not specify the exact directory, package-manager, or repository policies OpenCode needs, nor does it establish identical performance across all Apple Silicon virtualization combinations.

  • Quickstart: “You need Linux, macOS on Apple Silicon, or Windows with WSL 2 (experimental)”
  • How It Works: “Each agent runs in an isolated sandbox”
  • How It Works: “Agents never see real credentials”
  • Quickstart: “The default sandbox image is minimal Ubuntu with no agent installed”
openshell sandbox create --name demo
Not stated in the README:The README does not list the exact file paths, package managers, or repository domains that OpenCode must access.;It does not describe performance or compatibility differences among Docker, Podman, and host-virtualization backends on Apple Silicon.
It depends I need to deploy the OpenShell gateway with Helm on Kubernetes, manage multiple agent sandboxes, and rely on the existing CNI to enforce NetworkPolicy. Under what conditions is it suitable as a platform runtime?
For: A DevSecOps engineer responsible for a Kubernetes platform who needs to manage multiple agent gateways with Helm and depends on the CNI enforcing NetworkPolicy

It depends: OpenShell is suitable only when the cluster’s CNI genuinely enforces NetworkPolicy, the team can operate the gateway and policies, and the organization accepts that the 0.1.x interface is still evolving.

  • The Kubernetes section supports Helm deployment but explicitly requires the CNI to enforce NetworkPolicy; creating policy objects alone does not prove that traffic is blocked.
  • The gateway is the control plane for sandboxes, policies, and access, making it relevant for centrally managing multiple agents rather than launching one container.
  • The README exposes sandbox images, runtimes, GPUs, and lifecycle management, so the platform must also operate resource and agent-state controls.
  • Project data marks the latest release as dev, while the README describes new APIs and isolation primitives in 0.1.x; policy semantics and interfaces therefore need compatibility validation.

If CNI behavior, node privileges, or version compatibility cannot be established, OpenShell’s network controls should not be treated as the cluster’s complete security boundary.

  • Explore Further / Kubernetes: “deploy the gateway with Helm. Your CNI must enforce `NetworkPolicy`”
  • Explore Further / Gateways: “the control plane for sandboxes, policy, and access”
  • Explore Further / Sandboxes: “images, runtimes, GPUs, and lifecycle”
  • Project data: latest_release is `dev`; README: “New in OpenShell 0.1.x ... new APIs”
Not stated in the README:The README does not identify supported CNI implementations, Kubernetes versions, node runtimes, or GPU-plugin combinations.;It provides no capacity data for multiple gateways, high availability, upgrades, rollbacks, or large sandbox fleets.
It depends I need to maintain the OpenShell gateway, Python SDK, and several components that are still under development. Given that the latest project release is marked dev, should I use it now as the foundation of a production agent platform?
For: An infrastructure engineer responsible for agent-platform version governance who must maintain the OpenShell gateway, Python SDK, and multiple development-stage components

It depends. The project has the architecture needed for governed agent execution, but its release status and version-pairing requirements make it unsuitable for an unvalidated, high-criticality production dependency.

  • Project data marks the latest release as dev and reports five releases. The README also says that 0.1.x adds new isolation primitives, an expanded extension surface, and new APIs, indicating continued evolution.
  • The SDK section recommends using the same OpenShell release for the SDK and gateway whenever possible; mixing gateway, SDK, and CLI versions creates compatibility risk.
  • The project provides explicit gateway, sandbox, policy, provider, and Kubernetes paths, so its scope is platform integration rather than merely experimental container startup.
  • The README documents prerelease and development builds as supported ways to try upcoming releases or the latest main commit, but that is not a stability guarantee.

Use it as a controlled platform dependency if the team can maintain a version matrix, validate upgrades, and handle policy compatibility. If stable APIs, long-term support, and low operational effort are mandatory, the current evidence is insufficient.

  • Project data: latest_release is `dev`; release_count is 5
  • README Important notice: “New in OpenShell 0.1.x: ... new APIs”
  • SDKs: “Use the same OpenShell release for the SDK and the gateway when possible.”
  • Explore Further: “Prerelease and development builds”
Not stated in the README:The README does not provide support lifecycles, backward-compatibility guarantees, upgrade rollback procedures, or production SLAs.;It does not provide a complete compatibility matrix for gateway, SDK, CLI, and policy formats.
It depends I run an automation/operations agent on Linux that must access selected files, install packages, and use a GPU. Can OpenShell preserve these capabilities while providing sufficient isolation?
For: A platform engineer running an automation/operations agent on Linux that must read selected host files and use a GPU

It depends. OpenShell can control files, system calls, networking, and sandbox resources, but requiring host files, GPUs, or privileged system resources makes the isolation boundary and operational burden substantially more complex.

  • The Quickstart supports Linux and requires Docker, Podman, or host virtualization, providing a supported local execution foundation.
  • How It Works says kernel-level controls restrict file access and system calls, while network connections are checked before leaving the sandbox.
  • The Sandboxes section explicitly covers images, runtimes, GPUs, and lifecycle, so GPU use is part of the documented resource model rather than an entirely unaddressed scenario.
  • The project insights state that real files, internal services, GPUs, or highly privileged system resources complicate the isolation boundary; the sandbox does not replace hardening of the host, kernel, image, or runtime.

It therefore fits when file and resource access can be narrowly bounded. If the agent needs broad host access or privileged interfaces, the README does not provide enough evidence that the resulting risk is acceptable.

  • Quickstart: “You need Linux ... plus Docker, Podman, or host virtualization.”
  • How It Works: “Kernel controls confine which files it can access and which system calls it can make”
  • Explore Further / Sandboxes: “images, runtimes, GPUs, and lifecycle”
  • Project insights / usage_limitations: real files, GPUs, or highly privileged system resources complicate the isolation boundary
openshell sandbox create --name demo
Not stated in the README:The README does not specify the drivers, container runtime, device policies, or isolation strength required for GPU passthrough.;It does not specify how host-file mounts should be configured, which syscalls an operations agent needs, or the performance overhead.

✨ Highlights

  • Kernel-level isolation controls files, system calls, and network connections
  • Formal verification flags policy changes adding host access
  • Credentials are injected only into requests to approved endpoints
  • Kubernetes deployment requires the CNI to enforce NetworkPolicy

🔧 Engineering

  • Builds an agent runtime from sandboxes, policies, and a gateway
  • Supports OpenCode, OpenRouter models, and multilingual SDKs
  • Uses advisor and prover to review filesystem, network, and process rules

⚠️ Risks

  • Windows support depends on experimental WSL 2
  • The default sandbox is a minimal Ubuntu image without an agent
  • The gateway collects anonymous operational-category and count telemetry
  • Users must review the licenses and security of external materials

👥 For who?

  • Teams that need to constrain autonomous agents' file, API, and credential access
  • Developers running Linux, Apple Silicon macOS, or WSL 2
  • Platform teams using Kubernetes, Helm, and NetworkPolicy