Sandboxes on Linux

Set up NVIDIA OpenShell sandboxes on Linux with Docker Engine, Landlock and the openshell-gateway systemd user service, check the machine with sandbox doctor, and run your first agent on a live project folder.

Install and configure OpenShell sandboxes on Linux with defenseclaw sandbox setup, then check the machine with defenseclaw sandbox doctor. By default each sandbox is a Docker container with your project folder mounted live.

How it fits together

hooks, web
model calls
starts
mounted
Claude Code or Codexskip-permissions on
OpenShell supervisorthe only way out
DefenseClaw daemonchecks hooks, proxies the web
OpenShell gatewaysystemd user service
Your project folderlive at /work/myapp
Internetallowed sites
Model provider

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

  1. Your project folderlive at /work/myapp
    • mountedClaude Code or Codex
  2. Claude Code or Codexskip-permissions on
    • OpenShell supervisor
  3. OpenShell gatewaysystemd user service
    • startsOpenShell supervisor
  4. OpenShell supervisorthe only way out
    • hooks, webDefenseClaw daemon
    • model callsModel provider
  5. Model provider
  6. DefenseClaw daemonchecks hooks, proxies the web
    • Internet
  7. Internetallowed sites
A Linux sandbox. The agent's tool calls and web traffic go through DefenseClaw; model calls go straight to the provider, opened by OpenShell for the harness's own program.

Before you start

You needDetails
DefenseClawInstalled, with the daemon running (quickstart). Run as your own user, not root.
Linuxamd64 or arm64 with systemd user sessions. WSL2 is not supported.
KernelLandlock ABI 3 or newer in cat /sys/kernel/security/lsm.
DockerRootful Docker Engine 28 or newer with buildx, and your user in the docker group. Rootless Docker is not supported.
Disk5 GiB free for Docker (10 GiB recommended). The first image build downloads about 3 GB.
GitGit 2.29 or newer (sudo dnf install git or sudo apt-get install git). A copy-mode run copies your project with it, and the pre-session snapshot of a git repository uses it. defenseclaw sandbox doctor checks it (Host Git): the row fails where every run works on a copy (a MicroVM, which mounts no host folders, a managed computer, or openshell.workdir.mode copy) and warns otherwise (Managed command availability).
OpenShell0.1.6 or newer. Setup installs it, or upgrades an older one, after asking.

Turn on linger so the gateway keeps running after you log out: sudo loginctl enable-linger $USER.

Set up

Run setup

defenseclaw sandbox setup

