容器镜像、挂载与身份映射

容器沙箱会把当前工作区挂载到相同绝对路径。宿主安装的工具不一定存在于镜像中，缺少构建工具时应准备镜像依赖，而不是反复重试同一命令。

选择镜像

可用 GEMINI_SANDBOX_IMAGE 指定本地或仓库镜像，也可按官方沙箱专页配置对象：

{
  "tools": {
    "sandbox": {
      "command": "docker",
      "image": "us-central1-docker.pkg.dev/my-project/my-repo/my-custom-sandbox:latest"
    }
  }
}

这是占位镜像地址，需要替换并确保运行环境有拉取权限。镜像应含 bash 等标准 shell 工具。

本地构建的适用范围

专页给出 .gemini/sandbox.Dockerfile 和以下入口：

BUILD_SANDBOX=1 GEMINI_SANDBOX=docker gemini -p "run my custom build"

同页排障进一步限定：自动 BUILD_SANDBOX 构建只适用于从源码运行 CLI；npm 安装应使用预先构建的镜像。使用默认 ghcr.io 镜像作基础时，教程还要求 gh 已安装并认证。不能把自动构建写成所有安装方式都支持。

额外挂载

SANDBOX_MOUNTS 使用逗号分隔的 from:to:opts。from 必须是宿主绝对路径；省略 to 时保持相同路径，省略 opts 时默认只读 ro。

export SANDBOX_MOUNTS="/path/on/host:/path/in/container:rw,/another/path:ro"

只给需要写入的挂载 rw；增加挂载也扩大可访问的数据范围。路径是否可访问仍受提供方、容器用户和宿主权限影响。

CLI 自身在容器里运行

官方嵌套场景使用宿主 /var/run/docker.sock 创建同级沙箱容器。工作区在外层容器内必须与宿主绝对路径一致，因为宿主 Docker daemon 按宿主路径解析绑定。共享该 socket 意味着外层容器能调用宿主 Docker，不只是访问一个普通目录。

额外参数与 Linux 用户

SANDBOX_FLAGS 将空格分隔的参数传给 docker/podman；仅在理解对应引擎参数时使用，关闭安全选项可能削弱原有隔离。

SANDBOX_SET_UID_GID=true 强制映射宿主 UID/GID，false 禁用映射。遇到构建产物归属或写权限错误时检查映射与挂载权限，不能只改 Gemini 的工具批准设置。