Skip to main content
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.

​
Benefits of Sandboxing

Security

Prevent accidental system damage or data loss from AI-generated commands.

Isolation

Limit file system access to the project directory only.

Consistency

Ensure reproducible environments across different systems.

Safety

Reduce risk when working with untrusted code or experimental commands.
Sandboxing reduces but does not eliminate all risks. Always use the most restrictive profile that allows your work.

​
Prerequisites

Before using sandboxing, install and verify Gemini CLI: 
npm install -g @google/gemini-cli
gemini --version

​
Sandboxing Methods

Choose the method that best fits your platform and container solution.

​
macOS Seatbelt (macOS only)

Lightweight, built-in sandboxing using sandbox-exec.Default Profile: permissive-open
  • Restricts writes outside project directory
  • Allows most other operations
  • No additional installation required
Pros:
  • Native macOS integration
  • No container overhead
  • Fast startup
Cons:
  • macOS only
  • Less isolation than containers

​
Quickstart

​
Command Flag

Enable sandboxing for a single session: 
gemini -s -p "analyze the code structure"
or 
gemini --sandbox -p "run the test suite"

​
Environment Variable

export GEMINI_SANDBOX=true
gemini -p "run the test suite"
Valid values:
  • true - Auto-detect method
  • docker - Use Docker
  • podman - Use Podman
  • sandbox-exec - Use macOS Seatbelt

​
Settings File

Enable permanently in settings.json: 
{
  "tools": {
    "sandbox": "docker"
  }
}
or simply: 
{
  "tools": {
    "sandbox": true
  }
}

​
Configuration

​
Precedence Order

Settings are applied in this order (highest to lowest priority):
  1. Command flag: -s or --sandbox
  2. Environment variable: GEMINI_SANDBOX=true|docker|podman|sandbox-exec
  3. Settings file: "sandbox": true in tools object

​
macOS Seatbelt Profiles

Set profile via SEATBELT_PROFILE environment variable:
  • Write restrictions outside project
  • Network allowed
  • Good for general development
  • Write restrictions outside project
  • Network via proxy only
  • Use when you need proxy control
  • Strict restrictions on file operations
  • Network allowed
  • Recommended for untrusted code
  • Strict restrictions on file operations
  • Network via proxy only
  • High security with proxy control
  • Read and write restrictions
  • Network allowed
  • Maximum file safety
  • Read and write restrictions
  • Network via proxy only
  • Maximum security
Usage: 
export SEATBELT_PROFILE=restrictive-open
gemini -s

​
Custom Sandbox Flags

Inject custom flags into docker or podman commands using SANDBOX_FLAGS. 
export SANDBOX_FLAGS="--security-opt label=disable"
Example Use Cases:
  • Disable SELinux labeling (Podman)
  • Add volume mounts
  • Configure network settings
  • Set resource limits

​
Linux UID/GID Handling

The sandbox automatically handles user permissions on Linux. Override with: 
export SANDBOX_SET_UID_GID=true

​
Troubleshooting

Cause: Operation requires access outside sandbox boundaries.Solutions:
  • Try a more permissive profile (e.g., permissive-open instead of strict-open)
  • Add mount points for required directories
  • Check if the operation is necessary for your use case
Cause: Command not installed in sandbox environment.Solutions:
  • Add to custom Dockerfile for container-based sandboxing
  • Install via sandbox.bashrc configuration
  • Verify the command is available on the host
Cause: Sandbox profile blocks network or proxy misconfiguration.Solutions:
  • Verify profile allows network (e.g., -open profiles)
  • Check proxy configuration if using -proxied profiles
  • Test network connectivity: gemini -s -p "run shell command: ping -c 1 google.com"
Cause: UID/GID mismatch between host and container.Solutions:
  • Set SANDBOX_SET_UID_GID=true to force host UID/GID
  • Check file ownership on host
  • Verify container user has correct permissions
Cause: Container runtime not available or misconfigured.Solutions:
  • Verify Docker/Podman is installed: docker --version or podman --version
  • Check container service is running
  • Build sandbox image if using custom image
  • Try different sandbox method: GEMINI_SANDBOX=sandbox-exec (macOS)

​
Debug Mode

Enable detailed logging for troubleshooting: 
DEBUG=1 gemini -s -p "debug command"
If you have DEBUG=true in a project’s .env file, it won’t affect Gemini CLI due to automatic exclusion. Use .gemini/.env files for Gemini CLI-specific debug settings.

​
Inspect Sandbox Environment

gemini -s -p "run shell command: env | grep SANDBOX"

​
Use Cases

Untrusted Code

Run and test code from unknown sources without risking your system.

Experimental Commands

Try potentially destructive commands safely in isolation.

Production Testing

Test deployment scripts without affecting production environments.

CI/CD Integration

Consistent, isolated environments for automated workflows.

​
Security Notes

Important Security Considerations:
  • Sandboxing reduces but does not eliminate all risks
  • Use the most restrictive profile that allows your work
  • Container overhead is minimal after first build
  • GUI applications may not work in sandboxes
  • Network isolation varies by profile—choose carefully
  • Always review AI-generated commands before approval, even in sandbox

​
Configuration Examples

​
Basic Docker Sandbox

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

​
Restrictive macOS Setup

export SEATBELT_PROFILE=restrictive-proxied
export GEMINI_SANDBOX=sandbox-exec
gemini

​
Custom Podman with Security Options

export GEMINI_SANDBOX=podman
export SANDBOX_FLAGS="--security-opt label=disable --memory=2g"
gemini -p "analyze project"

​
Development Setup with UID Mapping

export GEMINI_SANDBOX=docker
export SANDBOX_SET_UID_GID=true
gemini

Configuration

Full configuration options for Gemini CLI

Commands

Available slash commands and usage

Checkpointing

Combine with checkpoints for double safety

​
Next Steps

Enable Sandboxing

Choose your method and add to settings.json

Test Your Setup

Run a simple command to verify: gemini -s -p "run shell command: echo test"

Build docs developers (and LLMs) love

Get started for freeTalk to us