Setup checks the machine and asks before each change: installing OpenShell (NVIDIA's installer, sha256 verified, sudo), turning on project-folder mounts and turning off OpenShell's usage telemetry on your local gateway, adding the claude and codex shell wrappers, and building the harness images.

DefenseClaw sandbox setup
  Checking this machine…  ✓ linux/arm64  ✓ Landlock  ✓ Docker 29.4.0  ✗ OpenShell not installed
Install OpenShell … with NVIDIA's installer? (sudo; sha256 verified) [y/N] y
  ✓ gateway configured and restarted
  ✓ openshell.enabled is on in ~/.defenseclaw/config.yaml
  ✓ the daemon runs the sandbox subsystem (ingress 127.0.0.1:18971, egress proxy 127.0.0.1:18972)

  ✓ Done →  cd <project> && defenseclaw sandbox run claude

Setup is safe to run again. Say no to mounts, or pass --no-mounts, and no Claude Code or Codex sandbox can start. Flags and the full list of steps are in the sandbox CLI reference. The TUI runs the same setup: defenseclaw tui, 0, Sandboxes (OpenShell).

You can also run setup from the TUI (defenseclaw tui, 0, Sandboxes (OpenShell)). The form shows the command it will run before you start it.

DefenseClaw TUI Setup, Sandboxes (OpenShell) form on Linux: the command it will run, the harnesses to set up, the credentials found, the This machine checks (Docker, Landlock, OpenShell 0.1.5, bind mounts), and the Mount Project Folder and OpenShell telemetry options

~/code/myapp
Recorded on DefenseClaw 1.0.4 on RHEL 9 with Docker 29.8.1 and OpenShell 0.1.1 installed, so setup offers the in-place upgrade to the pinned OpenShell 0.1.5 (the package manager output is trimmed). Every question shows its default answer (Enter); the plan is approved with y and the Codex image was skipped with n. The shell wrapper question was left at its default, no. On a host with no OpenShell, the same question reads 'Install OpenShell'.

Check the machine

defenseclaw sandbox doctor
  ✓ Landlock                   ABI 6
  ✓ Docker                     Docker 29.4.0 (Ubuntu 24.04 LTS)
  ✓ Gateway service            openshell-gateway active (running)
  ✓ Gateway compute driver     docker
  ✓ Project bind mounts        enabled for the docker driver
  ✓ Sandbox ingress port       127.0.0.1:18971 is served by the DefenseClaw daemon
  ✓ Harness images             hook-verified: claudecode 2.1.156, codex 0.146.0
  …

  ✓ ready for sandboxes

Every warning or failure names its fix on the next line. defenseclaw sandbox doctor --fix applies the fixes that need only your user. The command exits 1 when a check fails.

defenseclaw sandbox doctor on Linux: every check passes, with OpenShell 0.1.5 on the docker driver, the sandbox ports served by the DefenseClaw daemon, hook-verified harness images and the sandbox TLS trust row, ending ready for sandboxes

Run your first agent

cd ~/code/myapp
defenseclaw sandbox run claude

Continue with run an agent.

Understand what it changed

  • OpenShell 0.1.6, installed with NVIDIA's installer pinned by SHA-256, using sudo. DefenseClaw runs sandboxes on 0.1.6 up to, not including, 0.2.0. An older 0.1 release only connects so that setup can upgrade it.
  • The gateway listens on 127.0.0.1:17670 with mutual TLS. Setup turns on project-folder mounts for the Docker driver in ~/.config/openshell/gateway.toml, turns OpenShell's usage telemetry off in gateway.env, backs both files up and restarts the gateway once. The compute driver is docker unless you choose MicroVMs.
  • DefenseClaw's config: openshell.enabled: true, and openshell.harnesses lists the harnesses setup prepared (--harness NAME adds one; the default is Claude Code and Codex).
  • Harness images, built and checked that their hooks reach DefenseClaw. defenseclaw sandbox image list shows them.
  • Shell wrappers for claude and codex, if you said yes (--no-wrappers skips them).

defenseclaw sandbox teardown reverses all of it except the OpenShell install.

Run sandboxes in MicroVMs with KVM

On a host with KVM, the vm driver is intended to run each sandbox as a small virtual machine with its own kernel, including when the host kernel has no Landlock. Setup offers it when /dev/kvm exists and stops with the way on if something is missing: access to /dev/kvm, e2fsprogs 1.43 or newer, and the openshell-driver-vm download. Every MicroVM run works on a copy, so sandbox pull NAME --apply brings the work into your project (--branch or --patch-out FILE saves it elsewhere).

With OpenShell 0.1.6, MicroVM sandboxes on Linux with KVM do not start on either per-user or managed computers. OpenShell gives the sandbox account ownership of the guest root folder, so DefenseClaw cannot trust its localhost resolver and refuses and deletes the sandbox. Until a fixed OpenShell release is supported, use Docker. On a per-user computer, run defenseclaw sandbox setup and answer no to MicroVMs. On a managed computer, ask your administrator to set enterprise.openshell.driver: docker and run ensure; driver_fallback: docker does not cover this refusal. See the sandbox guide.

One OpenShell gateway per machine

OpenShell's gateway listens on 127.0.0.1:17670 for the account that started it, so only that account can run sandboxes. To hand sandboxes to another account, run systemctl --user disable --now openshell-gateway in the first, then defenseclaw sandbox setup in the second. Every sandbox on the gateway stops. Members of the docker group can see every sandbox container, so give the group only to accounts that trust each other.

A gateway that runs another way

If you started OpenShell's gateway yourself, not as the openshell-gateway user service, setup cannot restart it. It writes gateway.toml and gateway.env and asks you to restart the gateway the way you started it. Until you do, sandbox doctor warns that the gateway has not been restarted since the change. Details: OpenShell installed another way.

Check it worked

defenseclaw sandbox doctor ends with ready for sandboxes.

Undo

defenseclaw sandbox teardown --dry-run prints every step. defenseclaw sandbox teardown removes this install's sandboxes, images and gateway changes. OpenShell stays installed.

Common problems

Run defenseclaw sandbox doctor first. These are the Linux-only failures it reports, plus the folder problems of a live-mounted run.

The Landlock check fails

You see: the Landlock check fails.

Cause: the kernel does not report Landlock ABI 3 or newer with landlock in its lsm= list. OpenShell refuses to start a sandbox without it.

Fix: boot a kernel with Landlock ABI 3 or newer (6.2 or newer upstream, or a distribution kernel with a backport), then use Docker. With OpenShell 0.1.6, MicroVM sandboxes on Linux with KVM do not start on per-user or managed computers, so selecting MicroVMs does not resolve this check (known limit).

Check: cat /sys/kernel/security/lsm lists landlock and the check passes.

Docker is rootless or too old

You see: the Docker check says rootless Docker, or Docker older than 28.

Cause: sandboxes need a rootful Docker Engine 28 or newer. Rootless Docker keeps containers off the host network.

Fix: install a rootful Engine and run sudo usermod -aG docker $USER, then log in again. With linger on, logging out does not restart your systemd user manager, so the gateway service still lacks the group (next entry).

Check: the Docker check passes.

The gateway service started before you joined the docker group

You see: the Gateway service check says it runs under a user manager that started before you joined the docker group, or setup's restart fails with the restarted gateway is not healthy and names sudo systemctl restart user@<uid>.service. Or a run fails with permission denied on /var/run/docker.sock, or the DefenseClaw daemon started before you joined the docker group.

Cause: your systemd user manager and the daemon keep the groups they started with.

Fix: run sudo systemctl restart user@$(id -u).service (this stops your user services, which start again), then defenseclaw-gateway restart, then run setup again.

Check: defenseclaw sandbox doctor passes the Gateway service and Docker checks.

make fails inside a sandbox

You see: every make recipe fails with make: <command>: Operation not permitted (Error 127), and so do node-gyp builds.

Cause: the sandbox runs an image built before DefenseClaw's make wrapper, or the agent ran /usr/bin/make by its full path.

Fix: delete the sandbox and run again, which builds the current image. Run make by name.

Check: make test runs inside the new sandbox.

Docker BuildKit or buildx is missing

You see: docker's buildx plugin is not available (`docker buildx version`: …), the Docker BuildKit check fails, or DOCKER_BUILDKIT=0 turns BuildKit off.

Cause: the harness images need BuildKit, which docker uses only through its buildx plugin. Without it docker falls back to a legacy builder that cannot build them (the --chmod option requires BuildKit). A DOCKER_CONFIG or HOME that points elsewhere hides the plugin.

Fix: install the plugin (Docker Desktop includes it, on Linux it is docker-buildx-plugin from Docker's repository), point DOCKER_CONFIG at the config that has cli-plugins/docker-buildx, unset DOCKER_BUILDKIT or set it to 1, then restart the daemon with defenseclaw-gateway restart. The daemon builds in the environment it started with.

Check: the Docker BuildKit check passes.

An image build fails

You see: an error ending with the last lines docker printed (up to 40, with anything token-shaped redacted).

Cause: the build failed, whether setup, image build or the daemon ran it.

Fix: read ~/.defenseclaw/logs/sandbox-image-<harness>.log, or run defenseclaw sandbox image build <harness> --verbose to stream the build. The daemon log (~/.defenseclaw/gateway.log) has the lines under OPENSHELL_IMAGE_BUILD_FAILED.

Check: defenseclaw sandbox doctor shows the image as hook-verified.

A folder cannot be mounted live or has no snapshot room

You see: … cannot be mounted live: …; run with --copy to work on a copy, or the folder (for its undo snapshot) is …, above the 1.0 GiB limit.

Cause: the folder's git state cannot be protected in place, or a folder without git passes the 1 GiB snapshot cap.

Fix: add --copy. For the cap, make the folder a git repository, use --copy, or use --no-snapshot (no undo).

Check: the run starts.

npm install fails with EROFS

You see: in a live-mounted sandbox, npm install fails in a prepare script with EROFS under the folder the banner's Protected line marks as the repository's core.hooksPath.

Cause: the project points git's hooks at that folder (husky does), and DefenseClaw keeps it read-only.

Fix: run npm install --ignore-scripts in the sandbox, or work on a copy with --copy.

Check: the install finishes.

Next