Sandbox & Docker Execution

Gemini CLI can run shell commands on your machine. That's powerful, and also terrifying if you're asking it to run code you don't fully trust. The --sandbox flag puts Gemini CLI inside a Docker or Podman container, isolating every command from your host filesystem. This lesson covers how to set it up, when to use it, and the pre-built sandbox images that come with common tools pre-installed.

What you'll learn

• gemini --sandbox runs Gemini CLI inside an isolated Docker/Podman container -- file edits and commands can't touch your host
• Pre-built sandbox images include common dev tools (Python, Node, Git, curl). You can also build custom images
• --sandbox -y -p "prompt" is the safe one-shot pattern for running untrusted or experimental code
• Sandbox mode requires Docker or Podman installed and running. Docker Desktop, docker-ce, or podman all work
• Migration note: Sandbox mode is available on both Gemini CLI and Antigravity CLI with identical flags

The problem

You ask Gemini CLI to install a package and run a script. It does, and the script works. But what if the script had a bug that deleted files, or the package had a post-install hook you didn't read? The default mode trusts the agent with your filesystem. Sandbox mode doesn't: every command runs inside a container, and the worst-case scenario is a destroyed container, not a destroyed home directory. The cost is a Docker dependency and a slightly slower startup.

Options & when to use each

Mode	Command	Good for	When to pick it
Host mode (default)	gemini	Working on code in your own project, editing files you trust, running commands you'd run yourself	You're working on your own codebase and trust what the agent does
Sandbox one-shot	gemini --sandbox -y -p "prompt"	Running untrusted code, testing install scripts, experimenting with unfamiliar packages	You're asking Gemini CLI to install something or run generated code you haven't reviewed
Sandbox interactive	gemini --sandbox	Exploring a codebase you don't trust, or complete isolation during a debugging session	You want the full REPL experience but with filesystem isolation
Custom sandbox image	gemini --sandbox --image my-image	Projects with specific tooling that isn't in the default sandbox	You need Python 3.12, a specific Rust toolchain, or any dependency not in the base image

The default is host mode. Use sandbox mode when the task involves code you haven't reviewed, packages you're trying for the first time, or anything that could modify files outside your project directory.

Build it

Step 1: Install Docker or Podman

If you already have Docker or Podman, skip to Step 2. If not:

On Ubuntu/Debian (Docker):

# Install Docker Engine
sudo apt-get update
sudo apt-get install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to the docker group (avoids sudo for every command)
sudo usermod -aG docker $USER
# Log out and back in for the group change to take effect

On macOS (Docker Desktop):

brew install --cask docker
# Open Docker Desktop from Applications, accept the license, wait for engine to start

On WSL (Docker Desktop or Podman):

Docker Desktop for Windows integrates with WSL2 automatically. Install it on the Windows host, then enable WSL integration in Docker Desktop settings.

Or use Podman, which runs natively in WSL:

sudo apt-get update
sudo apt-get install -y podman

Verify the install:

Run a test container to confirm the runtime is functioning correctly.

docker run hello-world    # if using Docker
# or
podman run hello-world    # if using Podman

If you see "Hello from Docker!" (or the Podman equivalent), the container runtime is working.

Step 2: Run your first sandbox session

Execute a sandboxed one-shot prompt to safely run external code. The agent will spin up an isolated container for the task.

gemini --sandbox -y -p "Create a Python script that fetches the current Bitcoin price from the CoinDesk API and prints it. Save it as /tmp/btc.py and run it."

Gemini CLI starts a container with a pre-built sandbox image, creates the script inside the container, runs it, and prints the result. The container is destroyed when the session ends. The script never touches your host filesystem.

If this is your first sandbox run, Gemini CLI pulls the sandbox image from the registry. This takes a minute and only happens once per image version.

Step 3: Understand what sandbox mode isolates

Sandbox mode creates a container with its own filesystem. Key behaviors:

• File system: Reads and writes happen inside the container. /tmp inside the container is not your host's /tmp. To get files out, Gemini CLI copies them to your host at session end.
• Network: The container has network access (it can pip install and call APIs), but it can't reach services bound to localhost on your host unless you configure port mapping.
• Process isolation: A kill -9 in the container kills processes inside the container, not your host processes. A fork bomb fills the container's process limit, not your host's.
• Session lifetime: The container is created when the session starts and destroyed when it ends. No state persists between sandbox sessions by default.

