AI Native Notes
Back to Gemini CLI
Gemini CLIIntermediate2 min read

Trusted Folders, Sandboxing, and Restore

Use Gemini CLI safely with trusted folders, sandboxed execution, read-only Plan Mode, and checkpoint-based rollback.

securitysandboxtrusted-folderscheckpointingplan-mode

Official References: Trusted folders · Sandboxing · Checkpointing

Gemini CLI has a real safety model now

If you are worried about an AI agent wrecking your codebase, you must understand its multi-layered defense system:

  1. Trusted Folders: Controls workspace-level permissions.
  2. Plan Mode: A strict read-only mode for designing before acting.
  3. Sandboxing: Isolates risky shell executions.
  4. Checkpointing: Creates automated rollback points before writing files.

Plan Mode: Safe Design Before Execution (Read-Only)

For large refactors or exploring unfamiliar repositories, Plan Mode (/plan or enter_plan_mode) is your ultimate safety net.

  • While in Plan Mode, the agent is strictly prohibited from modifying files or running destructive shell commands. It can only use read-only tools to map the codebase and write design documents.
  • Only when the plan is thoroughly reviewed and approved do you manually switch back to the default mode to apply the changes (Execution).

Trusted folders: protect yourself from risky workspaces

Trusted folders are disabled by default. Once enabled, Gemini CLI asks whether a folder should be trusted before loading project-specific configuration.

Enable it in your user settings:

{
  "security": {
    "folderTrust": {
      "enabled": true
    }
  }
}

In an untrusted workspace, sensitive actions like loading .env, connecting to MCP servers, or auto-accepting tools are blocked. This is critical for client code or random open-source repositories.

Sandboxing: isolate risky actions

Gemini CLI can execute file modifications and shell actions inside an isolated container sandbox instead of your host OS.

gemini --sandbox

If a project needs extra binaries, you can provide a custom Dockerfile at .gemini/sandbox.Dockerfile. This keeps your local machine perfectly clean.

Checkpointing: rollback before AI writes files

If the agent makes a mistake, checkpointing (disabled by default) is your undo button. Enable it in settings.json:

{
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}

When enabled, it creates a shadow Git snapshot and conversation backup right before writing files. Restore instantly with:

/restore

How I would use this in practice

  • Unfamiliar client repo: Enable trusted folders globally -> Do NOT trust -> Use Plan Mode to explore -> Use Sandboxing for running code.
  • Trusted repo you own: Trust the folder -> Normal interactive mode -> Enable Checkpointing during heavy edit bursts.

Connected Guides