Lightweight sandbox tool for AI agents launches with no daemon or root needed

sandbox-bwrap-nix is a minimal sandbox tool designed specifically for running AI coding agents and experiments safely. The project consists of just a few files: start-sandbox.sh (the entry point that calls bubblewrap with a careful set of flags), flake.nix (which defines the dev shell with included tools), flake.lock (which pins the nixpkgs revision), and a sandbox-home directory that serves as the isolated home environment.

When you run the start script, the tool sets up isolated namespaces using bubblewrap. It mounts the host's /nix/store as read-only so you can access Nix packages, but replaces your real home directory with a sandbox-home folder. /tmp becomes a fresh tmpfs. Most of the rest of your filesystem is invisible from inside the sandbox. Once namespaces are established, the script runs nix develop inside the sandbox, activating a dev shell with tools like git, bun, uv, gnumake, and opencode already installed. You land in a bash prompt that looks familiar but operates completely contained.

The isolation works across three layers. Directories are restricted: only specific paths are visible, and the Nix store comes in read-only. Processes use their own PID namespace, so the sandbox cannot see host processes and host processes cannot see the sandbox. Environment variables are cleared entirely (--clearenv), preventing secrets in env vars or stray PATH entries from leaking from the host. To use it, you clone the repo, run ./start-sandbox.sh, and optionally add an alias to launch the sandbox from anywhere. The sandbox-home directory comes preconfigured with a .bashrc featuring git branch info, bash completion, and useful aliases, plus a nix.conf that enables flakes.

Compared to regular nix develop alone, the difference is stark: without the sandbox, an AI agent has full access to your filesystem, inherits all your environment variables, shares your PID namespace, and uses your real home directory. With sandbox-bwrap-nix, the agent sees only what you explicitly allow. Compared to Docker, sandbox-bwrap-nix is simpler and faster for this specific workflow—no Dockerfile, no image build, no daemon startup—but it only works on Linux with bubblewrap and shares the host's network and kernel. The project trades off portability and features for speed, simplicity, and a natural fit for developers already in the Nix ecosystem.

sandbox-bwrap-nix addresses a practical pain point for developers using AI coding agents: the fear of an agent running a destructive command like rm -rf on critical files or configuration directories. While containers like Docker and Podman offer isolation, they carry overhead—daemons, image management, layer caching, and the need for root privileges or sudo. The project takes a narrower, lighter approach by combining two existing Linux tools: bubblewrap (a minimal privilege-dropping sandbox) and Nix (which the project assumes users already have). The result is a tool that offers meaningful safety (isolated filesystem, separate process namespace, cleared environment variables) without the operational complexity of full containerization.

The design trade-offs are transparent: sandbox-bwrap-nix sacrifices portability (Linux and bubblewrap only) and some container features (no image caching, no separate OS kernel) in exchange for simplicity, speed, and a natural fit for developers already using Nix. The isolation model—mounting the Nix store as read-only, replacing the home directory with a throwaway sandbox-home folder, and using a fresh /tmp—means an AI agent can still be effective (it can install packages, edit files, run commands) but any damage or leftover changes stay inside the sandbox and can be erased by resetting the sandbox-home folder.

No comments yet. Be the first to share your thoughts!