PR #25930: (docs) update sandboxing documentation

• Repository: google-gemini/gemini-cli
• Author: g-samroberts
• State: open | merged: False
• Link: https://github.com/google-gemini/gemini-cli/pull/25930

Description (problem / solution / changelog)

Update sandbox documentation for Docker container workflows and other details

Summary

This PR expands and reorganizes the docs/cli/sandbox.md documentation to provide clearer, more sequential instructions for users utilizing container-based (Docker/Podman) sandboxing. It addresses common user questions regarding workspace path resolution, custom image configuration (such as Artifact Registry), and nested Docker setups.

Resolves #25929

Changes

• Reorganized document structure: Moved the "Quickstart" and general configuration sections to the top for a better "Bottom Line Up Front" (BLUF) reading flow. Grouped advanced settings and profile configurations together at the bottom.
• Expanded Docker/Podman instructions:
  • Added a "How it works" section explicitly clarifying that the local host workspace directory is mounted to the exact same absolute path inside the sandbox container.
  • Added detailed instructions for configuring custom sandbox images (e.g., from Artifact Registry) via settings.json and the GEMINI_SANDBOX_IMAGE environment variable.
  • Clarified the workflow for automatically building local images using .gemini/sandbox.Dockerfile and the BUILD_SANDBOX=1 environment variable.
• Documented sandbox expansion:
  • Added instructions on using the SANDBOX_MOUNTS environment variable to mount additional files or directories outside the project workspace into the sandbox.
• Formatting: Ran npm run format to ensure adherence to Markdown and Prettier guidelines.

Validation

• Manually reviewed the updated markdown for clarity, tone, and accuracy against the sandbox implementation.
• Verified that npm run format successfully passed.

Changed files

• docs/cli/sandbox.md (modified, +162/-45)