OpenShell deep dive: NVIDIA's runtime for autonomous AI agents — not approval, not a container, a policy-bounded execution environment

I. At a glance

★★★★☆ (4/5). A Rust project from NVIDIA, Apache-2.0, 8.7k stars / 1.3k forks (as of 2026-09-22). It fills the gap left when you strip away agentgate-style approval workflows and SkillSpector-style skill auditing: a policy-bounded runtime for autonomous AI agents. The agent is not waiting for approval — it runs inside an isolated container wrapped in four layers of declarative policy, and every outbound request passes through a three-state gate (allow / bind credentials / deny). One star off because 0.1.0 has not shipped yet (the repo is alpha and the very first line of the README says “OpenShell 0.1.0 is coming soon”), and the 403 open issues show this is a project still moving fast — don’t put it in production, but research / internal / controlled environments can absolutely try it.

Who is it for (per-audience score, 5-point scale):

Forks (Apache-2.0, three difficulty tiers):

II. What it is, what it isn’t

Before you open https://github.com/NVIDIA/OpenShell, three clarifications, because OpenShell is not several things that share the same neighborhood:

Not an approval workflow. agentgate — same broad category of “AI Agent control” — takes the approach: agent wants to act, dashboard / Slack / Discord approves. OpenShell goes the opposite way: deny by default, allow by policy. The agent is not applying for permission; it is running inside a container already surrounded by policy. Want to hit the GitHub API? Check the YAML first.

Not an agent vulnerability scanner. NVIDIA/SkillSpector scans agent skills for prompt injection or dangerous commands — entry point is the skill file. OpenShell doesn’t scan; it manages runtime. Assume your skills are clean and your agent is well-behaved; OpenShell adds the “what if it goes off the rails” safety net.

Not a CALDERA-style BAS. CALDERA is MITRE’s red-team automation platform (adversary emulation). OpenShell is a blue-team tool for “letting the agent act inside a smaller, trusted boundary.” They face opposite directions — OpenShell assumes you are defending production and the agent is a “trusted-but-needs-constraints” subject, not an attacker you are simulating.

So what is OpenShell? The official one-liner:

OpenShell is the safe, private runtime for autonomous AI agents. It provides sandboxed execution environments that protect your data, credentials, and infrastructure — governed by declarative YAML policies that prevent unauthorized file access, data exfiltration, and uncontrolled network activity.

Three keywords: sandboxed execution / declarative YAML policies / protect data credentials infrastructure.

III. Four protection layers × four components

OpenShell’s architecture splits cleanly into “four components managing four protection layers,” but the interaction sequence and responsibility boundaries matter more than the table itself.

Four components (README):

The Gateway is the control plane, not the policy enforcement point. The architecture docs are explicit: the Gateway exposes gRPC APIs (lifecycle, provider management, policy updates, logs, watch streams, relay forwarding) and HTTP endpoints (health, WebSocket tunnels, edge-auth), but it does not make per-request network policy decisions — those happen inside the sandbox, in the supervisor + proxy. The Gateway only stores and delivers policy; actual enforcement occurs at the kernel layer. This design lets the Gateway scale horizontally without becoming a performance bottleneck, and it avoids the “policy is outside, agent is inside” routing problem.

Sandbox Readiness state machine. The Gateway composes driver-reported status with supervisor session state into the externally visible SandboxPhase:

1
2
3
4
5
6
7

backend_phase = derive_phase(driver_status)

public_phase =
  backend_phase in {Error, Deleting}                → pass through (terminal precedence)
  driver_reports_runtime_readiness && Ready         → Ready
  backend_phase == Ready && session connected       → Ready
  backend_phase == Ready && no session              → Provisioning

For supervisor-controlled drivers (Docker, Podman, VM), the driver saying Ready is not enough — the supervisor gRPC session must also be established before the sandbox is Ready. For Kubernetes (a driver-reports-runtime-readiness driver), the driver’s Ready is authoritative. This distinction determines how long you wait after openshell sandbox create before you can connect — local Docker is usually seconds; Kubernetes may wait for Pod scheduling + image pull.

