Sandbox Containers

~16 min · gemini, sandbox, container, docker

Level 0🌱 Novice

0 XP0/70 lessons0/11 achievements

0/120 XP to next level120 XP to go0% complete

Container-based isolation by default

Gemini's sandbox is heavier than Claude Code's or Codex's — it's a real container (Docker / Podman) the agent runs inside. --sandbox spins up a container scoped to the working directory; the agent can write inside, but file changes only sync back when the session ends or on demand.

The trade: heavier setup (container runtime required) but real OS-level isolation. The agent literally cannot escape the container; nothing it does to /etc, ~/.ssh, or your filesystem outside the working directory matters.

Tool exclusion via -e: gemini --sandbox -e "WriteFile,RunShellCommand" disables specific tools even inside the container. Useful for "read-only audit" sessions even when the sandbox is on.

Code

Run in a sandbox·bash

# Default — no sandbox, agent runs in your shell
gemini

# Sandbox — Docker container
gemini --sandbox

# With tool exclusions even inside the sandbox
gemini --sandbox -e "WriteFile,RunShellCommand"

# Check container status
docker ps --filter "label=gemini.session"

# Configure default in settings
# ~/.gemini/settings.json
{ "sandbox": { "default": true, "image": "gemini-sandbox:latest" } }

Custom sandbox Dockerfile·dockerfile

FROM node:20-slim

# Pre-install tools the agent might need
RUN apt-get update && apt-get install -y --no-install-recommends \
      git curl ripgrep jq python3 \
    && rm -rf /var/lib/apt/lists/*

# Pre-install Gemini's expected runtime
RUN npm install -g @google/gemini-cli

# Non-root user for additional safety
RUN useradd -m -s /bin/bash agent
USER agent
WORKDIR /workspace

ENTRYPOINT ["gemini"]

External links

Gemini sandbox docs

Exercise

Run a Gemini session inside the sandbox container. Try to do something destructive (write to ~/.ssh, modify /etc) — confirm it's blocked. Build a custom sandbox image with the tools you usually need.