用途：在隔离的临时 libkrun microVM 中运行不可信或 LLM 生成的代码，避免暴露宿主机；也可用于一次性构建、集成测试夹具或临时 iii worker。
主要能力：sandbox::run 一次调用完成启动、运行代码片段、捕获 stdout/stderr 并自动销毁；sandbox::create → sandbox::exec / sandbox::fs::* → sandbox::stop 生命周期支持多步操作，返回的 sandbox id 在各调用间传递。文件操作包括 write、read、ls、stat、mkdir、rm、mv、chmod、grep、sed。sandbox::list 枚举运行中的沙箱，sandbox::catalog::list 列出可启动镜像名。
使用方式：需在 engine.workers 下启用 iii-sandbox，并提供硬件虚拟化（Apple Silicon 或 Linux 的 /dev/kvm）；Intel Mac 与 Windows 无法启动。调用前用 engine::functions::info { function_id: "sandbox::<fn>" } 获取权威参数与响应结构。在沙箱内运行 iii worker 时，须在 sandbox::create 的 env 中设置 III_ENGINE_URL（如 ws://localhost:49134）并启用网络，localhost 仅在创建时被重写为每沙箱网关；exec 时传入的 localhost 不会被重写。worker 需后台运行，前台执行会阻塞并超时。
适用场景：执行不可信代码、一次性“代码进、stdout 出”、临时构建或测试、隔离文件系统内读写搜索。
限制：沙箱不用于托管长期服务或持久状态，停止后覆盖层被清除；可启动镜像只能是目录中的名称（如 node、python 或自定义镜像），不能是任意 OCI 引用；sandbox::exec 每沙箱串行，长时前台命令会占用槽位；exec 不是 shell，管道、&&、重定向需用 shell 模式或 sh -c；默认网络隔离，访问宿主服务需在创建时显式启用；错误返回结构化提示，应按提示修复后重试。