Gemini Sandbox Configuration

MANDATORY: Invoke gemini-cli-docs First

STOP - Before providing ANY response about Gemini sandboxing:

• INVOKE gemini-cli-docs skill

• QUERY for the specific sandbox topic

• BASE responses EXCLUSIVELY on official documentation loaded

Overview

Meta-skill for configuring Gemini CLI's sandbox isolation. Sandboxing isolates potentially dangerous operations from your host system.

When to Use This Skill

Keywords: sandbox, docker, podman, seatbelt, isolation, container, safe execution, -s flag, GEMINI_SANDBOX

Use this skill when:

• Enabling sandboxing for the first time

• Choosing between sandbox methods

• Configuring Seatbelt profiles (macOS)

• Troubleshooting sandbox issues

• Understanding security boundaries

Sandbox Methods

Method Platform Isolation

Docker All Full container

Podman All Rootless container

Seatbelt macOS Process sandbox

Configuration

Enable via Command Flag

gemini -s -p "command"

Enable via Environment

export GEMINI_SANDBOX=true gemini "command"

Or specify method

export GEMINI_SANDBOX=docker export GEMINI_SANDBOX=podman export GEMINI_SANDBOX=sandbox-exec

Enable via Settings

Add to settings.json :

{ "tools": { "sandbox": true } }

Or specify method:

{ "tools": { "sandbox": "docker" } }

Seatbelt Profiles (macOS)

Set via SEATBELT_PROFILE environment variable:

Profile Writes Network

permissive-open (default) Restricted Allowed

permissive-closed

Restricted Blocked

permissive-proxied

Restricted Via proxy

restrictive-open

Strict Allowed

restrictive-closed

Strict Blocked

Custom Sandbox Flags

For container-based sandboxing, inject custom flags:

export SANDBOX_FLAGS="--security-opt label=disable"

Keyword Registry (Delegates to gemini-cli-docs)

Topic Query Keywords

Enable enable sandbox , -s flag , GEMINI_SANDBOX

Docker docker sandbox , container isolation

Podman podman sandbox , rootless container

Seatbelt seatbelt profiles , sandbox-exec macos

Custom flags SANDBOX_FLAGS , custom docker flags

Troubleshooting sandbox troubleshooting , operation not permitted

Quick Decision Tree

What do you want to do?

• Enable sandbox quickly -> Use -s flag

• Make it persistent -> Add to settings.json

• Use Docker -> Set GEMINI_SANDBOX=docker

• Use stricter macOS -> Set SEATBELT_PROFILE=restrictive-closed

• Debug issues -> Use DEBUG=1 gemini -s

Troubleshooting

Error Cause Solution

"Operation not permitted" Sandbox restriction Expected behavior

"Docker not found" Docker not running Start Docker daemon

Network blocked Restrictive profile Use permissive-open

Missing commands Not in sandbox image Add to custom Dockerfile

Security Notes

• Sandboxing reduces but doesn't eliminate all risks

• Use most restrictive profile that allows your work

• GUI applications may not work in sandbox

• Container overhead is minimal after first build

Verification Checkpoint

• Did I invoke gemini-cli-docs skill?

• Did official documentation load?

• Is my response based EXCLUSIVELY on official docs?

Test Scenarios

Scenario 1: Enable Sandbox

Query: "How do I enable sandboxing in Gemini CLI?" Expected Behavior:

• Skill activates on "sandbox" keyword

• Delegates to gemini-cli-docs for configuration options Success Criteria: User receives -s flag and settings.json configuration

Scenario 2: macOS Seatbelt

Query: "How do I configure Seatbelt profiles for Gemini CLI?" Expected Behavior:

• Skill activates on "seatbelt" or "macos sandbox"

• Provides SEATBELT_PROFILE environment variable options Success Criteria: User receives profile comparison table

Scenario 3: Troubleshoot Sandbox

Query: "Getting 'operation not permitted' in Gemini sandbox" Expected Behavior:

• Skill activates on "sandbox troubleshooting" or "operation not permitted"

• Explains expected sandbox restrictions Success Criteria: User understands behavior is expected and gets workarounds

References

Query gemini-cli-docs for official documentation on:

• "sandbox"

• "seatbelt profiles"

• "docker sandbox"

User-Facing Interface

When invoked directly by the user, this skill executes a command in Gemini CLI's sandboxed environment.

Execution Workflow

• Parse Arguments - Extract the shell command from $ARGUMENTS . If no command provided, ask the user what to execute in sandbox.

• Validate Command - Ensure the command is non-empty and reasonable for sandboxed execution.

• Execute in Sandbox - Run the command using Gemini CLI's -s flag for sandbox enforcement with appropriate sandbox type (Docker, Podman, or macOS Seatbelt).

• Report Results - Present execution output including stdout, stderr, exit code, and observations about command behavior in the sandboxed environment.

Version History

• v1.1.0 (2025-12-01): Added Test Scenarios section

• v1.0.0 (2025-11-25): Initial release