https://github.com/tgagor/docker-gemini-cli
Gemini CLI wrapped as a Docker image, so you don't need to trash your OS with Node and it's dependencies.
https://github.com/tgagor/docker-gemini-cli
ai docker gemini gemini-ai gemini-cli
Last synced: about 1 month ago
JSON representation
Gemini CLI wrapped as a Docker image, so you don't need to trash your OS with Node and it's dependencies.
- Host: GitHub
- URL: https://github.com/tgagor/docker-gemini-cli
- Owner: tgagor
- License: gpl-2.0
- Created: 2025-10-31T08:29:59.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-06-01T09:39:19.000Z (about 1 month ago)
- Last Synced: 2026-06-01T11:25:09.258Z (about 1 month ago)
- Topics: ai, docker, gemini, gemini-ai, gemini-cli
- Language: Dockerfile
- Homepage: https://gagor.pro/2025/10/running-gemini-cli-in-a-docker-container/
- Size: 79.1 KB
- Stars: 18
- Watchers: 0
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README-TEMPLATE.md
- License: LICENSE
Awesome Lists containing this project
- awesome-gemini-cli - Docker Gemini CLI - Gemini CLI wrapped as a Docker image, so you don't need to trash your OS with Node and its dependencies. (Development Tools & Utilities)
README
# Gemini CLI in Docker
A convenient and isolated way to run the [Gemini CLI](https://github.com/google-gemini/gemini-cli) without needing to install Node.js or its dependencies on your local system. This repository provides automatically updated Docker images.
[](https://github.com/tgagor/docker-gemini-cli/actions/workflows/build.yml)
## Prerequisites
* [Docker](https://docs.docker.com/get-docker/) must be installed and running on your system.
## Usage
### Recommended Setup
The recommended way to use this image is to create a shell function that handles all the necessary mount points and permissions. Add the following function to your `~/.bash_aliases` or `~/.zsh_aliases`:
```bash
function gemini {
local tty_args=""
if [ -t 0 ]; then
tty_args="--tty"
fi
docker run -i ${tty_args} --rm \
-v "$(pwd):/home/gemini/workspace" \
-v "$HOME/.gemini:/home/gemini/.gemini" \
-e DEFAULT_UID=$(id -u) \
-e DEFAULT_GID=$(id -g) \
-e TERM="${TERM:-xterm-256color}" \
-e COLORTERM="${COLORTERM:-truecolor}" \
tgagor/gemini-cli "$@"
}
```
This setup:
- Mounts your current directory as `/home/gemini/workspace` inside the container
- Mounts `~/.gemini` to preserve Gemini CLI configuration between runs
- Matches container user permissions with your local user to avoid file ownership issues
- Handles TTY properly for interactive use
- Thanks to [Lewis](https://github.com/Lewiscowles1986) colors are also handled properly
- To use the Bun variant, simply use `bun` tag: `tgagor/gemini-cli:bun`
#### Platform-specific Notes
**Linux:**
- Works out of the box with the setup above
- File permissions are handled automatically through UID/GID mapping
**macOS:**
- The setup works the same way
- File permissions might behave differently due to how Docker Desktop handles mounting on macOS
- If you experience permission issues, you may need to add `:delegated` to volume mounts for better performance
#### Runtime Variants
This repository provides two runtime variants:
- **Node.js** (default): Available on `linux/amd64`, `linux/arm64`, and `linux/arm/v7`. Use standard tags like `latest`, `v{{ .GEMINI_CLI_VERSION }}`.
- **Bun**: Faster alternative available on `linux/amd64` and `linux/arm64` only. Use tags with `bun` suffix (e.g., `bun`, `v{{ .GEMINI_CLI_VERSION }}-bun`).
### Basic Docker Usage
While not recommended, you can still run the container directly with Docker commands:
```bash
docker run --rm -it \
-v "$(pwd):/home/gemini/workspace" \
-v "$HOME/.gemini:/home/gemini/.gemini" \
-e DEFAULT_UID=$(id -u) \
-e DEFAULT_GID=$(id -g) \
-e TERM="${TERM:-xterm-256color}" \
-e COLORTERM="${COLORTERM:-truecolor}" \
tgagor/gemini-cli [command]
```
### Examples
**Using the shell function (recommended):**
```bash
# Get help
gemini --help
# Process a local file
gemini your-prompt-file.txt
# Pipe file as context
cat doc.md | gemini -p "Correct grammar"
# Use interactive mode
gemini
```
## Supported Tags
The following tags are available on [Docker Hub](https://hub.docker.com/r/tgagor/gemini-cli):
### Node.js (Default)
* [`latest`](https://hub.docker.com/r/tgagor/gemini-cli/tags): Most recent stable version.
* [`alpine`](https://hub.docker.com/r/tgagor/gemini-cli/tags): Latest with Alpine Linux base.
* [`v{{ .GEMINI_CLI_VERSION }}`](https://hub.docker.com/r/tgagor/gemini-cli/tags): Specific version.
* [`v{{ .GEMINI_CLI_VERSION }}-alpine`](https://hub.docker.com/r/tgagor/gemini-cli/tags): Specific version with Alpine base.
* [`v{{ .GEMINI_CLI_VERSION | splitList "." | first }}.{{ .GEMINI_CLI_VERSION | splitList "." | rest | first }}`](https://hub.docker.com/r/tgagor/gemini-cli/tags): Latest patch for a minor version.
* [`v{{ .GEMINI_CLI_VERSION | splitList "." | first }}.{{ .GEMINI_CLI_VERSION | splitList "." | rest | first }}-alpine`](https://hub.docker.com/r/tgagor/gemini-cli/tags): Latest patch with Alpine base.
* [`v{{ .GEMINI_CLI_VERSION | splitList "." | first }}`](https://hub.docker.com/r/tgagor/gemini-cli/tags): Latest minor release for a major version.
* [`v{{ .GEMINI_CLI_VERSION | splitList "." | first }}-alpine`](https://hub.docker.com/r/tgagor/gemini-cli/tags): Latest minor with Alpine base.
### Bun (⚠️ amd64 and arm64 only)
* [`bun`](https://hub.docker.com/r/tgagor/gemini-cli/tags): Latest with Bun runtime.
* [`v{{ .GEMINI_CLI_VERSION }}-bun`](https://hub.docker.com/r/tgagor/gemini-cli/tags): Specific version with Bun.
* [`v{{ .GEMINI_CLI_VERSION | splitList "." | first }}.{{ .GEMINI_CLI_VERSION | splitList "." | rest | first }}-bun`](https://hub.docker.com/r/tgagor/gemini-cli/tags): Latest patch for a minor version with Bun.
* [`v{{ .GEMINI_CLI_VERSION | splitList "." | first }}-bun`](https://hub.docker.com/r/tgagor/gemini-cli/tags): Latest minor with Bun.
## Security
Images are automatically scanned for vulnerabilities. You can view the latest security report [here](https://github.com/tgagor/docker-gemini-cli/security/advisories).
## Image sizes
)
)
)
## Images
You can fetch docker image from:
* [tgagor/gemini-cli](https://hub.docker.com/r/tgagor/gemini-cli)