Fresh

Gemini

Back

Manuals

• Get started
• Guides
• Reference

Gemini

Copy as Markdown

Open MarkdownAsk Docs AIClaudeOpen in Claude

Table of contents

---

Availability:Experimental

This guide covers authentication, configuration, and usage of Google Gemini in a sandboxed environment.

Official documentation: Gemini CLI

Quick start

Create a sandbox and run Gemini for a project directory:

$ sbx run gemini ~/my-project

The workspace parameter is optional and defaults to the current directory:

$ cd ~/my-project
$ sbx run gemini

Authentication

Gemini requires either a Google API key or a Google account with Gemini access.

API key: Store your key using stored secrets:

$ sbx secret set -g google

Alternatively, export the GEMINI_API_KEY or GOOGLE_API_KEY environment variable in your shell before running the sandbox. See Credentials for details on both methods.

Google account: If no API key is set, Gemini prompts you to sign in interactively when it starts. Interactive authentication is scoped to the sandbox and doesn't persist if you remove and recreate it.

Configuration

Sandboxes don't pick up user-level configuration from your host, such as ~/.gemini. Only project-level configuration in the working directory is available inside the sandbox. See Why doesn't the sandbox use my user-level agent configuration? for workarounds.

The sandbox runs Gemini without approval prompts by default and disables Gemini's built-in sandbox tool (since the sandbox itself provides isolation). Pass additional Gemini CLI options after --:

$ sbx run gemini --name <sandbox-name> -- <gemini-options>

Base image

Template: docker/sandbox-templates:gemini

Gemini is configured to disable its built-in OAuth flow. Authentication is managed through the proxy with API keys. Preconfigured to run without approval prompts.

See Custom environments to pre-install tools or customize this environment.