Sandboxing in the TerminaI

This document provides a guide to sandboxing in the TerminaI, including prerequisites, quickstart, and configuration.

Prerequisites

Before using sandboxing, you need to install and set up the TerminaI:

Terminal window

npm install -g @google/terminai

To verify the installation

Terminal window

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

Terminal window

# Enable sandboxing with command flaggemini -s -p "analyze the code structure"
# Use environment variableexport GEMINI_SANDBOX=truegemini -p "run the test suite"
# Configure in settings.json{  "tools": {    "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 the tools object of your settings.json file (e.g., {"tools": {"sandbox": true}}).

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

Custom sandbox flags

For container-based sandboxing, you can inject custom flags into the docker or podman command using the SANDBOX_FLAGS environment variable. This is useful for advanced configurations, such as disabling security features for specific use cases.

Example (Podman):

To disable SELinux labeling for volume mounts, you can set the following:

Terminal window

export SANDBOX_FLAGS="--security-opt label=disable"

Multiple flags can be provided as a space-separated string:

Terminal window

export SANDBOX_FLAGS="--flag1 --flag2=value"

Linux UID/GID handling

The sandbox automatically handles user permissions on Linux. Override these permissions with:

Terminal window

export SANDBOX_SET_UID_GID=true   # Force host UID/GIDexport 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

Terminal window

DEBUG=1 gemini -s -p "debug command"

Note: If you have DEBUG=true in a project’s .env file, it won’t affect terminai due to automatic exclusion. Use .gemini/.env files for terminai specific debug settings.

Inspect sandbox

Terminal window

# Check environmentgemini -s -p "run shell command: env | grep SANDBOX"
# List mountsgemini -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: Full configuration options.
• Commands: Available commands.
• Troubleshooting: General troubleshooting.