Step 4: Build a custom sandbox image

The default sandbox image has Python, Node, Git, curl, and basic build tools. If your project needs more, build a custom image.

Create a Dockerfile:

Write a custom image definition that includes the required dependencies and tools for your project.

FROM gemini-cli-sandbox:latest

# Add project-specific dependencies
RUN apt-get update && apt-get install -y \
    postgresql-client \
    redis-tools \
    && rm -rf /var/lib/apt/lists/*

# Install Python packages
RUN pip install sqlalchemy redis pytest-mock

# Set a working directory
WORKDIR /workspace

Build and use it:

Build the custom container image locally. Then, pass the image flag to the CLI so the sandbox utilizes your specific environment.

docker build -t my-sandbox .
gemini --sandbox --image my-sandbox -y -p "Connect to the Redis instance and list all keys"

The --image flag tells Gemini CLI to use your custom image instead of the default.

Step 5: When NOT to use sandbox mode

Sandbox mode isn't always the right choice:

• Working on your own project with files you need to keep. Sandbox mode isolates files. Edits to your project files inside the sandbox don't persist unless you explicitly copy them out. For day-to-day development on your own code, host mode is more practical.
• Accessing local services. If your project connects to a database or API running on your host, sandbox mode can't reach localhost without additional configuration.
• Speed-critical workflows. Sandbox mode adds container startup time (1-3 seconds for Docker, faster for Podman). For rapid back-and-forth tasks, the overhead adds up.

Use sandbox mode for: running untrusted code, testing install scripts, experimenting with unfamiliar packages, and any prompt that involves rm -rf or sudo.

What goes wrong

Mistake	How you notice it	The fix
Docker not running	gemini --sandbox fails with "cannot connect to Docker daemon"	Start Docker (sudo systemctl start docker on Linux, open Docker Desktop on macOS/Windows). On Linux, make sure your user is in the docker group
Sandbox image pull fails	"Error pulling image" or timeout	Check your internet connection. If behind a corporate proxy, configure Docker's proxy settings in ~/.docker/config.json
Files created in sandbox are gone after session	You cat /tmp/output.txt on your host and the file doesn't exist	Sandbox files are ephemeral. To persist output, ask Gemini CLI to cat the file to stdout and redirect, or use host mode for file-based work
Sandbox can't reach localhost services	You try to connect to http://localhost:3000 from inside the sandbox and it fails	Inside a container, localhost is the container's loopback, not the host's. Use host.docker.internal (Docker) or host.containers.internal (Podman) instead
Custom image missing expected tools	pip install or npm install fails inside the sandbox	Check your Dockerfile. The base sandbox image may have a different package set than you expect. Test the image with docker run -it my-sandbox /bin/bash before using it with Gemini CLI
Forgetting to use --yolo with --sandbox	Sandbox session still asks for confirmation on every command	--sandbox isolates execution but doesn't auto-approve. Add -y (short for --yolo) for no-confirmation execution: gemini --sandbox -y -p "..."

Confirm it worked

Run this sequence. If every step succeeds, sandbox mode is working:

# 1. Verify Docker/Podman is running
docker ps    # or podman ps

# 2. Run a sandboxed one-shot
gemini --sandbox -y -p "Install the 'cowsay' package using apt-get, then run 'cowsay Sandbox mode works' and show me the output"

# 3. Verify the command ran in isolation (host should not have cowsay)
which cowsay 2>/dev/null && echo "cowsay found on host -- isolation failed?" || echo "cowsay not on host -- isolation worked"

# 4. Try an interactive sandbox session (exit with Ctrl+C)
gemini --sandbox -p "What OS is this container running? Use cat /etc/os-release"

If step 2 shows a cow saying "Sandbox mode works" and step 3 confirms cowsay isn't on your host, sandbox isolation is working correctly. The container was created, used, and destroyed -- your host is untouched.

Next: Day 2 -- Gemini CLI: Advanced Features