Gemini Sandbox Configuration Skill

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

Agent Skills: Gemini Sandbox Configuration

Install this agent skill to your local

Skill Files