Policy Engine’s 6-step network decision flow. All outbound traffic inside the sandbox is forced through the proxy, which decides in this order (architecture/security-policy.md):

1. Force proxy — namespace + seccomp controls ensure traffic can only go through the proxy;
2. Binary identity — identify the requesting process binary path and compare against the binaries whitelist in policy;
3. Hard-block — reject dangerous internal IP ranges (e.g., 169.254.x.x, 10.x.x.x) unless explicitly allowed;
4. Policy match — match destination + port + binary against network policy blocks;
5. L7 rules — for endpoints with protocol inspection enabled, check HTTP method + path;
6. Action — allow / deny / audit / log. Explicit deny and hardening checks win over allow; no match → deny.

Four protection layers (defense in depth):

Why are Filesystem and Process locked at creation while Network and Providers can hot-reload? Because the first two are hard to walk back once granted (a file may have been copied somewhere else, an escalated process can spawn any child process), while the latter two are more like temporary passes — adding GitHub API to the network whitelist, attaching a new model profile for a different provider — both can be loaded live.

IV. Network policy and credential model (L7 + endpoint-bound)

The two pieces worth expanding on are network policy and credential model, because these are the biggest gap between OpenShell and “just another Docker sandbox.”

Network: L7 granularity, minimal egress by default

The Quickstart in the README shows a full “deny, then allow” cycle:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 1. Create a sandbox (starts with minimal outbound access)
openshell sandbox create

# 2. Inside the sandbox — blocked
sandbox$ curl -sS https://api.github.com/zen
curl: (56) Received HTTP code 403 from proxy after CONNECT

# 3. Back on the host — apply a read-only GitHub API policy
sandbox$ exit
openshell policy set demo --policy examples/sandbox-policy-quickstart/policy.yaml --wait

# 4. Reconnect — GET allowed, POST blocked by L7
openshell sandbox connect demo
sandbox$ curl -sS https://api.github.com/zen
Anything added dilutes everything else.

sandbox$ curl -sS -X POST https://api.github.com/repos/octocat/hello-world/issues -d '{"title":"oops"}'
{"error":"policy_denied","detail":"POST /repos/octocat/hello-world/issues not permitted by policy"}

Three details worth noting:

1. The 403 comes from the proxy, not from GitHub — the agent cannot get out at the network layer, regardless of DNS / IP / HTTPS tricks;
2. GET is allowed, POST is blocked — the policy is not a domain allow/deny list, it is “GET to https://api.github.com is allowed, POST is not.” That is L7 granularity, a big step up from most “egress allowlist” products that stop at L4 (IP + port);
3. Hot-reload does not require restarting the sandbox — the sandbox keeps running while openshell policy set ... --wait applies the new policy.

Policy YAML field structure

The full structure of examples/sandbox-policy-quickstart/policy.yaml is the starting point for understanding L7 policy:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

version: 1

filesystem_policy:
  include_workdir: true
  read_only: [/usr, /lib, /proc, /dev/urandom, /app, /etc, /var/log]
  read_write: [/sandbox, /tmp, /dev/null]

landlock:
  compatibility: best_effort

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

Key fields:

• version: 1 — the only supported version; the parser rejects unknown fields with no permissive parsing mode;
• filesystem_policy — static filesystem rules; read_only / read_write lists determine what paths the agent can touch;
• landlock — Linux Landlock LSM compatibility setting; best_effort means the sandbox starts even if the kernel does not support Landlock (with a warning logged);
• network_policies.<key> — named policy blocks, each containing endpoints (target host/port/protocol/access) and binaries (process whitelist).

Host wildcard rules. endpoints[].host supports * wildcards, but with two hard constraints: only in the first DNS label, or as an entire middle label. The OPA runtime matches with a . label boundary, so *.github.com matches api.github.com, but api.*.com does not. The validator enforces this boundary at policy load time, preventing silent mismatches at the proxy.

Landlock implementation details

OpenShell uses Linux Landlock LSM for filesystem enforcement, not just chroot:

