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?

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.

There is a simpler way.

What is sandbox-bwrap-nix?

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.

It works on any Linux machine that has bubblewrap installed and Nix with flakes enabled.

How it works

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.

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.

Why you would want this

There are a few situations where this setup really shines.

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.

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.

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.

What isolation looks like

The sandbox gives you three layers of protection.

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.

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.

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.

What you give up

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.

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.

How to use it

Clone the repo and run the start script.

git clone https://github.com/grigio/sandbox-bwrap-nix
cd sandbox-bwrap-nix
./start-sandbox.sh

You can also add an alias to your shell config so you can launch the sandbox from anywhere with a short command.

alias sss=/path/to/sandbox-bwrap-nix/start-sandbox.sh

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.

What is in the box

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.

The dev shell includes these tools out of the box.

• nix
• git
• bun
• uv
• opencode
• gnumake
• micro
• less
• bashInteractive with programmable completion

You can add more by editing flake.nix and running nix flake update.

How it compares

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 wrong command and you are cleaning up a mess.

With sandbox-bwrap-nix, the agent sees only what you let it see. The contrast is especially stark for AI tools that install their own software. Without the sandbox, those packages go into your real home. With the sandbox, they stay in sandbox-home and disappear when you reset it.

Compared to Docker, sandbox-bwrap-nix is simpler and faster for this specific workflow. No Dockerfile to write. No image to build. No daemon to start. Just namespaces and bind mounts. But it is also less portable -- it only works on Linux with bwrap installed, and it does not give you a different OS or kernel.

The project structure

The repo is small. You can understand all of it in a few minutes.

• start-sandbox.sh is the entry point. It calls bwrap with the right flags and then runs nix develop.
• flake.nix defines the dev shell with all the tools.
• flake.lock pins the nixpkgs revision.
• sandbox-home is the isolated home directory that gets mounted into the sandbox.

That is it. Three active files and a home directory.

Wrapping up

sandbox-bwrap-nix solves a specific problem in a simple way. If you run AI coding agents, if you experiment with Nix, or if you just want a throwaway environment for trying things, it is worth a look.

It is fast, it is contained, and it does not get in your way. Clone it, try it, and see if it fits your workflow.

The repo is at https://github.com/grigio/sandbox-bwrap-nix