Gemini CLI Sandbox Mode
Run AI-assisted code execution in a secure, isolated environment. Sandbox mode gives you full control over file access, network connectivity, and system commands so you can use Gemini CLI confidently on production codebases, shared servers, and CI/CD pipelines.
What is Sandbox Mode?
Sandbox mode is Gemini CLI's built-in security layer that creates an isolated execution environment for every AI-generated action. When sandbox mode is active, Gemini CLI cannot read, write, or delete files outside of directories you explicitly allow. It cannot make network requests to domains you have not approved. And it cannot run shell commands that fall outside your configured permission set.
This isolation is essential in several scenarios. If you are working with untrusted prompts from external sources, the sandbox prevents malicious instructions from accessing sensitive files or exfiltrating data. In shared development environments where multiple engineers use the same server, sandbox mode ensures that one developer's Gemini CLI session cannot interfere with another's files or processes. And in CI/CD pipelines, sandbox mode guarantees that AI-assisted steps cannot modify build artifacts, environment variables, or deployment configurations beyond what you intend.
Think of sandbox mode as a security perimeter around Gemini CLI. Everything the AI wants to do must pass through the sandbox's access control checks first. If the action violates your policy, it is blocked immediately and logged for your review. This gives you the productivity benefits of AI-assisted coding without sacrificing control over your environment.
How the Sandbox Works
The sandbox enforces security through four independent layers of isolation. Each layer operates independently, so a misconfiguration in one layer does not compromise the others. This defense-in-depth approach ensures robust protection even in complex environments.
File System Isolation
The sandbox restricts Gemini CLI to only the directories you specify. By default, it can access the current working directory and nothing else. You can expand access by adding paths to the allowlist, or narrow it further by blocking specific subdirectories. Any attempt to read, write, or traverse outside the allowed paths is blocked and recorded in the sandbox log.
Network Restrictions
Network access is fully configurable. You can block all outbound connections, allow connections only to specific domains, or route traffic through a corporate proxy. This prevents AI-generated code from making unexpected API calls, downloading dependencies from untrusted sources, or sending data to external endpoints without your knowledge.
Command Execution Controls
The sandbox governs which shell commands Gemini CLI can execute. You define an allowlist of permitted commands, and any command not on the list is rejected. This prevents the AI from running destructive operations like rm -rf, modifying system configurations, or installing packages without your approval.
Resource Limits
The sandbox can enforce CPU and memory limits on processes spawned by Gemini CLI. This prevents runaway scripts from consuming all available resources on your machine or build server. You can set maximum execution time, memory usage, and the number of concurrent processes the AI is allowed to spawn.
Enabling Sandbox Mode
There are three ways to enable sandbox mode depending on whether you want it for a single command, all sessions, or as a project-level default. Each method gives you the same security guarantees with different levels of permanence.
Per-Command Sandbox
Add the --sandbox flag to any Gemini CLI command. The sandbox is active only for that single execution and uses default restrictions.
# Run a single command in sandbox mode
gemini --sandbox "Analyze this code for security vulnerabilities"
# Sandbox with a specific task
gemini --sandbox "Refactor the auth module to use bcrypt"
Global Sandbox
Enable sandbox mode for all Gemini CLI sessions on your machine. This is recommended for shared servers and environments where security is a priority.
# Enable sandbox globally
gemini config set sandbox.enabled true
# Verify the setting
gemini config get sandbox.enabled
# Output: true
Project Configuration File
Define sandbox settings in your project's .gemini/settings.json file. This approach lets you commit security policies alongside your code so every team member uses the same sandbox configuration.
// .gemini/settings.json
{
"sandbox": {
"enabled": true,
"allowPaths": ["./src", "./tests", "./docs"],
"blockPaths": [".env", "credentials/", ".ssh/"],
"network": false,
"allowCommands": ["node", "npm", "npx", "git"]
}
}
File Access Controls
Fine-grained file access controls let you specify exactly which parts of your project Gemini CLI can interact with. You can combine allowlists, blocklists, and read-only mode to create a security policy that matches your workflow.
Allowlist: Permitted Directories
The allowPaths setting defines which directories Gemini CLI can access. Only these paths and their subdirectories are visible to the AI. Everything else is completely hidden.
// Only allow access to source and test directories
{
"sandbox": {
"allowPaths": ["./src", "./tests", "./package.json"]
}
}
Blocklist: Restricted Paths
The blockPaths setting explicitly denies access to specific files or directories, even if they fall within an allowed path. Blocklist rules always take precedence over allowlist rules.
// Block sensitive files even within allowed directories
{
"sandbox": {
"allowPaths": ["./"],
"blockPaths": [".env", ".env.local", "credentials/", "secrets/", "*.pem", "*.key"]
}
}
Read-Only Mode
Enable readOnly to let Gemini CLI analyze and read your code without modifying any files. This is useful for code review, auditing, and analysis tasks where you want AI insights without any risk of unintended changes.
// Allow reading everything, but prevent all writes
{
"sandbox": {
"readOnly": true,
"allowPaths": ["./"],
"blockPaths": [".env", "credentials/"]
}
}
Network Restrictions
Control whether and how Gemini CLI can access the network. Network restrictions prevent AI-generated code from making unexpected HTTP requests, downloading untrusted packages, or exfiltrating sensitive data.
Block All Network Access
The most restrictive setting. Gemini CLI operates entirely offline, with no outbound connections permitted. This is the safest option for air-gapped environments or when working with highly sensitive codebases.
// Complete network isolation
{
"sandbox": {
"network": false
}
}
Allow Specific Domains
Permit network access only to domains you trust. This lets Gemini CLI interact with approved APIs and package registries while blocking all other outbound traffic.
// Allow only trusted domains
{
"sandbox": {
"network": true,
"allowDomains": [
"api.google.com",
"registry.npmjs.org",
"github.com"
]
}
}
Enterprise Proxy Configuration
For corporate environments that route traffic through a proxy server, configure the sandbox to use your organization's proxy. All outbound requests from Gemini CLI will pass through the proxy, where your existing network security policies apply.
// Route all traffic through corporate proxy
{
"sandbox": {
"network": true,
"proxy": "http://proxy.corporate.com:8080",
"allowDomains": ["*.internal.corporate.com"]
}
}
Security Best Practices
Following these practices ensures you get the most out of sandbox mode while maintaining a strong security posture across your development workflow.
1. Always Sandbox Untrusted Prompts
If a prompt comes from an external source such as a user input, a webhook payload, or a file you did not write, always run it in sandbox mode. Untrusted prompts can contain injection attacks that attempt to access sensitive files or execute harmful commands.
2. Use Blocklists for Sensitive Files
Explicitly block access to environment files, credentials, private keys, and configuration files that contain secrets. Even if you trust the prompt, preventing access to these files eliminates an entire category of risk.
3. Enable Read-Only for Code Reviews
When using Gemini CLI for code analysis, auditing, or review tasks, enable read-only mode. There is no reason for the AI to write files during a review, and read-only mode guarantees your codebase remains untouched.
4. Restrict Commands to What You Need
Define an allowlist of shell commands that Gemini CLI can execute. If your task only requires running tests, limit the command set to your test runner. Avoid allowing broad commands like bash or sh that can execute arbitrary scripts.
5. Commit Sandbox Configs to Version Control
Store your .gemini/settings.json in your repository so every team member and CI/CD pipeline uses the same security policy. This ensures consistent protection across all environments and prevents individual developers from accidentally running without sandbox protection.
6. Review Sandbox Logs Regularly
The sandbox logs every blocked action, including the file path, command, or domain that was denied. Review these logs periodically to identify potential security issues, refine your policies, and detect any unexpected behavior from AI-generated actions.
Sandbox vs Docker
Both Gemini CLI's sandbox and Docker containers provide isolation, but they serve different purposes and operate at different levels. Understanding when to use each helps you choose the right tool for your security requirements.
Gemini CLI Sandbox
- • Built-in, zero setup required
- • Application-level isolation
- • Lightweight, no overhead
- • Fine-grained path and domain controls
- • Ideal for daily development workflows
- • Configuration lives in your project
Docker Container
- • Requires Docker installation and images
- • OS-level isolation with own filesystem
- • Higher resource overhead
- • Full environment isolation (kernel, network stack)
- • Ideal for untrusted workloads and production
- • Reproducible environments across machines
When to use both: For maximum security, run Gemini CLI inside a Docker container with sandbox mode enabled. The Docker container provides OS-level isolation, while the sandbox adds application-level access controls specific to Gemini CLI. This layered approach is recommended for CI/CD pipelines processing untrusted code and for environments where regulatory compliance requires defense in depth.
Related Questions
Subagents: Parallel Task Delegation
Learn how Gemini CLI delegates tasks to subagents and how sandbox policies apply to each
Configuration Files
Understand all Gemini CLI configuration files, including sandbox settings
Automate Tasks with Gemini CLI
Set up automation scripts and CI/CD integration with sandbox protection
Environment Variables
Configure Gemini CLI behavior through environment variables and keep secrets safe
Secure Your Workflow
Start using sandbox mode today to protect your codebase while leveraging the full power of AI-assisted development: