sandbox-bwrap-nix：为 AI 代理设计的轻量沙盒

在本地运行 AI 编码代理时，开发者常常担心一个问题：一旦代理执行了错误的 rm -rf 命令，主机上的项目目录、配置文件甚至整个家目录都可能被毁掉。传统容器方案（Docker、Podman）虽然能隔离环境，但需要守护进程、镜像管理、sudo 权限和漫长的镜像拉取，对轻量场景来说过于笨重。sandbox-bwrap-nix 正是为解决这一痛点而生的轻量替代方案。

项目定位

sandbox-bwrap-nix 是一个极简沙盒工具，结合 bubblewrap 与 Nix，为 AI 编码代理和命令行实验提供一个隔离的运行环境。它不需要守护进程、不需要拉取镜像、不需要 root 权限，只需执行一个脚本即可进入干净的隔离 Shell。整个启动过程在 1 秒以内完成。

使用前提：宿主机为 Linux，已安装 bubblewrap，并启用 Nix 的 flakes 功能。

工作原理

项目本身非常精简，核心入口是一个 Shell 脚本，调用 bwrap 并配置特定的命名空间与挂载参数：

将宿主的 /nix/store 以只读方式挂载进沙盒，可直接使用任意 Nix 包。
为沙盒分配独立的 /tmp、/home 目录与进程命名空间（PID namespace）。
宿主文件系统对沙盒完全不可见。

命名空间就绪后，脚本会在沙盒内运行 nix develop，自动激活预装好的开发环境，最终将用户置于一个功能完整但完全隔离的 bash 提示符下。

三层隔离机制

沙盒提供三个层面的保护：

目录隔离：仅暴露白名单路径；Nix store 只读进入；家目录替换为可随时重置的 sandbox-home；/tmp 为全新 tmpfs；其他文件系统对沙盒不可见。
进程隔离：沙盒使用独立 PID 命名空间，宿主与沙盒进程互不可见，AI 代理无法干扰其他运行中的软件。
环境隔离：启动时使用 --clearenv 参数，宿主机环境变量不泄漏；沙盒从零构建自己的干净环境，杜绝密钥通过 ENV 泄露。

典型使用场景

运行 AI 编码代理：OpenCode 等工具可正常浏览代码库、安装依赖、修改文件，但永远不会触及真实家目录。即使代理失控，破坏也仅限沙盒内部。
试验 Nix 配置：学习或测试 flake 时在沙盒内进行，弄乱环境后可随时重置，无需清理宿主。
运行不可信脚本：网络下载的脚本可先放入沙盒观察行为；脚本有网络访问（共享宿主网络），但无法触碰本地文件。

与 Docker / 普通 nix develop 的对比

相比裸 nix develop，沙盒为 AI 代理挡住了文件系统访问、环境变量泄漏和 PID 命名空间共享，安全性大幅提升；相比 Docker，则无需编写 Dockerfile、无需构建镜像、无需启动守护进程，启动更快、配置更轻。代价是可移植性较差：仅支持装有 bwrap 的 Linux，且不提供独立 OS 或内核。

开箱即用的工具集

进入沙盒后，开发环境预装以下工具：nix、git、bun、uv、opencode、gnumake、micro、less，以及支持可编程补全的 bashInteractive。sandbox-home 目录还内置了带 Git 分支提示的 .bashrc、启用 flakes 的 nix.conf 以及一套 opencode 配置文件。用户可通过编辑 flake.nix 并执行 nix flake update 自行扩展工具集。

项目仓库为 https://github.com/grigio/sandbox-bwrap-nix，克隆后运行 ./start-sandbox.sh 即可进入沙盒，也可为 start 脚本设置 Shell alias 以便随时调用。