GeminiProChat: a minimal self-hosted web UI for the Gemini API

What GeminiProChat actually solves

Google's Gemini API is reachable over HTTP, but it does not ship as a chat page you control. GeminiProChat fills that gap: a single-page chat front end that talks to the Gemini API using your own key, with no account system, no hosted backend of the vendor's, and no per-seat pricing layer. The README calls it a "Minimal web UI for Gemini Pro Chat" and states plainly that it is not affiliated with, endorsed by, or sponsored by Google.

The intended user is someone who already has a Google API key and wants a browser interface for it. That covers a developer prototyping against Gemini, a small team that wants one shared internal chat page, or anyone who prefers that prompts leave their machine through their own deployment rather than a third-party product. The scope is deliberately narrow. There is no workspace, no file upload pipeline described, no team management. If you need those, this is the wrong layer to look at.

One design decision matters more than the rest: the app is a front end, not a service. Conversations live in the browser session. The README documents no database and the repository layout shows no migration directory or ORM dependency, so nothing is persisted server-side by default.

How the Astro and Solid stack handles a chat request

The repository is an Astro project with Solid components. package.json lists astro, @astrojs/solid-js, solid-js, and unocss, plus markdown-it with markdown-it-highlightjs and markdown-it-katex for rendering replies. Streaming is handled by eventsource-parser, which parses server-sent events as they arrive, so answers appear token by token rather than after the whole response completes.

The Gemini call itself goes through @fuyun/generative-ai, a fork of the Google generative AI client. That dependency is patched: package.json declares a pnpm patchedDependencies entry mapping @fuyun/[email protected] to patches/@[email protected]. Anyone building from source inherits that patch, which is worth knowing before you swap the client library for the upstream one.

Build targets are selected by an OUTPUT variable. The scripts build:vercel and build:netlify set OUTPUT=vercel and OUTPUT=netlify respectively, and the adapters @astrojs/vercel, @astrojs/netlify and @astrojs/node are all present as dependencies. That is how one codebase serves three hosting shapes without separate branches. The Docker image instead runs a plain Node build behind hack/docker-entrypoint.sh, with HOST=0.0.0.0 and PORT=3000 set in the Dockerfile.

Deploying GeminiProChat with Docker on port 3000

The README recommends Vercel and offers one-click buttons for Railway and Zeabur, but Docker is the path that keeps everything on your own host. The documented command starts the container, maps port 3000, and passes the API key as an environment variable. Replace the placeholder with a key from the Google makersuite page the README links to.

docker run --name geminiprochat \
--restart always \
-p 3000:3000 \
-itd \
-e GEMINI_API_KEY=your_api_key_here \
babaohuang/geminiprochat:latest

After the container starts, the README says the service is reachable at http://localhost:3000. If you prefer Compose, the repository ships docker-compose.yml, which builds from the local Dockerfile rather than pulling the published image, and lists the optional variables as commented lines you can uncomment.

services:
  geminiprochat:
    build: .
    container_name: geminiprochat
    restart: always
    ports:
      - "3000:3000"
    environment:
      - GEMINI_API_KEY=YOUR_GEMINI_API_KEY

For local development outside Docker, the README requires Node v18 or later and pnpm. Copy .env.example to .env, set GEMINI_API_KEY, then run the dev server, which the README says listens on http://localhost:3000/.

pnpm install
pnpm run dev

GEMINI_API_KEY=AIzaSy...

Only GEMINI_API_KEY is marked required in the environment variable table. The rest are optional: API_BASE_URL for a custom Gemini endpoint, HEAD_SCRIPTS for injecting analytics before the closing head tag, PUBLIC_SECRET_KEY for signing API calls, SITE_PASSWORD for a password gate that accepts several comma-separated values, and GEMINI_MODEL_NAME, which defaults to gemini-2.5-flash.

Where the minimal design becomes a real constraint

SITE_PASSWORD is a shared secret, not authentication. The README describes it as a password for the site, with multiple passwords separated by commas, and notes that without it the site is public. There is no user table, no session model, and no per-user rate limiting described anywhere in the README or the environment table. If two people use the same password, nothing distinguishes them, and every request spends the same API key. For a public deployment that is a quota problem waiting to happen.

Conversation state is the second constraint. Nothing in the documented environment variables or the repository layout points to server-side storage of chat history. Reload the page and the session context is gone. That is consistent with a minimal front end, but it rules the project out as a knowledge base or an audit trail. There is a PUBLIC_MAX_HISTORY_MESSAGES variable in .env.example described as the maximum number of historical messages used for contextual contact, which bounds what is sent to the model, not what is stored.

The third issue is age. The last push to the default branch was on 2026-04-16. Nothing in the repository indicates an archived repository, but a gap of several months on a project that tracks a fast-moving external API is a fact to weigh. Model names and client libraries drift, and the pinned @fuyun/generative-ai patch will need attention when they do.

GeminiProChat compared with a general chat framework

The obvious alternative in this space is LibreChat or one of the other multi-provider chat frameworks. The difference is architectural, not cosmetic. GeminiProChat is built around exactly one provider: @fuyun/generative-ai, a Gemini endpoint, and GEMINI_MODEL_NAME. There is no provider abstraction to configure, because there is no second provider. A framework like LibreChat carries a database, user accounts, and adapters for several APIs, which is why it needs more infrastructure and more configuration before the first message.

There is also a direct lineage question. The README's acknowledgements state that the project is inspired by and based on ChatGPT-Demo, credited for the foundational codebase and features. That explains the package.json name field, which is still chatgpt-api-demo, and it explains the residual OPENAI_API_MODEL and HTTPS_PROXY lines commented out in docker-compose.yml. If you want a fork you can extend in a weekend, that small surface is an advantage. If you want a platform with a plugin ecosystem, it is the reason to choose something else.

A third option is to skip the UI entirely and call the Gemini API from your own application. GeminiProChat is only worth deploying when you specifically want the browser chat interface and the streaming markdown rendering that markdown-it, highlight.js and katex provide.

Licence, upgrades and the cost of keeping it current

The project is MIT licensed, with the LICENSE file at the repository root. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. It says nothing about Google's terms for the Gemini API itself, which are a separate agreement between you and Google, and nothing about the licence of the patched @fuyun/generative-ai dependency. Check those separately; this is a description of what the repository states, not legal advice.

Upgrade cost has two parts. The application side is cheap: pnpm install, pnpm run build, restart the container, and the Dockerfile pins node:18.15-alpine while the README asks for Node v18 or later. The dependency side is where the work sits. The pnpm patchedDependencies entry for @fuyun/[email protected] means a version bump requires re-validating patches/@[email protected], and the Astro 2.x and Solid 1.7.6 versions in package.json are the versions this code was written against. There are no retrieved releases, so there is no changelog to read before upgrading. Treat the pinned patch file as the thing you check first after any dependency update.

Editorial conclusion

Adopt GeminiProChat if you want a small, MIT-licensed chat front end in front of your own Gemini API key and you are comfortable running it as-is: Docker, port 3000, one required environment variable. Do not adopt it if you need multi-user accounts, stored conversation history, or a project with recent activity, since the last push was on 2026-04-16. Verify first that your API key works against the default model gemini-2.5-flash, and check whether SITE_PASSWORD alone matches your access-control needs.

Frequently asked questions

Official sources

1. babaohuang/GeminiProChat on GitHub
2. Issues
3. License: MIT
4. Project website
5. README