AI coding and agent tools run locally with access to your files, credentials, and network — running one directly on your system means it can reach all of that, creating real security exposure.
NVIDIA OpenShell solves this problem. It is an open-source sandbox runtime that wraps an agent in kernel-level isolation with declarative YAML policies. OpenShell controls what the agent can read on disk, which network endpoints it can reach, and what privileges it has—without disabling the capabilities that make the agent useful.
This playbook uses Pi, a terminal coding agent, as its reference agent, backed by a model served locally with vLLM on your own hardware. You get the full power of a local AI agent with local model serving, while enforcing explicit controls over filesystem access, network egress, and credential handling.
Get started with additional reference examples using NVIDIA NemoClaw, including express installers for DGX Spark and DGX Station.
Notice & Disclaimers
Quick Start Safety Check
Use a clean environment only. Run this playbook on a fresh device or VM with no personal data, confidential information, or sensitive credentials. Think of it like a sandbox—keep it isolated.
By installing this playbook, you're taking responsibility for all third-party components, including reviewing their licenses, terms, and security posture. Read and accept before you install or use.
What You're Getting
The playbook showcases experimental AI agent capabilities. Even with cutting-edge open-source tools like OpenShell in your toolkit, you need to layer in proper security measures for your specific threat model.
Key Risks with AI Agents
Be mindful of these risks with AI agents:
Data leakage – Any materials the agent accesses could be exposed, leaked, or stolen.
Malicious code execution – The agent or its connected tools could expose your system to malicious code or cyber-attacks.
Unintended actions – The agent might modify or delete files, send messages, or access services without explicit approval.
Prompt injection & manipulation – External inputs or connected content could hijack the agent's behavior in unexpected ways.
Security Best Practices
No system is perfect, but these practices help keep your information and systems safe:
Isolate your environment – Run on a clean PC or isolated virtual machine. Only provision the specific data you want the agent to access.
Never use real accounts – Don't connect personal, confidential, or production accounts. Create dedicated test accounts with minimal permissions.
Vet your skills/plugins – Only enable skills from trusted sources that have been vetted by the community.
Lock down access – If your agent exposes a web UI or messaging channel (via openshell service expose or similar), ensure it isn't accessible over the network without proper authentication.
Restrict network access – Where feasible, limit the agent's internet connectivity.
Clean up after yourself – When you're done, delete the sandbox and provider credentials you created, and revoke any API keys or account access you granted.
What you'll accomplish
You will install the OpenShell CLI (openshell), deploy a gateway on your hardware platform, build an agent image containing Pi, and launch it inside a sandbox with a custom provider profile pointing at a model served locally with vLLM. The sandbox enforces filesystem, network, and process isolation by default — you grant the agent exactly the network endpoints and binaries it needs, nothing more, and no external API keys are required.
Popular use cases
Secure agent experimentation: Test Pi's tool integrations and skills without exposing your main filesystem or credentials to the agent.
Private enterprise development: Route all inference to a local model on your hardware. No data leaves the machine unless you explicitly allow it in the policy.
Auditable agent access: Version-control the policy YAML alongside your project. Review exactly what the agent can reach before granting access.
Iterative policy tuning: Monitor denied connections in real time with openshell term, then hot-reload updated policies without recreating the sandbox.
What to know before starting
Required:
Comfort with the Linux terminal and SSH
Basic understanding of Docker (OpenShell runs your gateway and sandboxes as containers)
Familiarity with local LLM serving (this playbook uses vLLM)
Optional:
Awareness of the security model: OpenShell reduces risk through isolation but cannot eliminate all risk. Review the OpenShell documentation.
Supported hardware platforms
Use the matrix below to confirm your hardware platform, OS, memory, and whether multi-node applies. The same OpenShell + Pi workflow applies across supported hardware platforms. Set up the inference backend with the vLLM playbook for a single device or the vLLM cluster playbook for a cluster; model recommendations differ by platform.
Hardware platform
OS
Memory
Multi-node capable hardware
DGX Spark
DGX OS (Linux)
128 GB Unified Memory
—
DGX Station
DGX OS (Linux)
Large HBM + Grace DRAM
—
NOTE
Only platforms listed in the Supported hardware platforms table above are covered by this playbook.
Prerequisites
Hardware requirements
Supported hardware platform — see Supported hardware platforms matrix above
Docker Desktop or Docker Engine running: docker info
Python 3.12 or later: python3 --version
NVIDIA Container Toolkit configured for Docker
Network access to download packages from PyPI / GitHub, container images, and model weights from Hugging Face
A Hugging Face token when the chosen model requires authentication
Time & risk
Estimated time: 30 MIN (plus model download time, which depends on model size and network speed)
Risk level: Medium
OpenShell sandboxes enforce kernel-level isolation, significantly reducing the risk compared to running an agent directly on the host.
The sandbox default policy denies all outbound traffic not explicitly allowed. Misconfigured policies may block legitimate agent traffic; use openshell logs to diagnose.
Large model downloads may fail on unstable networks.
Rollback: Delete the sandbox with openshell sandbox delete <sandbox-name>, stop the gateway, and remove the vLLM container if you started one. See cleanup in the Instructions tab.
Last Updated: 10/19/2026
Set up the inference backend from the vLLM playbook (single device) or the vLLM cluster playbook (cluster)
Rewritten for OpenShell 0.1.0: reference agent changed from OpenClaw to Pi, custom provider profiles replace managed inference routing, and the sandbox deploy flow builds a bring-your-own agent image instead of using a prebuilt community sandbox
