How to Fix Gemini CLI Sandboxing Permission Errors

Gemini CLI uses a sandbox system to protect your machine from potentially dangerous operations. While this security feature is valuable, it can sometimes block legitimate commands. This guide explains how to understand and resolve sandbox permission errors across different platforms.

Understanding Gemini CLI's Sandbox Model

Gemini CLI operates with a "safety-first" approach to command execution. Before running shell commands, modifying files, or accessing network resources, Gemini checks whether the operation falls within its allowed permissions.

The sandbox protects against:

• Destructive file operations: Deleting system files or important directories
• Sensitive directory access: Reading from .ssh, .aws, or other credential locations
• Elevated privilege commands: Operations requiring sudo or administrator rights
• Network operations: Outbound connections to unknown hosts
• System modifications: Changes to PATH, environment variables, or system configs

When Gemini encounters an operation outside its permissions, it prompts you to approve the action rather than blocking silently.

Common Sandbox Error Messages

Here are the most frequent sandbox errors and what they mean:

"Permission denied: Cannot execute command"

This error appears when Gemini tries to run a shell command it considers potentially dangerous.

Error: Permission denied
Cannot execute: rm -rf node_modules/
Reason: Recursive delete operations require explicit approval

Solution: Approve the command when prompted, or pre-configure the command in your allowed list.

"Directory access restricted"

Occurs when Gemini attempts to read or write outside allowed directories.

Error: Directory access restricted
Cannot access: /etc/nginx/nginx.conf
Reason: System configuration directories are protected

Solution: Add the directory to your allowedDirectories configuration.

"Network access blocked"

Appears when Gemini tries to make network requests to hosts not in the allowed list.

Error: Network access blocked
Cannot connect to: api.example.com
Reason: Host not in allowed network list

Solution: Add the host to your network allowlist or approve the connection when prompted.

Configuring Sandbox Permissions

Gemini CLI stores its configuration in a settings file. The location varies by platform:

• macOS/Linux: ~/.gemini/settings.json
• Windows: %USERPROFILE%\.gemini\settings.json

Basic Configuration Structure

{
  "sandbox": {
    "enabled": true,
    "allowedDirectories": [
      "~/projects",
      "~/code",
      "/tmp"
    ],
    "blockedDirectories": [
      "~/.ssh",
      "~/.aws",
      "~/.gnupg"
    ],
    "allowedCommands": [
      "git *",
      "npm *",
      "node *",
      "python *"
    ],
    "blockedCommands": [
      "rm -rf /",
      "sudo rm *",
      "chmod 777 *"
    ],
    "networkAllowlist": [
      "github.com",
      "npmjs.org",
      "*.googleapis.com"
    ]
  }
}

Adding Directory Permissions

To grant Gemini access to additional directories:

{
  "sandbox": {
    "allowedDirectories": [
      "~/projects",
      "~/code",
      "/var/www",
      "/opt/myapp"
    ]
  }
}

Use absolute paths or ~ for home directory expansion. Wildcards are supported for subdirectories.

Platform-Specific Sandbox Behaviors

macOS

macOS has additional security layers that interact with Gemini's sandbox:

• System Integrity Protection (SIP): Prevents modification of system directories regardless of Gemini settings
• Gatekeeper: May prompt for approval when Gemini first runs shell commands
• Privacy permissions: Access to Desktop, Documents, and Downloads requires explicit system approval

To grant file access permissions on macOS:

1. Open System Preferences (or System Settings on macOS 13+)
2. Navigate to Privacy & Security > Files and Folders
3. Find your terminal application and enable access to needed directories

Windows

Windows-specific considerations include:

• UAC (User Account Control): Commands requiring elevation always prompt
• Antivirus integration: Some security software may block Gemini's file operations
• Windows Defender: May flag Gemini's shell access as suspicious initially

To reduce friction on Windows:

1. Run your terminal as Administrator for elevated operations
2. Add Gemini's directory to Windows Defender exclusions if you experience slowdowns
3. Use absolute paths with forward slashes or escaped backslashes

Linux

Linux generally has the most permissive sandbox behavior, but SELinux or AppArmor can add restrictions:

• SELinux: May block operations in enforcing mode
• AppArmor: Ubuntu systems may have additional confinement
• File permissions: Standard Unix permissions still apply

Check SELinux status with getenforce and review /var/log/audit/audit.log for denied operations.

Using YOLO Mode Safely

YOLO mode (--yolo or -y) disables sandbox restrictions and auto-approves all commands. Use it only when:

• Working in isolated development containers
• Running in CI/CD pipelines with limited scope
• Performing trusted batch operations
• Testing in disposable environments

# Enable YOLO mode for a session
gemini --yolo "refactor all JavaScript files to TypeScript"

# Enable via environment variable
export GEMINI_YOLO_MODE=true
gemini "perform database migration"

Never use YOLO mode when:

• Working on production systems
• Accessing sensitive credentials or data
• Running untrusted prompts
• Operating in shared environments

Command Approval Workflows

When Gemini encounters a restricted operation, it presents an approval prompt:

Gemini wants to execute:
  rm -rf ./build/

Options:
  [y] Yes, allow this once
  [a] Always allow this command
  [n] No, deny this operation
  [e] Edit the command first

Best Practices for Command Approval

1. Review before approving: Read the full command, especially for destructive operations
2. Use "always allow" sparingly: Only for commands you run frequently and trust
3. Edit when uncertain: Modify commands to be more specific (e.g., add --dry-run)
4. Deny and rephrase: If a command looks wrong, deny it and ask Gemini to try a different approach

Troubleshooting Persistent Sandbox Issues

Reset Sandbox Configuration

If your settings become corrupted:

# Backup current settings
cp ~/.gemini/settings.json ~/.gemini/settings.json.backup

# Reset to defaults
rm ~/.gemini/settings.json
gemini --version  # Regenerates default config

Debug Mode for Permission Issues

Enable verbose logging to understand why operations are blocked:

gemini --debug "list files in /etc"

Review the output for lines containing sandbox or permission to identify the restriction.

Clear Cached Permissions

Gemini caches approval decisions. To clear them:

# Clear the approval cache
rm ~/.gemini/approvals.json

This forces Gemini to re-prompt for all operations.

Verify Settings File Syntax

Invalid JSON in your settings file causes Gemini to fall back to restrictive defaults:

# Validate JSON syntax
cat ~/.gemini/settings.json | python -m json.tool

Fix any syntax errors reported before restarting Gemini.

Next Steps

• Learn how to configure MCP integrations for extended capabilities
• Explore Vertex AI Enterprise setup for organizational use
• Read the official Gemini CLI documentation for advanced configuration options