• Inode-type-distinguished rights. Landlock rules assign permissions based on the inode type reported by the already-opened path descriptor: directories keep directory + file rights; regular files, device nodes, and sockets keep only file-compatible rights. This lets mixed-path policies (e.g., /dev containing both directories and device nodes) succeed without weakening hard_requirement.
• Baseline path enrichment. Before applying Landlock, the supervisor auto-supplements baseline paths the runtime needs (e.g., /proc, /dev/urandom). Missing baseline paths are skipped rather than invalidating the entire ruleset.
• GPU special handling. When GPU is enabled, the supervisor adds existing GPU device nodes as read-write paths and promotes /proc to read-write because CUDA workloads write thread metadata under /proc/<pid>/task/<tid>/comm.

Credentials: never touch disk, bound to endpoints

OpenShell abstracts all API keys / tokens / service accounts as Providers (named credential bundles). Provider declarations come from provider profiles. Here is providers/anthropic.yaml:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

id: anthropic
display_name: Anthropic
description: Anthropic inference API
category: inference
inference_capable: true

credentials:
  - name: api_key
    description: Anthropic API key

endpoints:
  - host: api.anthropic.com
    port: 443
    protocol: rest
    enforcement: enforce
    access: read-write

binaries:
  - path: /usr/bin/curl
  - path: /usr/local/bin/curl

And providers/claude-code.yaml, showing the complexity of an agent-type profile:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

id: claude-code
display_name: Claude Code
description: Claude Code CLI
category: agent
inference_capable: true

credentials:
  - name: api_key
    description: ANTHROPIC_API_KEY or CLAUDE_API_KEY

endpoints:
  - host: api.anthropic.com        # inference endpoint
  - host: statsig.anthropic.com    # CLI telemetry
  - host: sentry.io                # error reporting

binaries:
  - path: /usr/bin/claude
  - path: /usr/local/bin/claude

Key design choices:

“Endpoint-bound” is the biggest difference from a regular secret manager: a secret manager hands the agent the full key and lets it go, OpenShell only gives the agent a temporary use of the key for the specific request the policy admits, and the moment the request ends, the binding is gone. The binaries field adds a second layer: even if the key is read, only specific processes can use it.

V. SDKs and ecosystem

Four official SDKs

Note the Rust SDK is still source-only — the README explicitly says “pin the Git dependency to the same OpenShell release as the gateway.” With 0.1.0 unreleased, the crate has not landed on crates.io.

Officially supported agents

These are not “OpenShell takes over the agent” — they are “OpenShell knows the agent’s binary paths, required endpoints, and credential types, and ships profiles pre-tuned for them.” Any other agent (custom, in-house SDK) can also run — you write the image, write the profile, declare the endpoint.

Agent Skills dual-layer system

OpenShell splits skills into two layers, embodying its “agent-first” design philosophy:

Public skills (skills/ directory, user-installable):

• openshell-cli — CLI workflow assistance
• debug-openshell-cluster — Gateway cluster troubleshooting
• debug-inference — Inference endpoint troubleshooting
• generate-sandbox-policy — Auto-generate sandbox policy

Install:

1

npx skills add NVIDIA/OpenShell

Contributor / Maintainer skills (.agents/skills/ directory, not distributed with public skills):

• create-spike → state:accepted → optional agent:* planning and implementation workflow
• triage-issue — agent assesses technical validity and impact; humans decide whether to schedule
• review-security-issue / fix-security-issue — security assessment and remediation
• sync-agent-infra, update-docs-from-commits — repository maintenance

The README states the project is “built agent-first” — not only does it provide agent tools to users, its own development workflow is agent-driven. Contributor skills are not for end users, but they signal NVIDIA’s bet on agent-driven development.

How to put an agent inside

1
2
3

# The default image contains only Ubuntu 24.04 — no agent CLI.
# You either build your own image or pull one from a registry:
openshell sandbox create --from registry.example.com/agents/my-agent:1.0 -- my-agent

