Gemini CLI Docker

Run Google Gemini CLI in a Docker container. Gemini CLI is an open-source AI agent that brings the power of Gemini directly into your terminal with access to Gemini 2.5 Pro and a 1M token context window.

Quick Start

# Pull and run (replace with your API key)
docker run -it --rm \
  -v $(pwd):/workspace \
  -e GOOGLE_API_KEY=your-key \
  ungb/gemini-cli

Prerequisites

Docker installed
One of the following:
- Google API key (free tier available)
- Google account for OAuth login
- Google Cloud account for Vertex AI

Authentication

Choose your authentication method:

Plan Type	Authentication Method	Section
Free/Personal Use	API Key (recommended)	API Key Setup
Google Account	OAuth Login	Google Account Login
Enterprise (GCP)	Vertex AI	Vertex AI Setup

API Key (Recommended for Docker)

Get a free API key from Google AI Studio:

# Set your API key as an environment variable
docker run -it --rm \
  -v $(pwd):/workspace \
  -e GOOGLE_API_KEY=AI... \
  ungb/gemini-cli

Or use an environment variable from your shell:

# Export once in your shell
export GOOGLE_API_KEY=AI...

# Then use in docker commands
docker run -it --rm \
  -v $(pwd):/workspace \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli

Free tier includes:

60 requests per minute
1,000 requests per day
Access to Gemini 2.5 Pro with 1M token context

Google Account Login

For browser-based authentication:

One-Time Setup

# Login with Google account (requires host network for callback)
docker run -it --rm \
  --network host \
  -v ~/.gemini:/home/coder/.gemini \
  ungb/gemini-cli

Follow the prompts to authenticate with your Google account.

Daily Usage

After the one-time login, simply run:

# No API key needed!
docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.gemini:/home/coder/.gemini \
  ungb/gemini-cli

Important: Always mount -v ~/.gemini:/home/coder/.gemini to persist your login. Without this mount, you'll need to login every time.

Vertex AI (Enterprise)

For Google Cloud users:

docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.config/gcloud:/home/coder/.config/gcloud:ro \
  -e GOOGLE_CLOUD_PROJECT=your-project \
  -e GOOGLE_CLOUD_REGION=us-central1 \
  ungb/gemini-cli

Usage Examples

Interactive Session

# Start an interactive Gemini CLI session
docker run -it --rm \
  -v $(pwd):/workspace \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli

One-Shot Commands (Non-Interactive)

Use the -p (or --prompt) flag for non-interactive mode:

# Ask a question about your codebase
docker run -it --rm \
  -v $(pwd):/workspace \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli \
  gemini -p "explain the architecture of this project"

# Generate code
docker run -it --rm \
  -v $(pwd):/workspace \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli \
  gemini -p "create a REST API endpoint for user authentication"

# Code review
docker run -it --rm \
  -v $(pwd):/workspace \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli \
  gemini -p "review the changes in the last commit for security issues"

# JSON output (for scripts/automation)
docker run -it --rm \
  -v $(pwd):/workspace \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli \
  gemini -p --output-format json "list all TODO comments"

Note: Non-interactive mode (-p) has limitations - it cannot authorize tools like WriteFile or run shell commands. For tasks requiring file modifications, use interactive mode.

Full Configuration (Recommended)

# Full setup with persistent config, git, SSH, and screenshots
docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.gemini:/home/coder/.gemini \
  -v ~/.ssh:/home/coder/.ssh:ro \
  -v ~/.gitconfig:/home/coder/.gitconfig:ro \
  -v ~/gemini-screenshots:/screenshots \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli

Using Docker Compose

Copy docker-compose.yml to your project:

curl -O https://raw.githubusercontent.com/ungb/gemini-cli-docker/main/docker-compose.yml

Create a .env file:

echo "GOOGLE_API_KEY=your-key-here" > .env

Run:

# Interactive session
docker compose run --rm gemini

# One-shot command (non-interactive, read-only)
docker compose run --rm gemini gemini -p "explain this code"

YOLO Mode

# Auto-approve all tool calls (use with caution)
docker run -it --rm \
  -v $(pwd):/workspace \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli \
  gemini --yolo "refactor this code"

Sandbox Mode

# Run in sandbox mode for safer execution
docker run -it --rm \
  -v $(pwd):/workspace \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli \
  gemini --sandbox "analyze this code"

With Google Search Grounding

Gemini CLI has built-in Google Search for up-to-date information (works in interactive mode):

docker run -it --rm \
  -v $(pwd):/workspace \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli

# Then ask: "what are the latest best practices for React 19?"

Configuration

Sharing Your Gemini Configuration

The ~/.gemini directory contains your Gemini CLI configuration, themes, and settings.

What's in ~/.gemini

~/.gemini/
├── settings.json         # Global settings and preferences
├── GEMINI.md             # Custom instructions (like CLAUDE.md)
└── themes/               # Custom color themes

