peez/gemini2mqtt repository overview

⁠gemini2mqtt

https://github.com/peez80/docker-gemini2mqtt⁠

⁠How it works

MQTT Broker
  │
  ├─► Topic: MQTT_PROMPT_TOPIC   (incoming)
  │       Message format: "response_topic|prompt"
  │
  └─► Topic: <response_topic>    (outgoing)
          Message format: "response_topic|gemini_answer"

⁠Message format

⁠Incoming (Prompt)

Incoming messages must contain two |-separated fields:

Example:

home/ai/response|What is the capital of Bavaria?

⁠Outgoing (Response)

The response is published to <response_topic> in the same |-separated format:

Example:

home/ai/response|The capital of Bavaria is Munich.

⁠Configuration (environment variables)

All settings are configured via environment variables. Copy .env.example to .env and adjust the values:

cp .env.example .env

⁠Deployment with Docker

⁠Quick start

# 1. Create .env
cp .env.example .env
# (adjust values in .env)

# 2. Build image and start container
docker compose up -d --build

⁠View logs

docker compose logs -f gemini2mqtt

⁠Stop container

docker compose down

⁠Local development (without Docker)

# Install dependencies
pip install -r requirements.txt

# Set environment variables
cp .env.example .env
# adjust .env as needed

# Start
python gemini2mqtt.py

⁠Authentication (Gemini CLI)

To authenticate with the Gemini API, credentials must be generated once inside a container and persisted to a local directory:

# Create a local directory for credentials
mkdir -p /path/to/credentials-directory

# Start container interactively with Gemini CLI and mount the directory
docker run -it --rm --entrypoint gemini \
  -v "/path/to/credentials-directory:/root/.gemini" \
  peez/gemini2mqtt

In the interactive CLI:

1. Navigate to "Sign in with Google" using the arrow keys and confirm.
2. Copy the displayed URL and open it in your browser.
3. Complete the Google auth flow and paste the displayed code back into the CLI.
4. After successful authentication, credentials are saved to /path/to/credentials-directory.

Mount this directory as a volume in docker-compose.yml so the service uses the stored credentials on startup.

⁠Vertex AI API (Alternative)

⁠When to use Vertex AI?

Standard mode authenticates via your Google account and uses its associated quotas — including any free tier limits. This is the easiest setup and works well for personal or home-server use.

Vertex AI is a paid Google Cloud API — billing must be enabled on your GCP project. Use it when data privacy is a requirement (requests are not used for training), when you need guaranteed quotas beyond the free tier, or when running in a production / enterprise environment.

⁠Prerequisites

1. Create (or reuse) a GCP project⁠ with billing enabled
2. Enable the Vertex AI API:

   gcloud services enable aiplatform.googleapis.com --project=<PROJECT_ID>
   

   Copy
3. Create a Service Account and grant it the Vertex AI User role:

   gcloud iam service-accounts create gemini2mqtt \
     --display-name="gemini2mqtt" --project=<PROJECT_ID>
   
   gcloud projects add-iam-policy-binding <PROJECT_ID> \
     --member="serviceAccount:gemini2mqtt@<PROJECT_ID>.iam.gserviceaccount.com" \
     --role="roles/aiplatform.user"
   

   Copy
4. Download the JSON key:

   gcloud iam service-accounts keys create vertex_key.json \
     --iam-account=gemini2mqtt@<PROJECT_ID>.iam.gserviceaccount.com
   

   Copy
5. Populate .env and start the Vertex AI Compose stack:

   cp .env.example .env
   # Set GOOGLE_CLOUD_PROJECT and VERTEX_CREDENTIAL_FILE
   docker compose -f docker-compose-vertexapi.yml up -d --build
   

   Copy

⁠Project structure

docker-ai2mqtt/
├── gemini2mqtt.py       # Main application
├── Dockerfile           # Docker image (Python + Gemini CLI)
├── docker-compose.yml           # Compose configuration (standard / Gemini CLI auth)
├── docker-compose-vertexapi.yml # Compose configuration (Vertex AI / service account)
├── requirements.txt     # Python dependencies
├── .env.example         # Environment variable template
├── .dockerignore
├── .gitignore
└── spec.md              # Project specification

⁠Docker Image Versioning

The image peez/gemini2mqtt is built automatically on every merge to the main branch and published to Docker Hub as a multi-arch image (linux/amd64 & linux/arm64).

⁠Available tags

⁠Which tag should I use?

• latest – suitable for private / home-server use when you always want the newest version. Works well in combination with tools like Watchtower⁠ for automatic updates.
• Timestamp tag – recommended for production or reproducible deployments where you want to pin a specific, tested version and control updates explicitly.

⁠Pulling a specific version

# Always latest
docker pull peez/gemini2mqtt:latest

# Specific snapshot
docker pull peez/gemini2mqtt:202604091830

⁠Updating

# Pull the new image and restart the container
docker compose pull
docker compose up -d