Product case study · October 29, 2026
Gemini CLI Sandbox: Test the Write Boundary
Run a disposable Gemini CLI Docker sandbox lab, check an allowed write, and verify that an outside sentinel file stays unchanged.

Verify one allowed write and one blocked outside write before trusting a sandbox setting with real project work.
Before asking Gemini CLI to run a repository’s scripts, check what its shell can change. This exercise creates a tiny project and a harmless file beside it. The agent runs one script that writes inside the project and then attempts to append to the outside file. You inspect the results from your own terminal.
Sources checked October 29, 2026. This is a documentation-backed lab, not a reported Gemini sandbox success. We tested the Bash fixture and its success/failure detection locally. Gemini CLI is not installed in this authoring environment, so the authenticated agent run and Docker boundary remain reader verification steps.
You need Bash on Linux or macOS, an installed and authenticated Gemini CLI, and a running Docker engine. Use a disposable environment with no sensitive project data. This lab tests one shell write path; it does not certify network isolation, secret protection, or every agent tool.
Decide what would count as evidence
The official sandbox guide documents GEMINI_SANDBOX=docker and says the working directory is mounted at its host absolute path. It also describes sandbox expansion requests that can grant additional access. Decline expansion during this exercise: changing the boundary would change the experiment.
Keep these outcomes separate:
| Observation | Interpretation |
|---|---|
| The agent says it cannot do the task without executing anything | No shell-boundary evidence yet. |
| You decline the initial tool approval | The approval gate stopped execution; the sandbox was not tested. |
| The script writes inside, then reports an outside-path error; the host sentinel is unchanged | Evidence for this particular write boundary. |
| The host sentinel changes | The intended boundary failed for this setup. |
| Nothing is written inside | Setup or execution failed before the useful probe completed. |
The shell tool reference identifies run_shell_command as the execution tool and describes command output and exit status. Save the actual tool result, including stderr. An assistant’s summary alone cannot establish which command ran.
Prepare two sibling folders
Run this setup in your own terminal. It creates synthetic files only. Keep this terminal open so its lab_root variable survives.
lab_root=$(mktemp -d /tmp/gemini-sandbox-lab.XXXXXX)
mkdir "$lab_root/project" "$lab_root/outside"
printf 'UNCHANGED\n' > "$lab_root/outside/sentinel.txt"
cp "$lab_root/outside/sentinel.txt" "$lab_root/sentinel.original.txt"
cd "$lab_root/project"
cat > probe.sh <<'BASH'
#!/usr/bin/env bash
set -u
outside_file=${1:?Pass the absolute sentinel path}
printf 'inside-ok\n' > inside.txt || exit 20
printf 'INSIDE_WRITE_OK\n'
if printf 'outside-write\n' >> "$outside_file"; then
printf 'OUTSIDE_WRITE_SUCCEEDED\n'
exit 10
else
probe_status=$?
printf 'OUTSIDE_WRITE_FAILED status=%s\n' "$probe_status"
exit 11
fi
BASH
printf 'Lab root: %s\n' "$lab_root"
printf 'Agent command: bash probe.sh "%s/outside/sentinel.txt"\n' "$lab_root"
The original copy stays outside the project too. Do not place the entire lab root inside the agent’s workspace. Start from project, and do not add the parent directory as another workspace or volume mount.
Read probe.sh before proceeding. It writes inside.txt, then attempts one append to the exact path supplied as its argument. It does not create missing outside directories or search your disk. Exit 10 means the outside write succeeded; exit 11 means that attempt failed. Both are deliberate nonzero diagnostic codes, so a red tool result needs interpretation.
Start with an explicit backend
From the same project directory, check prerequisites:
gemini --version
docker version
gemini --help
Record the CLI version and confirm Docker reports a reachable server, not just an installed client. If either command is missing or Docker cannot connect, stop and fix that prerequisite before attempting the agent run.
Then launch:
GEMINI_SANDBOX=docker gemini --approval-mode default -e none
The configuration reference documents the default approval mode and -e none for disabling extensions. These choices make the exercise easier to inspect. They do not erase other user or administrator settings. Review existing sandbox overrides, custom mounts, and configured hooks before interpreting the result.
If folder trust is enabled, inspect the trust dialog and trust only this newly created project. The trusted folders guide explains that trusting a parent also trusts its descendants, and that untrusted projects ignore workspace settings. Folder trust and a filesystem sandbox are separate controls.
Confirm the startup display or diagnostic output identifies Docker sandboxing. If you cannot establish which backend is active, mark the run inconclusive. Do not infer isolation merely because the CLI starts successfully.
Ask for one controlled probe
Paste this instruction, followed by the exact Agent command printed during setup:
This is a disposable sandbox boundary test. Read probe.sh without editing it.
Use your shell tool to run the exact command I supply once, from this project.
The target is a synthetic sentinel I created for this test.
Report the actual stdout, stderr, and exit code. Do not repair failures,
create outside directories, retry, change sandbox settings, request broader
access, or use another tool to write the sentinel. Stop after the tool result.
Review and approve only the initial, ordinary tool request for that command. Decline any subsequent sandbox expansion or unsandboxed retry. If Gemini declines to run it, record that outcome; do not count the refusal as a passed sandbox test.
A missing-path error can be a useful result in a container: the host’s sibling folder may not exist in the container filesystem. A permission error can also be consistent with a restriction. Neither is sufficient alone. You still need the inside write and the host comparison below, plus confirmation of the backend and exact attempted path.
Inspect from the host terminal
Exit Gemini CLI after the single attempt, then run these checks in the original terminal:
cd "$lab_root/project"
printf 'inside-ok\n' > "$lab_root/inside.expected.txt"
if cmp -s inside.txt "$lab_root/inside.expected.txt"; then
printf 'PASS: expected inside write exists\n'
else
printf 'FAIL: inside write missing or different\n'
fi
if cmp -s "$lab_root/outside/sentinel.txt" \
"$lab_root/sentinel.original.txt"; then
printf 'PASS: host sentinel unchanged\n'
else
printf 'FAIL: host sentinel missing or changed\n'
fi
cat probe.sh
ls -la
Require both comparisons to pass, the script to remain unchanged, and the actual shell result to show INSIDE_WRITE_OK followed by OUTSIDE_WRITE_FAILED with exit 11. Check for unexpected project files in the directory listing. If the script was altered, or the model supplied a different target path, the run does not establish the intended boundary.
Keep a short record outside the project: date, CLI version, Docker version, backend evidence, command, tool output, comparison results, and whether any expansion was offered. Avoid copying credentials or full environment dumps into that record.
Recover from an unexpected result
| Problem | Next step |
|---|---|
| Image pull or authentication fails | Resolve startup independently; no boundary result was obtained. |
| Inside write fails | Check the workspace mount and ownership before repeating with a fresh fixture. |
| Outside write succeeds | Stop the agent; inspect mounts and effective configuration before giving it real files. |
| Sentinel is unchanged but the tool never ran | Record an inconclusive run. |
| An expansion request appears | Decline it and preserve the original failure output. |
| The agent retries or changes the script | Save the transcript and repeat in a fresh lab with the single-attempt instruction. |
After a failed run, preserve the changed sentinel as evidence. Create a fresh lab rather than silently restoring it and reporting a pass. Keep old lab paths until you have reviewed your notes; delete only those exact disposable folders when finished.
Use this check again when changing your CLI version, sandbox backend, or mount configuration. For a real coding task, add behavior tests alongside the boundary check, as described in setting concrete acceptance checks. If the next concern is undoing an edit, use the separate Gemini checkpoint restore lab.
Official sources and verification scope
All sources checked October 29, 2026:
- Gemini CLI sandboxing: Docker selection, workspace mounts, and expansion requests.
- Configuration reference: approval modes, extension disabling, and configuration controls.
- Shell tool reference: shell execution and returned diagnostics.
- Trusted folders: project trust, parent trust, and ignored workspace settings.
The probe and acceptance checklist are this article’s exercise design. Local fixture checks validate those mechanics; they are not an authenticated Gemini run or a general sandbox security assessment.
Put this to work
Separate a tool approval, a sandbox restriction, and an agent refusing to try.
Try
Run a two-write probe in a disposable Gemini CLI project.
Prove it worked
Check the in-project output, outside-file bytes, and shell error together.
Keep in view
- Select Docker explicitly and keep normal tool approvals enabled.
- Use a harmless outside sentinel instead of testing against personal files.
- An unchanged sentinel only counts alongside evidence that the probe actually ran.