Mount Your Configuration

# Share your Gemini config folder
docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.gemini:/home/coder/.gemini \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli

Custom Instructions with GEMINI.md

Create ~/.gemini/GEMINI.md (or GEMINI.md in your project root) with instructions:

# Project Instructions

- Use TypeScript with strict mode
- Follow the existing code patterns
- Add tests for new functionality

The file is automatically picked up when mounted:

docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.gemini:/home/coder/.gemini \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli

Project-Specific GEMINI.md

Your project can have its own GEMINI.md at the root:

# Project's GEMINI.md is automatically available at /workspace/GEMINI.md
docker run -it --rm \
  -v $(pwd):/workspace \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli

Volume Mounts

Mount	Purpose
`/workspace`	Your project directory (required)
`/home/coder/.gemini`	Gemini config, themes, settings
`/home/coder/.ssh`	SSH keys for git operations (read-only)
`/home/coder/.gitconfig`	Git configuration (read-only)
`/home/coder/.config/gcloud`	Google Cloud credentials for Vertex AI
`/screenshots`	Optional: Dedicated folder for screenshots and images (recommended)

Working with External Files and Screenshots

Important: Drag-and-drop doesn't work when Gemini CLI runs in a Docker container because it's isolated from your host filesystem. You need to explicitly mount directories to make files accessible.

Recommended Setup: Dedicated Screenshots Folder

Create a dedicated folder on your host machine for screenshots and images you want to share with Gemini CLI:

Step 1: Create the Screenshots Directory

# Create a dedicated screenshots folder
mkdir -p ~/gemini-screenshots

Step 2: Mount the Screenshots Folder

Using docker run:

docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.gemini:/home/coder/.gemini \
  -v ~/gemini-screenshots:/screenshots \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli

Using docker-compose:

Update your docker-compose.yml to include the screenshots mount:

volumes:
  - ./:/workspace
  - ~/.gemini:/home/coder/.gemini
  - ~/gemini-screenshots:/screenshots  # Add this line

Step 3: Add Your Files

# Copy screenshots or images to the folder
cp ~/Downloads/screenshot.png ~/gemini-screenshots/
cp ~/Desktop/diagram.jpg ~/gemini-screenshots/

# Or save screenshots directly to this folder using your screenshot tool

Step 4: Reference Files in Gemini CLI

Inside Gemini CLI, reference files using the mounted path:

Can you analyze /screenshots/screenshot.png?

Please review the UI in /screenshots/mockup.png and suggest improvements

Read the diagram at /screenshots/architecture.jpg and explain the flow

Alternative: Using Your Downloads Folder

You can also mount your Downloads folder directly:

# Mount Downloads folder (read-only recommended for safety)
docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.gemini:/home/coder/.gemini \
  -v ~/Downloads:/downloads:ro \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli

Then reference files:

Analyze /downloads/screenshot.png

Alternative: Copy Files to Your Workspace

If you're working on a specific project, copy files directly into your project directory:

# Copy to your project directory (which is already mounted as /workspace)
cp ~/Downloads/screenshot.png /path/to/your/project/

# Then in Gemini CLI:
# Analyze /workspace/screenshot.png

Multiple Mount Points Example

You can mount multiple directories for different purposes:

docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.gemini:/home/coder/.gemini \
  -v ~/gemini-screenshots:/screenshots \
  -v ~/Downloads:/downloads:ro \
  -v ~/Documents:/docs:ro \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli

This gives you access to:

/workspace - Your current project
/screenshots - Dedicated screenshots folder (read-write)
/downloads - Downloads folder (read-only)
/docs - Documents folder (read-only)

Tips for Working with External Files

Use descriptive paths: Instead of screenshot.png, use login-page-error.png
Organize by purpose: Create subfolders in ~/gemini-screenshots/ like bugs/, designs/, diagrams/
Read-only mounts: Use :ro flag for folders you only need to read from (safety measure)
Absolute paths: Always use absolute paths when referencing files (e.g., /screenshots/image.png)

Example Workflow

# 1. Take a screenshot (macOS example)
# Press Cmd+Shift+4 and save to ~/gemini-screenshots/

# 2. Start Gemini CLI with screenshots mounted
docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.gemini:/home/coder/.gemini \
  -v ~/gemini-screenshots:/screenshots \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli

# 3. In Gemini CLI, reference the screenshot
> Can you analyze the error message in /screenshots/error-screenshot.png and help me fix it?

Environment Variables

Variable	Required	Description
`GOOGLE_API_KEY`	Conditional*	Google AI Studio API key
`GOOGLE_CLOUD_PROJECT`	No	GCP project ID (for Vertex AI)
`GOOGLE_CLOUD_REGION`	No	GCP region (for Vertex AI)
`GEMINI_MODEL`	No	Model to use (default: gemini-2.5-pro)

*Required unless using Google account login or Vertex AI.

Built-in Tools

