Gemini CLI sandbox setup using rootless podman

GEMINI_CLI_SANDBOX_SETUP_GUIDE.md

This guide teaches how to setup Gemini CLI sandbox on Linux without requiring root permission. Giving it Docker access is same as root access since it can bindmount anything.

1. Rootless Podman setup

Follow the official guide here, https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md.

TLDR version on ubuntu

# Install podman + dependencies
# 'passt' provides 'pasta' (default network tool since Podman 5.0)
# 'uidmap' provides newuidmap/newgidmap
# fuse-overlayfs is a fallback; native overlayfs works on Ubuntu 24.04 + kernel 5.12+
sudo apt-get update
sudo apt-get install -y podman passt uidmap

# Set up subuid/subgid ranges for your user (run with sudo)
sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $(whoami)

# Verify
grep $(whoami) /etc/subuid /etc/subgid

# If you already had podman running, migrate after subuid/subgid changes
podman system migrate

# Enable linger so user containers survive logout (optional)
sudo loginctl enable-linger $(whoami)

# Test
podman run --rm hello-world

# Run interactively
podman run -it --rm ubuntu bash

# Keep host UID inside container (useful for volume mounts)
podman run -it --rm --userns=keep-id ubuntu bash

2. Gemini CLI settings

Add the following into your ~/.gemini/.env, and then restart all running Gemini CLI instances.

GEMINI_SANDBOX=podman
SANDBOX_SET_UID_GID=true
SANDBOX_FLAGS='--userns=keep-id --security-opt=label=disable'

3. Done