Gemini CLI sandbox: enable Docker, Podman, macOS Seatbelt or gVisor

gemini -s -p "analyze the code structure"

export GEMINI_SANDBOX=docker
gemini -p "run the test suite"

{
  "tools": {
    "sandbox": "docker"
  }
}

GEMINI_SANDBOX accepts true, docker, podman, sandbox-exec, runsc or lxc. Precedence is flag, then env var, then settings file.

Seatbelt uses the built-in sandbox-exec. Pick a profile with SEATBELT_PROFILE.

• permissive-open (default): write restrictions, network allowed
• permissive-proxied: write restrictions, network via proxy
• restrictive-open: strict restrictions, network allowed
• restrictive-proxied: strict restrictions, network via proxy
• strict-open: read and write restrictions, network allowed
• strict-proxied: read and write restrictions, network via proxy

export SEATBELT_PROFILE=restrictive-open
gemini -s

The default image is ghcr.io/google/gemini-cli:latest. Your current directory is mounted at the same absolute path inside the container.

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

export GEMINI_SANDBOX_IMAGE="us-central1-docker.pkg.dev/my-project/my-repo/my-custom-sandbox:latest"

A .gemini/sandbox.Dockerfile built with BUILD_SANDBOX=1 only builds automatically when you run Gemini CLI from source. npm installs need a prebuilt image.

runsc gives the strongest isolation. It needs Docker with the runsc runtime configured, and it is never auto detected.

export GEMINI_SANDBOX=runsc
gemini -p "build the project"