docs/cli/sandbox.md
This document provides a guide to sandboxing in Gemini CLI, including prerequisites, quickstart, and configuration.
Before using sandboxing, you need to install and set up Gemini CLI:
npm install -g @google/gemini-cli
To verify the installation:
gemini --version
Sandboxing isolates potentially dangerous operations (such as shell commands or file modifications) from your host system, providing a security barrier between AI operations and your environment.
The benefits of sandboxing include:
You can enable sandboxing using a command flag, environment variable, or configuration file.
gemini -s -p "analyze the code structure"
macOS/Linux
export GEMINI_SANDBOX=true
gemini -p "run the test suite"
Windows (PowerShell)
$env:GEMINI_SANDBOX="true"
gemini -p "run the test suite"
{
"tools": {
"sandbox": "docker"
}
}
Enable sandboxing using one of the following methods (in order of precedence):
-s or --sandboxGEMINI_SANDBOX=true|docker|podman|sandbox-exec|runsc|lxc"sandbox": true in the tools object of your
settings.json file (for example, {"tools": {"sandbox": true}}).Your ideal method of sandboxing may differ depending on your platform and your preferred container solution.
Lightweight, built-in sandboxing using sandbox-exec.
Default profile: permissive-open - restricts writes outside project
directory but allows most other operations.
Built-in profiles (set via SEATBELT_PROFILE env var):
permissive-open (default): Write restrictions, network allowedpermissive-proxied: Write restrictions, network via proxyrestrictive-open: Strict restrictions, network allowedrestrictive-proxied: Strict restrictions, network via proxystrict-open: Read and write restrictions, network allowedstrict-proxied: Read and write restrictions, network via proxyCross-platform sandboxing with complete process isolation using container
technology. By default, it uses the ghcr.io/google/gemini-cli:latest image.
Prerequisites:
How it works (Workspace directory):
Inside the sandbox container, your current working directory is mounted at the
exact same absolute path as it is on your host machine. For example, if you
run the CLI from /Users/you/project on your host machine, the sandbox will
mount your local project folder and operate within /Users/you/project inside
the container. This allows the AI to seamlessly read and modify your project
files while remaining isolated from the rest of your system.
Quick setup:
To enable Docker sandboxing, run Gemini CLI with the sandbox flag and specify Docker as the provider:
# Using the environment variable (Recommended)
export GEMINI_SANDBOX=docker
gemini -p "build the project"
# Or configure it permanently in your settings.json
# {"tools": {"sandbox": "docker"}}
Customizing the Sandbox Image:
If your project requires specific dependencies, you can specify a custom image
name or have Gemini CLI build one for you automatically. You can use any Docker
or Podman image as your sandbox, provided it has standard shell utilities (like
bash) available.
Option A: Using an existing custom image (e.g., Artifact Registry)
To configure a custom image that is hosted on a registry (or built locally),
update your settings.json to use an object for the sandbox configuration, or
set the GEMINI_SANDBOX_IMAGE environment variable.
Example: Configuring via settings.json
{
"tools": {
"sandbox": {
"command": "docker",
"image": "us-central1-docker.pkg.dev/my-project/my-repo/my-custom-sandbox:latest"
}
}
}
Example: Configuring via environment variable
export GEMINI_SANDBOX_IMAGE="us-central1-docker.pkg.dev/my-project/my-repo/my-custom-sandbox:latest"
Option B: Building a local custom image automatically
If you prefer to define your environment as code, you can provide a Dockerfile and Gemini CLI will build the image automatically.
.gemini/sandbox.Dockerfile in your project root.gh CLI installed and authenticated (if you are using
the default ghcr.io/google/gemini-cli image as a base).BUILD_SANDBOX environment variable set:BUILD_SANDBOX=1 GEMINI_SANDBOX=docker gemini -p "run my custom build"
... Troubleshooting and Side Effects:
The Windows Native sandbox uses the icacls command to set a "Low Mandatory
Level" on files and directories it needs to write to.
icacls "C:\path\to\dir" /setintegritylevel Medium
C:\Windows) for safety.Strongest isolation available: runs containers inside a user-space kernel via gVisor. gVisor intercepts all container system calls and handles them in a sandboxed kernel written in Go, providing a strong security barrier between AI operations and the host OS.
Prerequisites:
When you set sandbox: "runsc", Gemini CLI runs
docker run --runtime=runsc ... to execute containers with gVisor isolation.
runsc is not auto-detected; you must specify it explicitly (e.g.
GEMINI_SANDBOX=runsc or sandbox: "runsc").
To set up runsc:
Full-system container sandboxing using LXC/LXD. Unlike Docker/Podman, LXC
containers run a complete Linux system with systemd, snapd, and other system
services. This is ideal for tools that don't work in standard Docker containers,
such as Snapcraft and Rockcraft.
Prerequisites:
snap install lxd or apt install lxd).Quick setup:
# Initialize LXD (first time only)
lxd init --auto
# Create and start an Ubuntu container
lxc launch ubuntu:24.04 gemini-sandbox
# Enable LXC sandboxing
export GEMINI_SANDBOX=lxc
gemini -p "build the project"
Custom container name:
export GEMINI_SANDBOX=lxc
export GEMINI_SANDBOX_IMAGE=my-snapcraft-container
gemini -p "build the snap"
Limitations:
Tool-level sandboxing provides granular isolation for individual tool executions
(like shell_exec and write_file) instead of sandboxing the entire Gemini CLI
process.
This approach offers better integration with your local environment for non-tool tasks (like UI rendering and configuration loading) while still providing security for tool-driven operations.
If you experience issues with tool sandboxing or prefer full-process isolation,
you can disable it by setting security.toolSandboxing to false in your
settings.json file.
{
"security": {
"toolSandboxing": false
}
}
[!NOTE] Changing the
security.toolSandboxingsetting requires a restart of Gemini CLI to take effect.
Sandbox expansion is a dynamic permission system that lets Gemini CLI request additional permissions for a command when needed.
When a sandboxed command fails due to permission restrictions (like restricted
file paths or network access), or when a command is proactively identified as
requiring extra permissions (like npm install), Gemini CLI will present you
with a "Sandbox Expansion Request."
This mechanism ensures you don't have to manually re-run commands with more permissive sandbox settings, while still maintaining control over what the AI can access.
By default, the sandbox only has access to the current project workspace. If you
need the sandbox to have permission to operate on certain files or directories
from the local file system outside of the project workspace, you can mount them
using the SANDBOX_MOUNTS environment variable.
Provide a comma-separated list of mount definitions in the format
from:to:opts. If to is omitted, it defaults to the same path as from. If
opts is omitted, it defaults to ro (read-only). Note that the from path
must be an absolute path.
Example:
export SANDBOX_MOUNTS="/path/on/host:/path/in/container:rw,/another/path:ro"
If you are running Gemini CLI itself from within an official or custom Docker container and want to enable sandboxing, you must share the host's Docker socket and ensure your workspace paths align.
/var/run/docker.sock so the CLI can spawn
sibling sandbox containers via the host's Docker daemon.Example:
docker run -it \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /absolute/path/on/host/project:/absolute/path/on/host/project \
-w /absolute/path/on/host/project \
-e GEMINI_SANDBOX=docker \
ghcr.io/google/gemini-cli:latest
For container-based sandboxing, you can inject custom flags into the docker or
podman command using the SANDBOX_FLAGS environment variable. This is useful
for advanced configurations, such as disabling security features for specific
use cases.
Example (Podman):
To disable SELinux labeling for volume mounts, you can set the following:
macOS/Linux
export SANDBOX_FLAGS="--security-opt label=disable"
Windows (PowerShell)
$env:SANDBOX_FLAGS="--security-opt label=disable"
Multiple flags can be provided as a space-separated string:
macOS/Linux
export SANDBOX_FLAGS="--flag1 --flag2=value"
Windows (PowerShell)
$env:SANDBOX_FLAGS="--flag1 --flag2=value"
The sandbox automatically handles user permissions on Linux. Override these permissions with:
macOS/Linux
export SANDBOX_SET_UID_GID=true # Force host UID/GID
export SANDBOX_SET_UID_GID=false # Disable UID/GID mapping
Windows (PowerShell)
$env:SANDBOX_SET_UID_GID="true" # Force host UID/GID
$env:SANDBOX_SET_UID_GID="false" # Disable UID/GID mapping
"Operation not permitted"
Missing commands
BUILD_SANDBOX builds are only
available when running Gemini CLI from source; npm installs need a prebuilt
image instead.sandbox.bashrc.Network issues
DEBUG=1 gemini -s -p "debug command"
[!NOTE] If you have
DEBUG=truein a project's.envfile, it won't affect gemini-cli due to automatic exclusion. Use.gemini/.envfiles for gemini-cli specific debug settings.
# Check environment
gemini -s -p "run shell command: env | grep SANDBOX"
# List mounts
gemini -s -p "run shell command: mount | grep workspace"