OpenShell sandboxes

Run Claude Code, Codex and other coding agents in skip-permissions mode inside NVIDIA OpenShell sandboxes on Linux and Apple-silicon Macs, with DefenseClaw judging every tool call and every site.

defenseclaw sandbox run runs a coding agent in its skip-permissions mode inside an NVIDIA OpenShell sandbox. The agent sees only your project folder. DefenseClaw still checks every tool call and every site its web traffic reaches; model calls go straight to the model provider. At the end you review what changed and keep it, undo it or pull it back.

cd ~/code/myapp
defenseclaw sandbox run claude

Use it when you want an agent to work without stopping to ask. Claude Code's skip-permissions flag is --dangerously-skip-permissions, Codex's is --dangerously-bypass-approvals-and-sandbox. On your own machine that lets a bad guess touch everything you can touch. In a sandbox it touches only the project.

The mental model

The sandbox is a locked room that holds only your project folder. Two layers build it.

  • OpenShell builds the room. A container on Linux by default, a MicroVM on a Mac. The workload has no network of its own, runs as your uid with no capabilities, and is held in by Landlock and seccomp. Its only way out is OpenShell's supervisor.
  • DefenseClaw adds the judgment. Hooks inside the sandbox send every tool call to the DefenseClaw daemon, which applies the same rule packs, guardrails and judge as outside. The egress proxy decides and logs every site the web traffic reaches. Model calls bypass it: OpenShell sends them straight to the provider and adds the real key (Sandbox network). DefenseClaw also hides secret files, protects git internals, snapshots the folder and reviews what changed.
Inside the room, the agent canOutside the room, it cannot
Edit your project, run tests, build and install packages.See your home directory, ~/.ssh, ~/.aws, other repositories or the rest of the system.
Browse the web through DefenseClaw's egress proxy.Reach paste sites, file drops, webhook catchers, tunnels and anonymizers on the blocklist.
Use your model credential through a placeholder.Read the real key: OpenShell adds it only on requests to the model provider.
Reach a port on your machine you name with --host-port, once you approve it.Reach DefenseClaw's own API or the OpenShell gateway, ever. Reach your local network unless you approve it.

The sandbox reaches your machine only at host.openshell.internal, through a hook ingress port and the egress proxy port. The main API is never reachable. With the default API port 18970, the hook ingress is 18971 and the egress proxy 18972. Agent segmentation shows which layer enforces what.

See it in action

What OpenShell protects

OpenShell isolation: a .env secret that reads as empty inside the sandbox, an environment with only a placeholder model key, and host files the agent cannot see. Recorded on an earlier build, so the launch banner differs slightly from 1.0.4.

What DefenseClaw adds

DefenseClaw inside OpenShell: a malicious prompt is blocked, a tool call to the cloud metadata endpoint is blocked, and the egress proxy allows github.com but refuses a request-inspection site. The block messages in this recording use older wording; 1.0.4 says “DefenseClaw policy blocked this action (rule ID: title). Do not retry it in another form.”

Linux and macOS at a glance

The driver decides these rows, not the operating system. A Linux host with KVM can run the MicroVM driver too and then behaves like the macOS column.

TopicLinux (Docker driver, the default)macOS (Apple silicon, MicroVM driver)
OpenShell driverOne container per sandbox.One virtual machine per sandbox, on Apple's Hypervisor. OpenShell calls the driver experimental.
IsolationLinux namespaces, Landlock (ABI 3 or newer), seccomp, your uidThe same, inside a MicroVM with its own Linux kernel
OpenShell gatewayopenshell-gateway systemd user serviceHomebrew's nvidia/openshell/openshell service
Your project folderMounted live at /work/<folder>. --copy works on a copy.Always a copy, at /sandbox/work/<folder>. A MicroVM mounts no host folders.
Secret filesAppear empty insideHeld back from the copy
Git internals.git/hooks and .git/config are read-onlyThe agent's work comes back as git objects
End of sessionKeep the changes, or undo themBring the changes back (apply, branch or patch), or leave them in the sandbox
Undosandbox undo restores the pre-session snapshotsandbox undo reverts the last sandbox pull --apply
First start of an imageA few secondsAbout a minute, to prepare a MicroVM disk of about 5 GB
Harness imagesBuilt in DockerBuilt in Docker Desktop, then booted as MicroVMs

Why not Docker Desktop on a Mac?

OpenShell's supervisor needs Landlock. Docker Desktop's Linux VM kernel does not run it, so a sandbox on OpenShell's Docker driver fails to start there. DefenseClaw refuses that combination and sets the Mac's gateway to the MicroVM driver instead. Docker Desktop still builds the harness images.

Linux (amd64 or arm64) with Docker Engine 28 and a Landlock kernel, or an Apple-silicon Mac with Docker Desktop and Homebrew, as your own user. Not on Windows, WSL2, Intel Macs or as root. Setup installs OpenShell 0.1.6. On Linux with Docker your folder is mounted live; on a Mac, or with any MicroVM, the agent works on a copy.

Claude Code, Codex, GitHub Copilot CLI, OpenCode, Kiro CLI, Hermes Agent and Antigravity run. Amp, Cursor Agent and Devin CLI cannot run yet.

Requirements

