DEV Community

Cover image for How to Run Gemini CLI in a Local Docker Sandbox (The Safe & Easy Way!)
Aakash Choudhary
Aakash Choudhary

Posted on

How to Run Gemini CLI in a Local Docker Sandbox (The Safe & Easy Way!)

#docker #ai #gemini #security

If you are someone who loves working in the terminal and automating away day-to-day friction, bringing an AI agent into your workflow feels like a superpower. But let’s be honest: the moment you think about running an AI agent on your local machine, a little alarm bell goes off in your head.

What exactly does this AI have access to? Is it reading my secret files?

Today, we are going to fix that. I'm going to show you how to spin up the Gemini CLI on your local system in a completely isolated, safe sandbox environment using Docker.

Why a Sandbox?

When running any AI agent, security and access control should be your top priorities.

  1. Total Isolation: You probably don't want the AI sniffing around your entire file system. There might be confidential files you want to keep hidden.
  2. Saving Tokens: If the AI has access to too many files, it might pull unnecessary data into its context window, eating up your precious tokens (and your money!).
  3. Control: In a sandbox, you have the upper hand. You decide exactly which single folder the agent can see, and whether it has read-only or read-write access.
  4. Multiple Instances: Because we are using Docker, you can spin up multiple independent containers. They won't know about each other, allowing you to run different tasks at the same time without them getting mixed up.

Plus, you still get all the awesome Gemini CLI features—like running in auto-accept mode, plan mode, and switching between fast or pro models!

The Prerequisites

Before we start, let's make sure you have what you need:

  • A Gemini API Key: You can grab this from the Google AI Studio.
  • Docker: Installed and running on your local system.
  • Reading this article: Honestly, this is the holy grail for you right now. Stick with me!

Step 1: Check if Docker is Awake

First things first, let's make sure Docker is actually running. If you are on a Mac (or Linux), open your terminal and type:

docker ps
Enter fullscreen mode Exit fullscreen mode

If you see a nice little table (even if it's empty), your Docker daemon is up and running. If it throws an error, go ahead and start Docker Desktop!

Step 2: The Dockerfile

Google's official documentation suggests installing the Gemini CLI via Node.js. So, we are going to use a lightweight Node image to build our sandbox.

REFER GITHUB FOR QUICK ACCESS TO FILE

Create a file named gemini-sdbx.Dockerfile and paste this in:

FROM node:slim@sha256:aa27a5fbf5acb298116a38133794f080406c6f8dfe52e2e2836bb55dc7cae8f0 AS base
FROM base AS installation

RUN apt-get update && apt-get install -y \
   git \
   curl \
   bash \
   python3 \
   build-essential \
   && rm -rf /var/lib/apt/lists/*

RUN npm install -g @google/gemini-cli

RUN useradd -m -s /bin/bash sandboxuser
USER sandboxuser

WORKDIR /workspace
ENTRYPOINT ["gemini"]
Enter fullscreen mode Exit fullscreen mode

Wait, why did we create a sandboxuser? Great question! Even though a Docker container runs in a completely isolated namespace and doesn't interact directly with your host kernel, it is still a bad habit to run things as the root (sudo) user. Creating a dedicated sandboxuser adds an extra layer of peace of mind. We don't want Gemini having root privileges, even inside its own little box!

Step 3: The Docker Compose File

Next, we are going to use a Compose file to actually spin up the container we just built.

Create a file named docker-compose.yml and paste this in:

services:
  gemini-sandbox:
    build:
     context: .
     dockerfile: gemini-sdbx.Dockerfile
    image: gemini-sandbox
    container_name: gemini-sandbox
    volumes:
     - ${LOCAL_DIRECTORY_PATH}:/workspace
    environment:
     GEMINI_API_KEY: ${GEMINI_API_KEY}
Enter fullscreen mode Exit fullscreen mode

Step 4: Configure Your Environment

As you can see in the compose file above, we need two environment variables to make the magic happen:

  1. GEMINI_API_KEY: Your secret key
  2. LOCAL_DIRECTORY_PATH: The path to the specific folder on your computer that you want Gemini to see. 
export GEMINI_API_KEY="sk-asdfghjk"
export LOCAL_DIRECTORY_PATH="/this/is/my/directory"
Enter fullscreen mode Exit fullscreen mode

Because we are mounting this specific folder to /workspace inside the container, Gemini will only be able to work inside that folder. It will have absolutely no idea what else is on your computer.

Ready, Set, Go!

Once you have your files saved and your environment variables set, just run:

docker compose run gemini-sandbox
Enter fullscreen mode Exit fullscreen mode

And boom! You now have a fully functional, completely isolated AI assistant ready to help you out right from your terminal. No security worries, no token waste, just smooth sailing.

Happy automating!

Top comments (0)