gemini-sandbox-configuration
Central authority for Gemini CLI sandboxing and isolation. Covers Docker, Podman, macOS Seatbelt profiles, and security boundaries. Use when enabling sandboxing, choosing sandbox methods, configuring Seatbelt profiles, or troubleshooting sandbox issues. Delegates 100% to gemini-cli-docs for official documentation.
When & Why to Use This Skill
The Gemini Sandbox Configuration skill is a specialized tool designed to manage security boundaries and process isolation for the Gemini CLI. It provides comprehensive guidance on implementing sandboxing via Docker, Podman, and macOS Seatbelt profiles, ensuring that potentially hazardous operations are safely contained. By offering precise configuration steps for environment variables, settings files, and command-line flags, it helps developers and security operations teams maintain a secure execution environment while troubleshooting common isolation issues.
Use Cases
- Case 1: Enabling mandatory sandboxing for Gemini CLI operations to prevent unauthorized host system access during automated task execution.
- Case 2: Configuring macOS Seatbelt profiles to restrict network access and file system writes for specific processes using permissive or restrictive policies.
- Case 3: Setting up containerized isolation using Docker or Podman to ensure a consistent and clean execution environment across different operating systems.
- Case 4: Troubleshooting 'Operation not permitted' errors and debugging sandbox configurations to balance security requirements with functional needs.
| name | gemini-sandbox-configuration |
|---|---|
| description | Central authority for Gemini CLI sandboxing and isolation. Covers Docker, Podman, macOS Seatbelt profiles, and security boundaries. Use when enabling sandboxing, choosing sandbox methods, configuring Seatbelt profiles, or troubleshooting sandbox issues. Delegates 100% to gemini-cli-docs for official documentation. |
| allowed-tools | Read, Glob, Grep, Skill |
Gemini Sandbox Configuration
MANDATORY: Invoke gemini-cli-docs First
STOP - Before providing ANY response about Gemini sandboxing:
- INVOKE
gemini-cli-docsskill- 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
-sflag - 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"
Version History
- v1.1.0 (2025-12-01): Added Test Scenarios section
- v1.0.0 (2025-11-25): Initial release