Running Agents in an Isolated and Secure Environment with OpenShell

NVIDIA recently released OpenShell, its agent runtime.

It is a manager that starts the agent, enforces its boundaries, monitors it, and shuts it down, with security built in.

I built an agent with OpenShell that reads logs and errors from several of my Google Cloud projects, while OpenShell manages its permissions.

Some interesting principles in OpenShell:

• It separates the agent from its security environment. You can replace the agent, model, or sandbox technology while managing permissions and policy from the same place.
• It does not try to make the agent careful through prompt instructions. It assumes the agent is exposed to risks and may make mistakes, so it enforces restrictions around it.

To understand the benefits and importance of OpenShell, I went back to the basics of what an agent is, and how and where it runs.

I also built an interactive OpenShell guide where you can click through the stack, test deny-by-default policy, and see how inference.local keeps model credentials outside the sandbox.

What is an agent?

An agent is software that performs actions: it runs commands on a computer, edits files, calls tools and services, and more.

It may have access to secret information such as environment variables, passwords, internal tools, and other credentials.

The agent is exposed to prompt injection and other security risks that can cause damage. It can also perform actions we did not intend and harm our environment.

One way to reduce the risk is a sandbox: the concept of an isolated and restricted execution environment.

The sandbox defines the security boundary and the agent’s available area of action. It creates an isolated and restricted environment for running untrusted code.

A sandbox can be a virtual machine, a container, and more.

Containers and sandboxes

A container is one of the technologies that can be used to implement a sandbox.

At its core, a container is a way to run software inside a separate and restricted environment, together with the files and dependencies it needs, and run it consistently across different computers and servers.

Containers are common for isolation because they are fast, lightweight, and portable. But their isolation is not absolute because they share the host’s kernel.

When would we want to use this?

When an agent operates in production, in an environment with secret or sensitive information, or any time we want to increase the security around it.

The components involved in running an agent

The agent itself

• Model - the brain that thinks and makes decisions.
• Harness - the software the agent lives inside. It includes the tools, memory, skills, and the rest of the surrounding system. Examples include Claude Code, Codex, OpenClaw, OpenCode, and others.

The execution and deployment environment

• Runtime - in OpenShell’s case, this is also the security and management layer.
• Driver - the technology that runs the sandbox.
• Host - the physical or virtual computer where everything runs.

The agent can stay the same while moving between Docker, MicroVMs, and different computers.

Every agent needs some kind of execution environment, but it does not necessarily need a dedicated agent runtime like OpenShell.

A basic execution environment runs the agent and gives the software what it needs to work. An agent runtime like OpenShell can also manage permissions, monitoring, and lifecycle.

The word runtime is used for several different kinds of execution environments, including the Node.js runtime, Bun, a container runtime, and a model runtime.

Why OpenShell?

A sandbox provides isolation, but the level of isolation depends on the technology and its configuration.

Depending on that configuration, the agent may still be able to access the internet, mounted files, and credentials placed inside it.

A container, for example, provides basic isolation but is not necessarily a secure sandbox by itself.

OpenShell adds a dedicated management and security layer:

• Policy and permission control.
• Credential management.
• Monitoring.
• Controlled communication with the outside environment.

It sits between the agent and the sandbox and manages what crosses the boundary between them.

It creates and manages sandboxes, distributes and enforces policy, controls communication with external services, routes requests to models, and records the agent’s activity.

OpenShell includes:

• Sandbox supervisor: Creates the isolated box and enforces its boundaries, including which files and processes are allowed inside. This is what starts the agent with its restrictions.
• Policy engine: The policy is written in a YAML file. The engine reads it and turns it into allow or deny decisions for files, tools, processes, and more.
• Gateway: The door to the outside environment. It controls outbound network access, holds credentials and API keys, and routes model calls.
• Observability and CLI: Monitors the agent’s activity and extracts logs that show what the agent tried to do.

OpenShell uses a compute driver to create the sandbox.

You can run OpenShell on a laptop, a physical server, a virtual machine, or in the cloud.

Policy examples

• Keys stay in the gateway instead of inside the container.
• Write access is allowed in a specific location and denied outside it.
• The agent does not get direct access to passwords and secrets such as cloud login credentials.

Some credentials may still be configured to enter the sandbox. This depends on the provider and the policy.

How the agent calls a model without an API key

The agent calls an internal address that exists only inside the sandbox, for example inference.local, with the prompt it wants to send.

The request reaches the gateway outside the sandbox.

The gateway adds the key and forwards the request to the model.

The model returns its response to the agent, without the agent ever getting direct access to the API key.

The value beyond container isolation

A container is isolated from the host, but it may still have open internet access, access to keys placed inside it, and access to every file mounted into it.

OpenShell adds deny-by-default policy and additional protections.

Even if the agent is compromised, OpenShell limits the information and systems it can reach according to the defined policy.

The agent I built

I built an agent that receives questions in natural language, uses the Nemotron model through OpenRouter, and reads information from five GCP projects.

It can:

• Read logs from Cloud Logging.
• Read metrics from Cloud Monitoring.
• Run BigQuery queries.
• Read metadata about Cloud SQL instances and databases.

The model chooses which tool to use, but only four defined functions are available to it.

How it works

• It calls a local gateway address where the API key is stored.
• The gateway adds the key to the request and sends it to the model.
• The key stays in the gateway.
• I can remove openrouter.ai from the policy. There is no need to upload openrouter.env into the sandbox.

How it is restricted

It cannot:

• Access any internet destination outside the five allowed hosts.
• Write to central parts of the filesystem.
• Directly access files on my personal computer that were not uploaded or mounted into the sandbox.
• Connect directly to a Cloud SQL database through Postgres.
• Use another Google API that was not defined in the policy.

The steps for building an agent with OpenShell

1. Build the agent normally, or use Claude Code, Hermes, or whichever agent you prefer.
2. Install the OpenShell CLI and Gateway.
3. Make sure a compute driver such as Docker, Podman, or a MicroVM is available.
4. Configure inference and policy.
5. Ask OpenShell to create a sandbox and run the agent inside it.

I already have more projects where I want to add OpenShell.

Beyond OpenShell, NVIDIA has many other interesting products, including the Nemotron model family, the NeMo Agent Toolkit, NIM for packaging models as services, and NemoClaw, which is a ready-made package built on top of OpenShell.

The interactive guide includes the full mental model, a policy simulator, the inference routing flow, and a tested local setup.