By AIO Sandbox team
Beyond SDKs: Securing the AIO Sandbox with NVIDIA OpenShell
This is the third part of a series of posts diving into AIO Sandbox that provides an isolated, programmable environment where agents can safely execute. Please see previous posts here: Part 1 & Part 2.
As AI agents become more capable, the need for secure, tool-rich execution environments is growing rapidly. Agents increasingly require access to browsers, shells, filesystems, development tools, and external services—but granting those capabilities directly on a host system creates obvious operational and security risks.
This is where sandbox runtimes become essential. Recently, we explored integrating AIO Sandbox with NVIDIA OpenShell, and found that the two systems complement each other extremely well. By leveraging OpenShell’s Bring-Your-Own-Container (BYOC) model, we were able to run AIO Sandbox as the underlying workspace environment while benefiting from OpenShell’s policy controls, isolation model, and gateway architecture.
The result is a powerful combination:
AIO Sandbox provides rich built-in agent capabilities such as browser automation, shell access, file operations, VS Code Server, and MCP integration.
OpenShell provides the secure outer runtime boundary: sandbox lifecycle management, policy enforcement, controlled networking, and operational governance.
This post walks through the architecture, why the combination makes sense, and how BYOC enables a clean integration path.
Why Combine AIO Sandbox and OpenShell?
Each platform solves a different part of the agent infrastructure stack.
AIO Sandbox: Rich Agent Workspace
AIO Sandbox is designed as an all-in-one environment for agents. The sandboxing primitives are exposed as a library with multi-language bindings, so it can be embedded directly into your agent framework.
Typically, an agent might need a browser to fetch data, a Python interpreter to analyze it, and a filesystem to store the results. Managing these as separate services introduces latency and synchronization complexity. AIO sandbox consolidates these requirements into a single containerized environment. It packages commonly needed capabilities into a single containerized workspace:
Computer Interaction: A Chromium browser controllable via the Chrome DevTools Protocol (CDP), with documented support for Playwright.
Code Execution: Pre-configured runtimes for Python and Node.js.
MCP Compatibility: AIO Sandbox exports its services as tools that an LLM can call directly via a standardized protocol.
Standard Tooling: A bash terminal and a file system accessible across modules.
Development Interfaces: Integrated VSCode Server and Jupyter Notebook instances for monitoring and debugging.
This makes it ideal as the inner execution environment where the agent actually performs work.
OpenShell: Secure Runtime Envelope
OpenShell is a Kubernetes-based sandbox platform. Each sandbox is a K8s pod inside a K3s cluster inside Docker container. It is built to manage multiple sandboxes with centralized policy (using OPA policy engine). It also provides support for injecting credentials through a network proxy in order to keep real credentials away from the agent via a proxy. OpenShell focuses on secure agent execution and governance:
Isolated sandbox runtime
Gateway-managed access patterns
Declarative policy controls
Network and filesystem restrictions
Operational auditability
BYOC custom runtime support
This makes OpenShell ideal as the outer control plane around a capable agent workspace.
The Architecture
The integration model is straightforward:
User / API Request
|
v
NVIDIA OpenShell Gateway
|
v
OpenShell Sandbox (BYOC)
|
+--> AIO Sandbox Runtime
- Browser
- Shell
- File APIs
- VS Code
- MCP Tools
Instead of replacing AIO Sandbox, OpenShell hosts it securely.
This is important because it preserves the strengths of both systems:
AIO remains the productivity layer.
OpenShell remains the security and governance layer.
What This Means for the Future
As agent systems mature, we are likely to see a layered architecture emerge:
Layer 1: Secure Runtime Envelope: Sandboxing, policy, networking, credentials, governance
Layer 2: Capability Workspace: Browser, shell, files, IDE, tools, APIs
Layer 3: Agent Intelligence: Reasoning model, planning, tool use, memory
The AIO Sandbox + OpenShell combination is an early example of this layered model in practice.
Why Bring-Your-Own-Container (BYOC) Matters
Without BYOC support, integrating specialized agent runtimes into secure sandbox systems often requires invasive rework. OpenShell’s BYOC model removes that friction. It allows you to:
Package your existing runtime as a container
Bring your own dependencies and startup model
Retain existing APIs and workflows
Add OpenShell security controls around it
In our case, we already had AIO Sandbox working independently. BYOC meant we could reuse that investment rather than rebuild functionality natively for OpenShell.
Requirements for Custom Images
While OpenShell supports almost any Linux-based image, there are a few technical requirements:
Base Requirements: The image must contain glibc, /proc filesystem support, and the iproute2 package (for network namespace management).
Use a standard Linux base image
Add sandbox user to the AIO Docker Image
User/Group Handling: For custom images, you still must manually create a sandbox user and group in the Dockerfile, like this:
# You must add this to your custom Dockerfile
RUN groupadd -g 1000 sandbox && \
useradd -m -u 1000 -g sandbox sandbox
If you don't do this, the supervisor will refuse to start the agent because it doesn't have a safe, non-root user to "drop" down to after it finishes setting up the secure environment.
docker build -t ghcr.io/deepak-vij/sandbox-openshell:latest .
docker push ghcr.io/deepak-vij/sandbox-openshell:latest
FROM ghcr.io/agent-infra/sandbox:latest
RUN groupadd -r sandbox && \
useradd -r -g sandbox -m -d /home/sandbox -s /bin/bash sandbox && \
mkdir -p /workspace && \
chown -R sandbox:sandbox /home/sandbox /workspace
Create OpenShell Sandbox
The following CLI command creates a sandbox from existing docker image (AIO Sandbox in our case). The very first time, it also boots up a K3S cluster inside a docker container. Within the K3S cluster, it automatically creates an OpenShell gateway (with mTLS enabled).
# Running your own app
# Pass your start command explicitly — use -- <command> on the CLI.
# The image's CMD/ENTRYPOINT is replaced by the sandbox supervisor at runtime.
openshell sandbox create --from ghcr.io/deepak-vij/sandbox-openshell:latest \
--forward 18080 \
-- /usr/local/bin/python-server --host 0.0.0.0 --port 8091 --ws-ping-interval 30 --mcp-config /opt/gem/mcp-hub.json --filter-mcp-servers sandbox --workspace /home/gem
openshell forward start 8091 exceeding-reindeer
Practical Benefits of the Integration
Rich Agent Capabilities Inside a Controlled Boundary
Agents can use browsers, terminals, and tools—but only inside the sandbox.
This dramatically reduces host risk while preserving capability.
Operational Simplicity
Rather than assembling separate browser pods, shell workers, file services, and IDE containers, AIO Sandbox bundles them into one runtime.
OpenShell then governs it as a single managed workload.
Better Security Posture
Instead of exposing powerful tools directly, OpenShell can apply policies such as:
restricted egress networking
ephemeral lifecycle
credential boundaries
isolated filesystem mounts
controlled tool invocation paths
Faster Experimentation
Because AIO Sandbox already includes a rich environment, new agent use cases can be tested quickly without building custom images for every scenario.
Real-Life Example Use Cases
Earlier, we briefly mentioned the 3-layer architecture whereby:
OpenShell contributes: capabilities such as secret injection; secure identity; governed outbound access; sandbox lifecycle; policy control.
AIO Sandbox contributes: capabilities such as browser-use/CUA; shell; files etc. More importantly, AIO Sandbox provides the integrated workspace primitives that allow agents to perform multi-step workflows inside a single runtime.
Agent contributes: capabilities such as reasoning; planning; execution.
With that as the background, the following are a set of possible real-life example use cases.
Autonomous Security Patch Agent – Patch-and-PR Agent
Imagine an enterprise wants an agent that automatically patches an internal service when a new CVE is published. This typically requires:
access to internal Git repo
ability to browse vulnerability reports
edit code
run tests
build artifacts
create pull requests
use API keys securely
operate inside controlled boundaries
Most traditional sandboxes can run code. But they do not provide a full secure workspace + browser + governed secrets + developer environment in one flow.
This demonstrates a broader shift in agent infrastructure: from isolated code runners to governed autonomous workspaces. Instead of merely executing commands in isolation, the combined AIO Sandbox + OpenShell stack can run a full enterprise remediation workflow. OpenShell securely provisions short-lived credentials at runtime, launches an AIO workspace container, and applies outbound network policy.
Inside the workspace, the agent researches a newly disclosed vulnerability, updates the affected repository, runs tests, validates behavior in a browser session, and opens a pull request to the approved internal Git host. When the task completes, the sandbox is destroyed and credentials are revoked.
Other Possible Use Case Scenarios
Incident Response Agent – Investigates production alerts inside a governed sandbox, analyzes logs and dashboards, runs diagnostics, and prepares remediation steps or pull requests while keeping credentials and network access tightly controlled.
Browser QA Agent – Launches real browser sessions to validate user flows, detect UI regressions, capture screenshots, and file reproducible bug reports from an isolated workspace environment.
Autonomous Data Ops Agent – Executes data pipelines, validates schemas, runs transformations, investigates failed jobs, and generates reports or fixes in an ephemeral sandbox with secure access to approved data sources.
Key Observations & Final Thoughts
After integrating the two systems, one architectural principle became clear:
The best agent platforms separate capability surfaces from trust boundaries.
AIO Sandbox excels at capability surfaces.
OpenShell excels at trust boundaries.
Combining them yields a much stronger system than forcing either platform to do both jobs alone.
In Conclusion
OpenShell’s Bring-Your-Own-Container model provides a practical path to secure it without redesigning everything. For us, integrating AIO Sandbox with OpenShell demonstrated how modern agent infrastructure can be both:
high capability
operationally safe
And that balance is exactly what production-grade AI agents will need.
Top comments (0)