“Installing OpenShell” and “having an agent run inside OpenShell” are two different things. OpenShell provides isolation and policy; you are responsible for putting the agent into the image. That is a deliberate responsibility split: the runtime does not take the blame for an agent that misbehaves.

Terminal UI

openshell term launches a k9s-style real-time terminal dashboard that auto-refreshes every 2 seconds:

• Tab switches panels
• j/k moves up/down
• Enter selects
• : enters command mode

The TUI is not cosmetic — it is a terminal frontend for the Gateway gRPC watch stream, showing real-time sandbox status, provider attachments, and policy decision logs (action=allow in green / action=deny in red).

VI. Model freedom / compute backends / GPU

Four compute drivers compared

OpenShell’s compute runtimes do not evaluate policy themselves; they only start and stop workloads per the Gateway’s spec. But the four drivers differ significantly (architecture/compute-runtimes.md):

The Podman driver deserves its own paragraph. Unlike Docker, Podman uses the libpod API to start two containers simultaneously — one workload (the agent runs inside) and one supervisor (runs outside). The workload container has no network at all (network=none); all outbound must go through the supervisor container’s proxy. The two containers share only a user namespace (for volume ownership), not PID, mount, or network namespace. This means even if the workload container is compromised, the attacker has no network access — because the workload container has no network interface.

The 7 requirements of the Driver Contract (from the architecture docs):

1. Select the sandbox image;
2. Resolve an immutable non-root sandbox identity before workload creation;
3. Supply separate bootstrap material for workload and supervisor;
4. Deliver openshell-sandbox only to the workload, openshell-supervisor only to the supervisor;
5. Provide a protected control channel (Unix socket / TLS TCP / vsock);
6. Forward the exact main-process argv and TTY mode without shell reconstruction;
7. Report lifecycle events and clean up runtime-owned resources.

What you can and cannot change

GPU passthrough deserves its own paragraph. openshell sandbox create --gpu ... will attempt CDI (Container Device Interface) first and fall back to Docker’s --gpus all if CDI is not available. The documentation is refreshingly honest: “Expect rough edges and breaking changes.” It is genuinely experimental — do not stake production on it.

Telemetry compilation options

Telemetry is not a single on/off switch; OpenShell offers three levels of control:

1. Runtime disable (gateway level, propagated to sandboxes):

1
2
3

OPENSHELL_TELEMETRY_ENABLED=false openshell gateway ...
# Helm install:
helm install openshell ... --set server.telemetryEnabled=false

2. Compile-time removal (produces binaries with no telemetry endpoint, HTTP client, or emission code):

1
2

cargo build --release -p openshell-gateway \
  --no-default-features --features defaults-without-telemetry

Note: --no-default-features must be paired with defaults-without-telemetry; passing --features defaults-without-telemetry alone fails because Cargo does not support “subtract a single default feature.”

3. Per-driver trimming. Gateway Cargo features also include compute-driver-kubernetes, compute-driver-docker, compute-driver-podman, compute-driver-vm, and compute-driver-mxc (Windows). Compile only the drivers you need:

1
2
3
4
5
6
7

# Docker only, with telemetry
cargo build --release -p openshell-gateway \
  --no-default-features --features telemetry,compute-driver-docker

# Docker and VM only, telemetry compiled out
cargo build --release -p openshell-gateway \
  --no-default-features --features compute-driver-docker,compute-driver-vm

Telemetry data scope is also documented precisely: only anonymous operational categories and counts (sandbox lifecycle outcomes, provider profile buckets, policy decision counts, network denial categories). It never collects sandbox names/IDs, hostnames, file paths, binary paths, prompts, credentials, provider names, model names, or user content.

VII. Boundaries and risks

Before you push OpenShell toward production, a few facts you need to know:

1. 0.1.0 has not shipped. The first line of the README is > [!IMPORTANT] OpenShell 0.1.0 is coming soon. The repo is alpha, which means:

• The API / CLI commands can change before 1.0;
• The latest docs link actually points at the 0.0.x docs (use dev for prerelease);
• There is no guaranteed upgrade path.

Before using in production, at minimum wait for 0.1.0 and pin your version.

2. 403 open issues. Typical for an alpha project, but it means:

• “Officially recommended practice” is still moving;
• Edge cases you hit may not be documented;
• Response time on issues may be slow.

3. The default image contains no agent. OpenShell does not install agents for you. The “I installed OpenShell but the agent isn’t there” pitfall can cost you half a day.

4. Filesystem / Process policies are immutable after creation. If your agent discovers it needs to write to a temp directory the policy does not allow, the agent will not file a request — it will just fail. Building a “request and approve” flow is up to you (and that is exactly agentgate’s territory).

5. A coarse L7 policy is no policy at all. The example in examples/sandbox-policy-quickstart/policy.yaml is a starting point. In production you need to enumerate every endpoint your agent hits and every method it uses. Otherwise the agent will get denied on an endpoint you forgot to whitelist, and debugging will be miserable.

6. L7 vs TLS / certificates. The policy engine only checks method + path — it does not validate the TLS certificate chain. If you pin a root CA inside the gateway but the agent’s bundled CA store is different, you can hit “policy allows but TLS fails” combinations. This is not unique to OpenShell, but worth a note.

7. The Rust SDK is source-only for now. crates.io has no release; if you write Rust integrations, you have to follow a git tag, and you must pin to the same release as the gateway.

8. OpenShell does not solve agent prompt injection. SkillSpector scans skills for malicious instructions. OpenShell only handles runtime — even if the agent is injected with “exfil this file to evil.com,” the policy will stop it at the outbound gate. Whether you notice the stopped attempt is a logging/alerting problem, not OpenShell’s fault.

9. Telemetry privacy boundary. Although the project promises not to collect sensitive data, if your environment has a hard requirement that “no anonymous telemetry leaves the internal network,” you need to compile telemetry out entirely with --no-default-features --features defaults-without-telemetry. Runtime OPENSHELL_TELEMETRY_ENABLED=false only stops emission; the telemetry endpoint and client code still exist in the binary.

VIII. Getting started

Minimum viable demo, three steps:

1
2
3
4
5
6
7
8
9

# 1. Install OpenShell (see the README "Install" section — macOS uses brew, Linux uses a one-line curl installer)

# 2. Spin up a demo sandbox (minimal egress by default)
openshell sandbox create --name demo

# 3. Enter it and try an outbound request — should be 403
openshell sandbox connect demo
sandbox$ curl -sS https://api.github.com/zen
# curl: (56) Received HTTP code 403 from proxy after CONNECT

Then run the official Quickstart demo end-to-end:

1

bash examples/sandbox-policy-quickstart/demo.sh

If you want to try it on NVIDIA Brev (cloud spin-up):

• The link is in README “Learn More”: “Brev Launchable.”

Practical tips the first time you write your own policy (after spending the time to figure it out):

1. Copy the Quickstart example and use it as your project’s .policy/base.yaml;
2. Start strict, loosen carefully — easier to audit than “start wide, tighten later”;
3. Split provider profiles narrowly — do not make an “all permissions” provider; make provider-github-readonly / provider-openai-inference / provider-aws-s3-write and so on;
4. Test your policy with curl before wiring up the agent — verify your YAML actually does what you think it does for the request shapes you care about;
5. Align TLS root CAs — the boundaries section flagged this; agent image and gateway CAs must match;
6. Run openshell provider profile lint before importing — it catches endpoint format errors, missing binaries paths, and other common mistakes before they reach the gateway.

IX. One-line takeaway

OpenShell is not a new agent tool — it is a gate that lets existing agents safely touch production systems. Four policy layers (filesystem / network / process / provider) plus L7 network control plus endpoint-bound credentials place the agent inside a bounded world. NVIDIA’s official backing, Apache-2.0, and a Rust implementation mean this is worth keeping on the radar as a serious foundation, but with 0.1.0 unreleased it is a tool for research / internal / controlled environments today. Production deployments should wait for at least a couple of minor releases past 0.1.0. When you start using it, clone an example policy and write your own first before plugging in an agent — skipping that step will cost you an hour on TLS / endpoint matching, just like it did me.