DefenseClaw drives OpenShell 0.1.1 and later 0.1 releases, not 0.2, and runs sandboxes only on 0.1.6 or later. OpenShell 0.1.6 initializes missing or empty MicroVM hosts files and includes the earlier network and lifecycle fixes. It preserves nonempty image-authored hosts files, so DefenseClaw checks the completed image's exported hosts file with its resolver and checks the guest resolver before a session starts. Setup installs OpenShell 0.1.6 with NVIDIA's installer, and on 0.1.1 to 0.1.5 it offers the upgrade to 0.1.6 in place. On those older releases DefenseClaw still lists, stops, deletes and pulls from sandboxes, but creates and starts none. Setup is the only place that installs it.

The full lists are on Set up on Linux and Set up on macOS. In short: run DefenseClaw as your own user (not root), with its daemon running, plus rootful Docker Engine 28 or newer and a Landlock kernel on Linux, or Docker Desktop and Homebrew on an Apple-silicon Mac. Allow at least 5 GiB of free disk for the images.

Choose your path

Start with Set up on Linux or Set up on macOS, then Run an agent and Review, undo or pull.

The session lifecycle

Set up the machineonce: defenseclaw sandbox setup
Start or resume a sandboxsandbox run · sandbox connect
The agent workstool calls and web traffic checked
Review what changedfiles that can run code flagged
Decide what to keepLinux: keep or undo · Mac: bring back
Sandbox stopped and keptresume it later, or delete it

List view for small screens. Use the expand button to open the drawing.

  1. 1.Set up the machineonce: defenseclaw sandbox setup
    • Start or resume a sandbox
  2. 2.Start or resume a sandboxsandbox run · sandbox connect
    • The agent works
  3. 3.The agent workstool calls and web traffic checked
    • Review what changed
  4. 4.Review what changedfiles that can run code flagged
    • Decide what to keep
  5. 5.Decide what to keepLinux: keep or undo · Mac: bring back
    • Sandbox stopped and kept
  6. 6.Sandbox stopped and keptresume it later, or delete it
A sandbox's life, one stage per list item below, with review and keep shared in step 4. Setup is once per machine. Every run after it repeats steps 2 to 5.
  1. Setup checks the machine, installs OpenShell when you agree and builds the harness images.
  2. Run creates a sandbox for the folder you are in, or resumes the one that holds it.
  3. During the session every tool call, and every site reached through the egress proxy, is checked. Blocks and asks appear in the activity feed.
  4. At the end you review the changed files that could run code on your machine, then keep, undo or pull them. On Linux with Docker you keep or undo the changes. On a Mac, a MicroVM or with --copy, you apply them, put them on a branch, write a patch, or leave them in the sandbox.
  5. Stop or delete. The sandbox is kept: defenseclaw sandbox connect NAME resumes it, defenseclaw sandbox delete NAME removes it.

What you can see, and how far to trust it

Some of what DefenseClaw reports about a sandbox it measures itself, and some is what OpenShell or the sandboxed program says about itself. Sandbox telemetry says which is which, signal by signal.

What it does not do

  • It does not stop a program from using the model credential through the harness's own program, because OpenShell opens the model host around the egress proxy.
  • It does not inspect HTTPS paths or bodies.

Which agents can run

Claude Code and Codex are set up by default. GitHub Copilot CLI, OpenCode, Kiro CLI, Hermes Agent and Antigravity also run. DefenseClaw uses a harness image only after it proves that its hooks fire and block in it. Amp, Cursor Agent and Devin CLI cannot run yet because the unverified images need an account no test could stand in for.

Agentsandbox run nameHook tierStatus
Claude CodeclaudemanagedVerified
CodexcodexmanagedVerified
GitHub Copilot CLIcopilotmanagedVerified through bring-your-own-provider mode
OpenCodeopencodeuserVerified
Kiro CLIkirouserVerified in scripted mode
Hermes AgenthermesuserVerified with a mock model
Antigravityantigravity (or agy)userVerified with a mock Gemini API
Cursor Agentcursor-agentmanagedUnverified
AmpampuserUnverified
Devin CLIdevinuserUnverified

The hook tier says whether the agent could switch DefenseClaw's hooks off. Managed: the hook configuration is a root-owned file that user and project settings cannot override. User: the configuration lives where the agent could edit it, so the run banner says so and DefenseClaw watches for hooks that go silent. The capability matrix lists each harness's hook file and version. Add another agent with defenseclaw sandbox setup --harness NAME.

What is in the image

Each harness image is NVIDIA's OpenShell community base image (Ubuntu 24.04, pinned by digest) with the harness and DefenseClaw's hooks on top. The agent finds gcc, g++ and make, Python 3.14 (python3, python, pip using /sandbox/.venv, plus uv), Node.js 22 with npm, and git, gh, curl, jq and ssh. make is a DefenseClaw wrapper around GNU make, because OpenShell's seccomp filter refuses a call make issues for every recipe. There is no Go, Rust or Java toolchain, and the agent has no root, so it cannot apt-get install one. For another system tool, build a base image of your own FROM the pinned base, push it, and set openshell.image.base in config.yaml to its digest (<image>@sha256:…; configuration). The next run builds the harness images on it.

Where to go next

Reference: Sandbox CLI, policy, network, telemetry. Problems: Sandbox troubleshooting.