Gemini CLI includes these tools out of the box:

Google Search - Grounded answers with web search
File Operations - Read, write, edit files
Shell Commands - Execute terminal commands
Web Fetch - Retrieve web content

MCP (Model Context Protocol) Support

Warning: MCP support in Docker containers is limited and may require additional configuration.

Current Limitations

Gemini CLI supports MCP, but in Docker:

Stdio-based MCP servers need the server binary installed inside the container
Network-based MCP servers need proper network configuration
MCP servers that access local resources need those resources mounted
Authentication for MCP servers may not transfer into the container

What Might Work

MCP Type	Status	Notes
HTTP/SSE servers (remote)	May work	Requires `--network host` or port mapping
Stdio servers (local)	Unlikely	Server must be installed in container
Servers needing local files	Partial	Files must be mounted
Servers with OAuth	Unlikely	Auth flow may not complete

Attempting MCP with Docker

# Mount MCP config and use host network
docker run -it --rm \
  --network host \
  -v $(pwd):/workspace \
  -v ~/.gemini:/home/coder/.gemini \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli

Building a Custom Image with MCP Servers

FROM ungb/gemini-cli:latest

USER root
RUN npm install -g @anthropic/mcp-server-filesystem
USER coder

MCP Investigation Needed

Full MCP support requires further investigation. Gemini CLI's MCP implementation may differ from Claude Code. If you have solutions, please open an issue or PR!

Troubleshooting

Permission Denied on Mounted Files

# Run with your user ID
docker run -it --rm \
  --user $(id -u):$(id -g) \
  -v $(pwd):/workspace \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli

Git Operations Failing

Ensure SSH keys are mounted and git is configured:

docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.ssh:/home/coder/.ssh:ro \
  -v ~/.gitconfig:/home/coder/.gitconfig:ro \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli

API Key Invalid

Verify your API key works:

curl -H "x-goog-api-key: $GOOGLE_API_KEY" \
  "https://generativelanguage.googleapis.com/v1beta/models"

Rate Limits

Free tier limits: 60 requests/minute, 1,000 requests/day. For higher limits:

Use multiple API keys
Upgrade to Vertex AI
Use a paid AI Studio plan

Utility Commands

# Check version
docker run --rm ungb/gemini-cli gemini --version

# Show help
docker run --rm ungb/gemini-cli gemini --help

# Use a specific model
docker run -it --rm \
  -v $(pwd):/workspace \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  -e GEMINI_MODEL=gemini-2.0-flash \
  ungb/gemini-cli

Shell Alias (Convenience)

Add to your ~/.bashrc or ~/.zshrc:

alias gemini-docker='docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.gemini:/home/coder/.gemini \
  -v ~/.ssh:/home/coder/.ssh:ro \
  -v ~/.gitconfig:/home/coder/.gitconfig:ro \
  -v ~/gemini-screenshots:/screenshots \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  ungb/gemini-cli gemini'

# Usage (interactive): gemini-docker
# Usage (one-shot):    gemini-docker -p "explain this code"
# Usage (with screenshot): gemini-docker -p "analyze /screenshots/bug.png"

Building Locally

git clone https://github.com/ungb/gemini-cli-docker.git
cd gemini-cli-docker
docker build -t gemini-cli .

License

MIT License - see LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github/workflows		.github/workflows
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
entrypoint.sh		entrypoint.sh

License

ungb/gemini-cli-docker

Folders and files

Latest commit

History

Repository files navigation

Gemini CLI Docker

Table of Contents

Quick Start

Prerequisites

Authentication

API Key (Recommended for Docker)

Google Account Login

One-Time Setup

Daily Usage

Vertex AI (Enterprise)

Usage Examples

Interactive Session

One-Shot Commands (Non-Interactive)

Full Configuration (Recommended)

Using Docker Compose

YOLO Mode

Sandbox Mode

With Google Search Grounding

Configuration

Sharing Your Gemini Configuration

What's in ~/.gemini

Mount Your Configuration

Custom Instructions with GEMINI.md

Project-Specific GEMINI.md

Volume Mounts

Working with External Files and Screenshots

Recommended Setup: Dedicated Screenshots Folder

Step 1: Create the Screenshots Directory

Step 2: Mount the Screenshots Folder

Step 3: Add Your Files

Step 4: Reference Files in Gemini CLI

Alternative: Using Your Downloads Folder

Alternative: Copy Files to Your Workspace

Multiple Mount Points Example

Tips for Working with External Files

Example Workflow

Environment Variables

Built-in Tools

MCP (Model Context Protocol) Support

Current Limitations

What Might Work

Attempting MCP with Docker

Building a Custom Image with MCP Servers

MCP Investigation Needed

Troubleshooting

Permission Denied on Mounted Files

Git Operations Failing

API Key Invalid

Rate Limits

Utility Commands

Shell Alias (Convenience)

Building Locally

License

Links

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages