What is OpenShell and how do I use it?

An AI agent investigating a failing service needs more than a conversation window. It needs the code, the logs, and often a way to call an API. Give it your ordinary terminal and it may also inherit access to unrelated repositories, cloud credentials, and whatever else your account can reach.

NVIDIA OpenShell is an open-source runtime that runs agents inside controlled sandboxes. You define the files, processes, destinations, and supported API operations they may use. OpenShell enforces those permissions outside the agent’s reasoning, so a convincing instruction in a README cannot simply talk the controls into disappearing.

The practical question is how much access a task needs. We’ll start with a working agent, then remove the model from the experiment and use curl to make an allowed request and a denied request visible. Finally, we’ll apply that same approach to an SRE investigation.

This is a documentation-based walkthrough. Commands and expected behavior were checked against NVIDIA’s published references; they were not executed in this authoring environment.

What OpenShell does for an agent

OpenShell supplies the execution environment around an agent. The agent still selects tools and reasons about its task, while the runtime controls what those tools can touch. NVIDIA documents support for agents including Codex, Claude Code, Pi, and Hermes. Your workload image must contain the agent and the programs it needs.

That separation lets you change the model or agent without treating each new setup as permission to inherit your workstation. For example, an investigation agent can read a copied incident bundle, call one model service, and write a proposed patch in its own workspace. Access to the production control plane is a separate decision.

NVIDIA made OpenShell part of its broader Open Agent Safety Platform announcement on September 28, 2026. That platform also includes Sentry, a hardware watchdog reference design. The local walkthrough here uses OpenShell’s software controls and a container runtime; it does not require Sentry or an NVIDIA GPU.

Sources: NVIDIA’s runtime introduction, September 28 announcement, and support matrix.

A container alone can restrict an agent, but the restrictions depend on how you configure it. OpenShell adds a common policy and management layer around that execution. Conversely, an OpenShell policy does not determine whether a diagnosis is correct or whether a permitted change will help customers. Those remain application and operational questions.

How the sandbox actually works

Three components matter. The gateway manages sandboxes and configuration. The workload contains the agent and its tools. A separate, trusted supervisor evaluates outbound requests and opens the approved connections.

The workload has no ordinary direct route to the outside network. Its traffic travels through the protected supervisor channel. On Docker and Podman, the supervisor lives in another container and the workload’s normal networking is disabled. Kubernetes uses separate pods and NetworkPolicy; the VM runtime uses a guest without a network device.

Inside the Linux workload, Landlock restricts filesystem access, while seccomp and process controls constrain operations. Landlock is a Linux security mechanism for limiting what a process can access. Seccomp filters or mediates system calls, the requests programs make to the kernel.

If the supervisor connection disappears, the sandbox freezes the agent. That is useful containment behavior, but it cannot undo an API request a remote service already accepted. The distinction matters when agents eventually get write access.

Source: OpenShell architecture.

Install OpenShell on your workstation

Use Linux or an Apple Silicon Mac for the most straightforward local path. Windows through WSL 2 and Docker Desktop is listed as experimental. NVIDIA specifies Docker Desktop or Engine 28.0 or newer for Docker-backed gateways, or Podman 5.x for supported Linux workflows. MicroVM is another option, but Docker is enough for this guide.

Start your container runtime, then run NVIDIA’s installer on the host:

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

The installer sets up the CLI and a local gateway. openshell status checks whether the CLI can reach that gateway. On macOS, the package runs the gateway as a Homebrew service; Debian and RPM installations use a systemd user service.

For a reproducible evaluation, select a stable release rather than a floating development build. The installer accepts OPENSHELL_VERSION. Most documentation pages reviewed for this guide identify v0.1.4, so the corresponding pinned command is:

curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | \
  OPENSHELL_VERSION=v0.1.4 sh

Review the install script before running it on a managed workstation, or use your organization’s package distribution process. Keep the CLI, gateway, supervisor, and sandbox runtime aligned to the selected release.

Sources: installation and supported platforms and runtime requirements.

Run your first AI agent

The quickest route in NVIDIA’s first-agent guide uses OpenCode with OpenRouter. OpenRouter supplies the model API; OpenCode supplies the agent. OpenShell supplies the environment around both.

First, load your OpenRouter key into the host shell using your normal secret-management method. The following Bash/Zsh input avoids putting the literal key in a command saved to shell history:

printf 'OpenRouter API key: '
IFS= read -r -s OPENROUTER_API_KEY
printf '\n'
export OPENROUTER_API_KEY

Import the service profile and create the provider:

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

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

unset OPENROUTER_API_KEY

The profile describes the endpoint and executable access. The provider stores the credential. --from-existing reads it from the host environment.

Create the agent sandbox:

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

This follows NVIDIA’s documented example. Model availability and free-tier terms can change; select another model if the named option is unavailable. Ask the agent to explain the files it can see before giving it a larger task.

Source: Run Your First Agent. The floating image and profile URL are convenient for exploration; pin reviewed artifacts for repeatable runs.

If you prefer Pi, NVIDIA publishes a complete Pi and OpenRouter walkthrough. It builds an image with the search tools Pi needs and uses a profile for the Node.js executable. That is a useful companion to our Pi guide; avoid attaching an agent-specific profile to a different image without checking the executable paths.

See exactly what a policy allows

A model’s response is a noisy way to test an access rule. It might choose another tool, give up early, or never attempt the request. A direct command makes the test easier to interpret.

We’ll build a small workload image that contains curl. This original example is adapted to NVIDIA’s network-policy tutorial. Save the following as Dockerfile.tools in an otherwise empty directory:

FROM ubuntu:24.04
RUN apt-get update \
    && apt-get install -y --no-install-recommends curl ca-certificates \
    && rm -rf /var/lib/apt/lists/*
RUN useradd --create-home --uid 10001 agent \
    && mkdir -p /workspace && chown agent:agent /workspace
USER agent
WORKDIR /workspace

Build the image on the same Docker engine your gateway uses. Then create a sandbox without automatically attaching providers:

docker build -t openshell-tools:local -f Dockerfile.tools .
openshell sandbox create \
  --name policy-lab \
  --from openshell-tools:local \
  --no-auto-providers

Keep that interactive shell open. In a second host terminal, inspect the policy before testing it:

openshell policy get policy-lab --full

Confirm that no network rule permits the GitHub API. An image policy, a saved sandbox policy, providers, or a gateway-wide policy can change the effective access; omitting --policy alone does not prove that the restrictive fallback is active.

Sources: network-policy tutorial, workload images, and fallback-policy selection.

Make one request, then grant a read

Inside the sandbox, try:

curl -sS --max-time 10 https://api.github.com/zen

With no matching permission, the connection should fail. On the host, find the denial:

openshell logs policy-lab --since 5m --source sandbox

Now grant curl inspected, read-only API access from the host:

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

Each part matters: api.github.com is the destination; 443 is the port; read-only permits GET, HEAD, and OPTIONS; rest enables HTTP request inspection; and enforce blocks disallowed requests. Audit mode would record a request-rule violation while allowing it.

Back inside the sandbox, retry the GET, then try a POST to the same endpoint:

curl -sS --max-time 10 https://api.github.com/zen
curl -sS --max-time 10 -X POST https://api.github.com/zen

The GET should return an aphorism. The POST should return an OpenShell policy_denied response. Check the logs to identify who rejected it; a GitHub error is not evidence that OpenShell enforced the restriction.

Sources: NVIDIA’s GET/POST demonstration and network-rule semantics.

ILLUSTRATIVE RESULTS / SAME HOST, DIFFERENT REQUEST

$ curl https://api.github.com/zen
GET allowedThe service can answer the request.

$ curl -X POST https://api.github.com/zen
POST denied: policy_deniedThe supervisor rejects the operation before forwarding it.

$ curl https://unapproved.example/
Connection deniedThere is no rule for this destination.

The method preset describes the request’s shape. It cannot guarantee that a poorly designed upstream GET has no side effects, nor prevent sensitive data from being sent to an approved service. For a production API, restrict paths and use a server-side identity whose permissions fit the task.

Verify the loaded policy and remove access

Inspect the revision and the effective policy after the change. Confirm the latest intended revision is loaded, then repeat the allowed and denied requests.

openshell policy list policy-lab
openshell policy get policy-lab --full

openshell policy update policy-lab \
  --remove-rule github_readonly --wait

Removal is worth testing too. Retry the GET after the revision loads; it should be denied again if no other effective rule grants access. Save any files you need before deleting the lab:

openshell sandbox delete policy-lab

Source: policy verification and lifecycle.

Give an agent files it can use

An empty sandbox tells you little about actual engineering work. The next useful experiment is a copied project or incident bundle, with a known directory and a clear output to retrieve.

For a hypothetical investigation, prepare an incident-fixture directory containing sanitized application logs, a configuration snapshot, and a short task description. Remove tokens and customer information before transfer. Uploading is a copy operation; it does not make the sandbox a secret-aware mirror of your workstation.

openshell sandbox upload my-agent ./incident-fixture

Without a destination, the CLI discovers the sandbox working directory and preserves the uploaded directory’s basename. Ask the agent to list that directory and confirm the intended files arrived. Uploads in a Git repository normally respect Git ignore rules, but those rules are not a complete secret scanner.

Ask for a report named incident-fixture/analysis.md, then copy it back from the host while the sandbox is available:

openshell sandbox download \
  my-agent incident-fixture/analysis.md ./analysis.md

Review the report or patch on the host before applying it. The useful first workflow keeps investigation inside the sandbox and makes promotion of the result a separate step.

Source: file-transfer behavior.

For a worker that reads its input immediately at startup, use a scratch sandbox, transfer the input, and launch the worker through sandbox exec. This avoids a race between the process starting and the files arriving. A running interactive agent can instead wait while you upload its input.

Keep real credentials outside the workload

Provider-backed access solves a specific problem: the agent can authenticate to a service without receiving the real credential as ordinary readable data. It sees a placeholder, and the supervisor substitutes the credential only where the profile or explicit binding permits it.

Network permission and credential permission are separate. Allowing a destination does not automatically authorize sending a provider key there. If a request reports a credential-endpoint mismatch, repair the binding rather than opening more network access.

This protection applies to credentials managed through that path. A real token in a file, an agent config, or sandbox create --env is still data the workload can read. Also, keeping a key outside the agent does not make every authenticated request harmless; the remote identity still needs appropriately narrow permissions.

Sources: provider profiles and plain environment variables.

For the incident-bundle example, the model key can stay in a provider. A future observability connection should use a separate read-scoped identity. Giving the model service access and giving a metrics API access are different capabilities, even if both travel over HTTPS.

Let the agent ask for more access

Eventually a legitimate request will hit a restriction. OpenShell can draft a narrow network-rule proposal from a denied connection. Its optional policy advisor also lets agents submit proposals. The advisor is off by default, and proposals normally wait for manual review.

openshell rule get my-agent --status pending
openshell rule approve my-agent --chunk-id <proposal-id>
openshell rule reject my-agent --chunk-id <proposal-id> \
  --reason "This investigation uses the uploaded incident bundle."

Replace the ID with the one shown in the pending proposal. Read the actual destination, calling executable, method, path, and risk findings before approving.

For the hypothetical investigation, a request to an unrelated upload service should remain denied. A request to the approved metrics endpoint might be appropriate, but only if the task needs current metrics and the data is suitable for that service. The fact that an agent asked for access is a starting point for review.

Automatic approval changes this decision. NVIDIA documents that a new public host without an applicable provider credential may pass the risk checks and be approved automatically. Manual review is the clearer starting point when your goal is to understand every destination the task uses.

Source: Policy Advisor, approval modes, and proposal risk checks.

What formal verification proves

OpenShell’s policy prover checks modeled permissions. A boundary check asks whether a candidate policy grants more than a maximum policy you supply. The proposal risk check asks a different question about newly introduced access.

openshell sandbox get my-agent --policy-only > candidate.yaml
openshell-prover check candidate.yaml --boundary boundary.yaml

Create and review boundary.yaml first; it must describe the maximum access you intend. The prover can return a counterexample when the candidate exceeds it. Treat unsupported or inconclusive results as a check that did not pass.

The current boundary model covers filesystem, process, Landlock, L4 network, and REST features, with documented limits. Other protocols can return unsupported. A passing check does not verify the correctness of an agent’s plan, the absence of software vulnerabilities, or that a running sandbox enforces the intended policy.

Source: Policy Prover and coverage limits.

Use OpenShell for a real SRE task

Consider a hypothetical checkout service whose errors increased after a deployment. The first task is to compare the supplied logs and configuration, identify plausible causes, and propose the next diagnostic. It does not require the agent to restart the service.

Begin with the sanitized bundle and a model provider. Give the agent a concrete output contract:

Read incident-fixture/ and write incident-fixture/analysis.md.
Separate observations from hypotheses.
Cite the file and timestamp for each important observation.
Identify missing evidence and the next diagnostic that could resolve it.
Do not change infrastructure or contact additional services.

The prompt describes the job; the environment should make its limits true. An agent that cannot reach the cluster API cannot quietly convert this investigation into a production restart. Its report can still be wrong, so the reviewer checks whether the cited evidence supports the proposed cause.

After that workflow works, add a read-scoped observability API if fresh data changes the investigation. Test that the necessary read succeeds and that an attempted write is denied. Keep the remote account restricted as well, so a permissive local rule cannot silently grant administrative capability.

The progression follows a practical operating principle: an agent’s intelligence does not establish its authority. Its useful scope comes from the work it must perform, the evidence needed to check that work, and the consequences of a mistake.

OpenShell handles important parts of the access problem. Your service workflow still owns approvals for consequential actions, stale plans, retries, and recovery. If containment interrupts a write, establish what the destination accepted before resuming. Our OpenShell recovery guide develops that problem further.

Operate OpenShell beyond your laptop

A shared gateway becomes part of the infrastructure supporting your agents. It needs identity controls, persistent configuration, image management, and monitoring. Start with the workstation lab so you understand the expected traffic before moving it into a cluster.

Kubernetes must enforce the outer fence

NVIDIA’s current Kubernetes setup requires Kubernetes 1.29+, Helm 3.x, and the Agent Sandbox controller and CRDs. The OpenShell chart uses that controller to provision workloads; it does not install the controller for you.

The consequential prerequisite is a CNI that enforces ingress and egress NetworkPolicy in every sandbox namespace. Kubernetes can accept a policy object even when the network implementation does not enforce it. In that case, the workload may reach the network directly instead of through the supervisor.

For a cluster evaluation, verify that direct workload egress fails while the mediated approved request succeeds. A running pod and an accepted manifest cannot establish that distinction.

Source: Kubernetes installation and CNI requirements. Follow the complete release-specific setup for certificates, RBAC, and registration.

Monitor the work and its infrastructure

Gateway metrics describe the system supporting execution, while a synthetic task tells you whether an agent can perform the work you need. A useful check starts a sandbox, reads a fixture, contacts the approved model service, and returns a verifiable artifact. Use a fixture that contains no private data.

NVIDIA exposes Prometheus metrics for gateway requests, readiness, relay capacity, and other components. Scrape each replica for replica-local capacity. Its metrics endpoint uses unauthenticated plaintext HTTP, so restrict reachability to the monitoring system.

Source: gateway metrics.

Collect both policy logs and workload output. The gateway holds a bounded in-memory log buffer, and the push path can drop events. An agent’s stdout is also a different source from the supervisor’s policy decisions. Preserve both if the records will support incident reconstruction.

Source: log collection, retention, and loss awareness.

For a rollout, measure completed investigations, useful denied operations, accidental blocks, and human review time. These are proposed workflow measures, not native OpenShell metric names. They tell you whether the permissions support the task instead of merely producing a large count of denials.

Troubleshoot the layer that actually failed

A failed agent request can mean the program is missing, the rule is wrong, the credential is unavailable, or the destination rejected the request. Broadening access before identifying the layer makes the next failure harder to interpret.

openshell status
openshell sandbox get my-agent
openshell policy list my-agent
openshell policy get my-agent --full
openshell logs my-agent --since 10m --source sandbox

Pay attention to interpreters. A Python script’s network activity may be attributed to the real Python executable, and a Node-based tool may need the Node path used by its image. Use the denial log rather than guessing from the command’s friendly name.

Network updates can reload in a running sandbox and close existing connections. Filesystem and process restrictions are startup controls. A successful policy submission also needs a loaded-revision check and a traffic test.

Sources: policy troubleshooting, binary matching, endpoint diagnostics, and static and dynamic controls.

Common questions about NVIDIA OpenShell

References for these answers: sandboxes and optional GPU resources, inference routing, request protocols and MCP limitations, and prover coverage.

Your first useful OpenShell session

Download the session checklist

Start with a copied incident bundle, one model provider, and a report you can retrieve. Complete the direct GET/POST lab as well, so you know what a real policy denial looks like. Those two experiments establish a useful baseline: the agent can do bounded work, and you can explain what the runtime prevented.

Expand from there when a specific task needs another capability. If the report needs fresh metrics, grant the relevant read and test it. If the task needs a production change, bring it into a workflow that can check the destination and recover when the result is uncertain. You now have a concrete way to decide which access belongs in the next sandbox.

Sources and version notes

This guide was prepared against NVIDIA’s public documentation on October 13, 2026. Most reviewed pages identify the latest release as v0.1.4; the fallback-policy page returned v0.1.3. The creation-time upload discrepancy is called out where it affects the workflow. Check your installed release and command help before relying on a newer option.

The incident investigation, Dockerfile adaptation, request explorer, and workflow measures are constructed teaching examples. No production incident, firsthand OpenShell deployment, benchmark result, or completed local command execution is claimed.

1. NVIDIA/OpenShell repository and Apache 2.0 license.
2. NVIDIA runtime introduction and setup video.
3. Architecture and enforcement boundaries.
4. Installation and support matrix.
5. First-agent walkthrough.
6. First network policy and request-rule semantics.
7. Default policy and policy management.
8. Provider profiles and Pi tutorial.
9. Sandbox lifecycle, uploads, and downloads.
10. Policy Advisor and Policy Prover.
11. Kubernetes setup.
12. Logs and metrics.
13. Security best practices.
14. Inference routing.