sandbox-bwrap-nix: A lightweight sandbox for AI agents and experiments

If you run AI coding tools on your machine, you know the fear. What if the agent decides to rm -rf something it should not? What if it messes up your home directory, your config files, or your projects?<br>Containers can help, but Docker and Podman are heavy. You need a daemon running. You need to manage images and layers. You need sudo. And you wait while images pull.<br>There is a simpler way.<br>What is sandbox-bwrap-nix?<br>sandbox-bwrap-nix is a minimal sandbox that combines bubblewrap and Nix to give you an isolated environment for running commands, AI agents, and experiments. It boots in under a second. It needs no daemon, no image pulls, and no root privileges. You just run a script and you are inside a clean, isolated shell.<br>It works on any Linux machine that has bubblewrap installed and Nix with flakes enabled.<br>How it works<br>The project is just a few files. The main entry point is a shell script that calls bwrap with a carefully chosen set of flags. It mounts your host's /nix/store as read-only so you can use any Nix package. It gives the sandbox its own /tmp, its own /home, and its own process namespace. Your host filesystem is invisible from inside the sandbox.<br>Once the namespaces are set up, the script runs nix develop inside the sandbox. This activates a dev shell with tools like git, bun, uv, gnumake, and opencode already installed. You land in a bash prompt that looks familiar but is completely contained.<br>Why you would want this<br>There are a few situations where this setup really shines.<br>First, running AI coding agents. Tools like OpenCode can browse your codebase, run commands, install packages, and edit files. You want them to be effective, but you also want guardrails. With sandbox-bwrap-nix, the agent can do its job without ever seeing your real home directory. If it goes rogue, the damage stays inside the sandbox.<br>Second, experimenting with Nix itself. If you are learning Nix or testing a new flake, you can do it inside the sandbox without worrying about polluting your host environment. You can try things, break things, and start fresh with no cleanup.<br>Third, running untrusted code. Someone sends you a script from the internet. You can run it in the sandbox and see what it does. It has network access (the sandbox shares your network), but it cannot touch your files.<br>What isolation looks like<br>The sandbox gives you three layers of protection.<br>Directories. Only specific paths are visible. The Nix store comes in as read-only. Your home directory is replaced with a sandbox-home folder that you can reset any time. /tmp is a fresh tmpfs. The rest of your filesystem simply does not exist from inside the sandbox.<br>Processes. The sandbox uses its own PID namespace. You cannot see host processes, and host processes cannot see the sandbox's processes. This prevents agents from interfering with other running software.<br>Environment. The sandbox starts with --clearenv, which means no environment variables leak from your host. No secrets in env vars, no stray PATH entries, no accidental access to host tools. The sandbox sets up its own clean environment from scratch.<br>What you give up<br>This is not a full container. There is no image management, no layer caching, no registry. You share the host's network and kernel. The point is not to replace Docker. The point is to have something much lighter for the specific use case of running AI agents and experiments.<br>You also need Nix on your host. If you are not using Nix already, that is an extra thing to install. But if you are in the Nix ecosystem, this setup feels natural.<br>How to use it<br>Clone the repo and run the start script.<br>git clone https://github.com/grigio/sandbox-bwrap-nix<br>cd sandbox-bwrap-nix<br>./start-sandbox.sh<br>You can also add an alias to your shell config so you can launch the sandbox from anywhere with a short command.<br>alias sss=/path/to/sandbox-bwrap-nix/start-sandbox.sh<br>Once you are inside, you can install any Nix package as a normal user. You can run opencode, edit files, build projects, and do everything you would normally do. The difference is, none of it touches your real system.<br>What is in the box<br>The sandbox-home directory comes preconfigured with a .bashrc that gives you a nice prompt with git branch info, bash completion from the Nix store, and useful aliases. There is a nix.conf that enables flakes and nix-command. And there is a ready-to-use opencode config folder with skills and prompt instructions.<br>The dev shell includes these tools out of the box.<br>nix<br>git<br>bun<br>uv<br>opencode<br>gnumake<br>micro<br>less<br>bashInteractive with programmable completion<br>You can add more by editing flake.nix and running nix flake update.<br>How it compares<br>If you put sandbox-bwrap-nix next to a regular nix develop, the difference is clear. With nix develop alone, your agent has full access to your filesystem, inherits all your environment variables, shares your PID namespace, and uses your real home directory. One...