melodic-software/gemini-sandbox-configuration

Gemini Sandbox Configuration

MANDATORY: Invoke gemini-cli-docs First

STOP - Before providing ANY response about Gemini sandboxing:

1. INVOKE gemini-cli-docs skill
2. QUERY for the specific sandbox topic
3. 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?

1. Enable sandbox quickly -> Use -s flag
2. Make it persistent -> Add to settings.json
3. Use Docker -> Set GEMINI_SANDBOX=docker
4. Use stricter macOS -> Set SEATBELT_PROFILE=restrictive-closed
5. 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

1. Parse Arguments - Extract the shell command from $ARGUMENTS. If no command provided, ask the user what to execute in sandbox.
2. Validate Command - Ensure the command is non-empty and reasonable for sandboxed execution.
3. Execute in Sandbox - Run the command using Gemini CLI's -s flag for sandbox enforcement with appropriate sandbox type (Docker, Podman, or macOS Seatbelt).
4. 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