Run AI in a sandbox with access you control
Run AI agents in a sandbox with explicit file and network access. NVIDIA OpenShell enforces policies outside the agent, routes credentials to approved endpoints, and lets you review new network access before allowing it.
Requirements
- Docker Desktop / Docker Engine >= 28.0
- Git
- OPENROUTER_API_KEY
Overview
What you get
- Sandboxed execution with filesystem, network and process policies.
- Provider credentials delivered only to endpoints authorized by their configuration.
- Network access proposals you can review, approve or reject while the sandbox runs.
Good fit
- Running coding agents with explicit access to project files and external services.
- Keeping access policies in version control and inspecting denied requests.
Tutorial
Understand what OpenShell controls
Coding agents need to read files, run commands and reach external services. OpenShell runs the agent in a separate sandbox and enforces access policies through the runtime.
| What you want to control | How OpenShell handles it |
|---|---|
| Files the agent can read or change | Filesystem policies define allowed paths inside the sandbox |
| Services the agent can reach | Network rules scope destinations, calling programs and permitted requests |
| Use of model API keys | Providers store credentials and use them at authorized endpoints |
You will run OpenCode with OpenRouter, ask it to document a small project, then learn how to handle blocked network requests. Filesystem and process policies are set when the sandbox is created. Network rules can change while it runs.
Start your first AI sandbox
Prepare the local environment
This tutorial uses OpenShell 0.1.5 with Docker. Prepare Git, a running Docker Desktop or Docker Engine 28.0+, and an OpenRouter API key.
Supported platforms include Linux x86_64 / arm64 and Apple Silicon Macs. Windows through WSL 2 with Docker Desktop is experimental. Linux sandboxes need Landlock ABI 3 enabled (normally Linux 6.2+) and the required seccomp capabilities. See the support matrix for the complete requirements.
-
Install from a host terminal, then check the connection:
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/v0.1.5/install.sh | OPENSHELL_VERSION=v0.1.5 sh openshell statusThe installer sets up the CLI, policy prover and local gateway.
statusshould return the gateway status. If it cannot connect, check the gateway service using the installation guide. -
Configure the model service. OpenRouter supplies the model API in this example. A Provider is OpenShell’s object for storing its credentials and access configuration. Replace the API key, then run these commands in the same host terminal:
export OPENROUTER_API_KEY='REPLACE_WITH_YOUR_OPENROUTER_API_KEY' # Import the profile for OpenCode access to OpenRouter openshell profile import \ --url https://raw.githubusercontent.com/NVIDIA/OpenShell/v0.1.5/providers/openrouter.yaml # Read the API key from this environment and create a provider named openrouter openshell provider create --name openrouter --type openrouter --from-existingThis profile lets
/usr/local/bin/opencodein the image reachopenrouter.ai. Once provider creation succeeds, attach it to the sandbox by its name,openrouter.
Launch OpenCode
Run this in host terminal A:
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 the image and model route in the official first-agent guide. You should see the OpenCode interface. Keep this terminal open for the tasks below. The official example uses a free OpenRouter model; opencode models openrouter inside the image lists available models.
--from selects an image containing the agent. The default Ubuntu image contains the base system; use the OpenCode image above to run OpenCode.
Give the agent a small task
Upload a sample project
-
Open a second host terminal, B, and create a separate project:
mkdir greeting-demo cd greeting-demo git init cat > main.py <<'PY' def greet(name): return f"Hello, {name}!" if __name__ == "__main__": print(greet("Ada")) PY cd .. -
From terminal B, upload the directory to the running sandbox:
openshell sandbox upload my-agent ./greeting-demoWithout an explicit destination, uploads go into the sandbox’s working directory and retain the directory name,
greeting-demo. Starting the sandbox before uploading also lets you finish the transfer before asking the agent to read the files.
Write and retrieve the README
-
Return to OpenCode in terminal A and send this task. This is an editorial exercise written for this tutorial:
Read greeting-demo/main.py under the current working directory. Write greeting-demo/README.md describing the program, the function's input and output, how to run it, and the expected output. Base the explanation on the source. Do not install dependencies or change main.py. List the files you added when finished. -
When the agent finishes, retrieve and read the file from host terminal B:
openshell sandbox download my-agent greeting-demo/README.md ./greeting-demo/README.md cat ./greeting-demo/README.mdThe README should explain that
greet(name)returns a greeting and that running the program printsHello, Ada!. Check the explanation against the source to judge the result.
Grant network access when needed
Later tasks, such as reading documentation or downloading dependencies, may encounter a blocked destination. OpenShell records the denial and drafts a proposed access rule.
-
From host terminal B, inspect recent logs and pending proposals:
openshell logs my-agent --since 5m --source sandbox openshell rule get my-agent --status pendingLook at the destination host, port and calling program. The README task does not require network access, so you can continue to the next section if the list is empty.
-
For a proposal that matches the task, replace
<chunk-id>with its actual ID and approve it:openshell rule approve my-agent --chunk-id <chunk-id>Reject unnecessary access with a reason:
openshell rule reject my-agent --chunk-id <chunk-id> --reason "Not needed for this task" -
After approval, return to OpenCode and ask it to retry the blocked operation. Network changes take effect without restarting the sandbox.
Base each decision on the task and the specific access it needs.
Narrow access to read-only requests
You can distinguish reads from writes within an allowed destination. Use a separate curl sandbox to observe the difference, following the rule syntax in the official network-policy tutorial.
Prepare an image with curl
Run these commands in host terminal B:
mkdir openshell-policy-demo
cd openshell-policy-demo
cat > Dockerfile <<'DOCKER'
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 mkdir -p /workspace && chown 1000:1000 /workspace
USER 1000:1000
WORKDIR /workspace
DOCKER
docker build -t openshell-curl-demo:local .
openshell sandbox create --name api-demo --from openshell-curl-demo:local --no-auto-providers
Docker installs curl while building the image. The sandbox then starts with the tools already available. Terminal B now contains the api-demo sandbox shell. Keep it open.
Observe a denial, then allow reads
-
From the sandbox shell in terminal B, request the GitHub API:
curl -sS https://api.github.com/zenUnder a fresh local gateway’s default network policy, this destination has not been allowed and the request should be blocked.
-
Open another host terminal, C, and allow only
/usr/bin/curlto read from this service:openshell policy update api-demo \ --rule-name github_api \ --binary /usr/bin/curl \ --add-endpoint api.github.com:443:read-only:rest:enforce \ --waitread-onlyallows GET, HEAD and OPTIONS.restinspects HTTP requests, andenforceblocks requests outside the rule. This command changes network rules only. -
Return to the sandbox shell in terminal B and compare GET and POST to the same address:
curl -sS https://api.github.com/zen curl -sS -X POST https://api.github.com/zenGET should return a line of text. OpenShell should deny POST with a response containing
policy_denied. This demonstrates separate control over connecting to a service and making write requests. -
From host terminal C, inspect the policy and denial records:
openshell policy get api-demo --full openshell logs api-demo --since 5m --source sandboxThe logs should identify the program, destination and denied method. If the first request already succeeded, inspect the full policy for existing permissions, then compare access before and after the update.
Apply the workflow to your project
Adjust these four parts:
| Replace | How to choose |
|---|---|
| Uploaded directory | Select the project needed for the task; Git repository uploads respect .gitignore by default |
| Agent image | Use an explicit image reference containing the agent and its tools |
| Provider | Match credentials, endpoints and executable paths to the model service and image |
| Network rules | Allow the services and read/write access the task needs |
Replace the brackets and send this request to the sandboxed agent:
The project is at [project path under the sandbox working directory].
The goal is [the change to complete].
You may edit [file scope]. Preserve [content that should stay unchanged].
External services needed: [domains and their purpose].
Read the existing files, explain your implementation steps, then make the change and report your checks and output paths.
This is an editorial request template. Enforce filesystem limits through the policy when creating the sandbox; task instructions describe the work and do not automatically become OpenShell access rules. See the policy guide for custom policies.
After retrieving the outputs you need, delete the exercise sandboxes from a host terminal:
openshell sandbox delete api-demo
openshell sandbox delete my-agent
If you also created demo from the overview’s usage commands, remove it with openshell sandbox delete demo.