sandbox doc (#1390)
Co-authored-by: matt korwel <matt.korwel@gmail.com> Co-authored-by: Jenna Inouye <jinouye@google.com>
This commit is contained in:
parent
d8000c9248
commit
d45d414c93
|
@ -0,0 +1,133 @@
|
|||
# Sandboxing in the Gemini CLI
|
||||
|
||||
This document provides a guide to sandboxing in the Gemini CLI, including prerequisites, quickstart, and configuration.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before using sandboxing, you need to install and set up the Gemini CLI:
|
||||
|
||||
```bash
|
||||
#install gemini-cli with npm
|
||||
npm install -g @google/gemini-cli
|
||||
|
||||
# Verify installation
|
||||
gemini --version
|
||||
```
|
||||
|
||||
## Overview of sandboxing
|
||||
|
||||
Sandboxing isolates potentially dangerous operations (such as shell commands or file modifications) from your host system, providing a security barrier between AI operations and your environment.
|
||||
|
||||
The benefits of sandboxing include:
|
||||
|
||||
- **Security**: Prevent accidental system damage or data loss.
|
||||
- **Isolation**: Limit file system access to project directory.
|
||||
- **Consistency**: Ensure reproducible environments across different systems.
|
||||
- **Safety**: Reduce risk when working with untrusted code or experimental commands.
|
||||
|
||||
## Sandboxing methods
|
||||
|
||||
Your ideal method of sandboxing may differ depending on your platform and your preferred container solution.
|
||||
|
||||
### 1. macOS Seatbelt (macOS only)
|
||||
|
||||
Lightweight, built-in sandboxing using `sandbox-exec`.
|
||||
|
||||
**Default profile**: `permissive-open` - restricts writes outside project directory but allows most other operations.
|
||||
|
||||
### 2. Container-based (Docker/Podman)
|
||||
|
||||
Cross-platform sandboxing with complete process isolation.
|
||||
|
||||
**Note**: Requires building the sandbox image locally or using a published image from your organization's registry.
|
||||
|
||||
## Quickstart
|
||||
|
||||
```bash
|
||||
# Enable sandboxing with command flag
|
||||
gemini -s -p "analyze the code structure"
|
||||
|
||||
# Use environment variable
|
||||
export GEMINI_SANDBOX=true
|
||||
gemini -p "run the test suite"
|
||||
|
||||
# Configure in settings.json
|
||||
{
|
||||
"sandbox": "docker"
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Enable sandboxing (in order of precedence)
|
||||
|
||||
1. **Command flag**: `-s` or `--sandbox`
|
||||
2. **Environment variable**: `GEMINI_SANDBOX=true|docker|podman|sandbox-exec`
|
||||
3. **Settings file**: `"sandbox": true` in `settings.json`
|
||||
|
||||
### macOS Seatbelt profiles
|
||||
|
||||
Built-in profiles (set via `SEATBELT_PROFILE` env var):
|
||||
|
||||
- `permissive-open` (default): Write restrictions, network allowed
|
||||
- `permissive-closed`: Write restrictions, no network
|
||||
- `permissive-proxied`: Write restrictions, network via proxy
|
||||
- `restrictive-open`: Strict restrictions, network allowed
|
||||
- `restrictive-closed`: Maximum restrictions
|
||||
|
||||
## Linux UID/GID handling
|
||||
|
||||
The sandbox automatically handles user permissions on Linux. Override these permissions with:
|
||||
|
||||
```bash
|
||||
export SANDBOX_SET_UID_GID=true # Force host UID/GID
|
||||
export SANDBOX_SET_UID_GID=false # Disable UID/GID mapping
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common issues
|
||||
|
||||
**"Operation not permitted"**
|
||||
|
||||
- Operation requires access outside sandbox.
|
||||
- Try more permissive profile or add mount points.
|
||||
|
||||
**Missing commands**
|
||||
|
||||
- Add to custom Dockerfile.
|
||||
- Install via `sandbox.bashrc`.
|
||||
|
||||
**Network issues**
|
||||
|
||||
- Check sandbox profile allows network.
|
||||
- Verify proxy configuration.
|
||||
|
||||
### Debug mode
|
||||
|
||||
```bash
|
||||
DEBUG=1 gemini -s -p "debug command"
|
||||
```
|
||||
|
||||
### Inspect sandbox
|
||||
|
||||
```bash
|
||||
# Check environment
|
||||
gemini -s -p "run shell command: env | grep SANDBOX"
|
||||
|
||||
# List mounts
|
||||
gemini -s -p "run shell command: mount | grep workspace"
|
||||
```
|
||||
|
||||
## Security notes
|
||||
|
||||
- Sandboxing reduces but doesn't eliminate all risks.
|
||||
- Use the most restrictive profile that allows your work.
|
||||
- Container overhead is minimal after first build.
|
||||
- GUI applications may not work in sandboxes.
|
||||
|
||||
## Related documentation
|
||||
|
||||
- [Configuration](./cli/configuration.md): Full configuration options.
|
||||
- [Commands](./cli/commands.md): Available commands.
|
||||
- [Troubleshooting](./troubleshooting.md): General troubleshooting.
|
Loading…
Reference in New Issue