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
- Gemini CLI: YOLO mode, auto_edit and allowing specific shell commands
- Gemini CLI: turn off usage statistics and telemetry
- Configure Gemini CLI with settings.json
- Gemini CLI extensions and custom commands
- GEMINI.md in Gemini CLI: context file locations, imports and /memory
- Gemini CLI MCP servers: gemini mcp add and mcpServers in settings.json
- Gemini CLI custom slash commands: TOML files, {{args}}, !{shell} and @{file}
- Gemini CLI headless mode: gemini -p, JSON output and exit codes for scripts and CI
- Gemini CLI hooks: settings.json, BeforeTool, AfterTool, exit codes and /hooks
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 →