Skip to content
AgentAtlas

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

How do I run Gemini CLI in a sandbox?

Start the CLI with -s (or --sandbox), set GEMINI_SANDBOX, or set tools.sandbox in settings.json. Supported providers include docker, podman, sandbox-exec (macOS Seatbelt), runsc (gVisor) and lxc. The flag wins over the env var, which wins over settings.

Compare: sandbox modes in every AI coding agent →

Three ways to turn it on

Flag

gemini -s -p "analyze the code structure"

Environment variable (macOS/Linux)

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

settings.json

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

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

macOS Seatbelt profiles

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

Shell

export SEATBELT_PROFILE=restrictive-open
gemini -s

Docker or Podman

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

Custom image in settings.json

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

Custom image via env var

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.

gVisor (runsc) on Linux

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

Shell

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

Sources

More Gemini CLI guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →