Gemini Gateway 🚀

English | 中文

An intelligent AI gateway that supercharges your applications by providing a unified API for Google's Gemini models, complete with load balancing, failover, and a user-friendly management dashboard.

✨ Key Features

• Unified API Interface: Access Gemini models through multiple API formats. Use standard model names like gpt-4o or claude-3-opus, and let the gateway handle the rest.
• Dynamic Model Routing: Configure custom routing rules through the UI. Map any incoming model name (including wildcards like gpt-4-*) to a specific downstream Gemini model. Set priorities for wildcard matches.
• Smart Load Balancing: Intelligently distributes requests across a pool of Gemini API keys to maximize throughput.
• Automatic Failover: Automatically retries failed requests with the next available key, ensuring high availability.
• Persistent & Dynamic: Manage API keys, model mappings, and configurations on-the-fly through a web UI without service restarts.
• Secure & Scalable: Built with security in mind, ready for production deployment with Docker.
• Management Dashboard: A sleek dashboard to monitor usage, manage keys, and configure model routing rules in real-time.

🛠️ Tech Stack

• Framework: Next.js (App Router)
• Language: TypeScript
• Database: SQLite (with Drizzle ORM)
• UI: Tailwind CSS, Shadcn UI
• Containerization: Docker

🚀 Getting Started

Self-Hosting with Docker (Recommended)

1. Clone the repository:

   git clone https://github.com/jonthanliu/gemini-gateway.git
   cd gemini-gateway

2. Configure your environment: Copy the example environment file. This is the single source of truth for your gateway's configuration.

   cp .env.example .env

   Now, edit the .env file. All fields are mandatory.

   # --- Security (Mandatory) ---
   # This is the password for the web admin panel.
   AUTH_TOKEN="your_super_secret_admin_password"
   
   # A comma-separated list of tokens that your API clients will use for authentication.
   ALLOWED_TOKENS="client_token_1,client_token_2"
   
   # A strong, random secret for signing Web UI session tokens (JWT).
   # You can generate one here: https://www.uuidgenerator.net/
   WEB_JWT_SECRET="your_strong_and_random_jwt_secret"
   
   # --- Database (Do not change for Docker) ---
   DATABASE_URL="file:/app/data/prod.db"

3. Run with Docker Compose:

   docker-compose up --build -d

4. Access the Admin Panel & Onboarding:

   • Open your browser and navigate to http://YOUR_SERVER_IP:3000.
   • You will be prompted to log in. Use the password you set for AUTH_TOKEN in the .env file.
   • After logging in, you will be guided to add your first Gemini API Key.
   • Once the key is added, you will be redirected to the main dashboard.

Your gateway is now live and ready to serve requests!

Using the Pre-built Docker Image (Easiest)

If you prefer not to build the image locally, you can directly use the latest image we build and publish automatically on ghcr.io via GitHub Actions.

1. Create a docker-compose.yml file: On your server, create a file named docker-compose.yml and paste the following content. It will pull the latest main branch image.

   version: "3.8"
   
   services:
     app:
       image: ghcr.io/jonthanliu/gemini-gateway:main
       restart: always
       ports:
         - "3000:3000"
       volumes:
         - ./data:/app/data
       env_file:
         - .env

2. Create and configure your .env file: Just like the previous method, create an .env file and fill in your configuration.

   cp .env.example .env
   # Edit your .env file...

3. Start the service:

   docker-compose up -d

   Docker will automatically pull the image from ghcr.io and start the service. This method skips the entire build process on your local machine, making deployment faster.

🔌 Client Usage Examples

Once your gateway is deployed, you can configure your favorite clients to use it. For the best experience and security, it is highly recommended to configure your own domain name for the gateway.

Native Gemini Clients (Recommended)

For clients that support the Google Gemini API, this is the most direct way to configure.

VSCode (Cline) & CherryStudio

1. In your client's model settings, select Gemini as the model provider.
2. Set the API Base URL or Endpoint to your gateway address:

   http://<your_domain_or_server_ip>:3000
   

3. Set the API Key to one of the tokens you defined in the ALLOWED_TOKENS list in your .env file.

Anthropic-Compatible Clients

For tools that use the Anthropic SDK (e.g., claude-code), you can point to this gateway by setting environment variables.

# Set your gateway address
export ANTHROPIC_BASE_URL=http://<your_domain_or_server_ip>:3000

# Set one of the tokens from your ALLOWED_TOKENS list
export ANTHROPIC_API_KEY=<your_client_token>

# Now run your tool
claude

OpenAI-Compatible Clients

For general-purpose clients like LobeChat or ChatGPT-Next-Web, you can use the OpenAI-compatible interface.

1. In your client's settings, find the OpenAI-Compatible or Custom Model option.
2. Set the API Base URL or Endpoint to:

   http://<your_domain_or_server_ip>:3000/openai/v1
   

3. Set the API Key to one of the tokens from your ALLOWED_TOKENS list.
4. Select a model name that you have configured in the Model Mappings panel (e.g., gpt-4o). The gateway will automatically route the request to the appropriate Gemini model.

⚠️ Important Notes & Disclaimer

• Password Recovery: If you forget your admin password, simply edit the AUTH_TOKEN in your .env file and restart the container (docker-compose restart).
• No More Cron Jobs: The key health check mechanism has been refactored. The gateway now automatically disables failing keys for a short period. You no longer need to set up an external cron job.
• AI-Generated Code: This project was primarily developed by an AI assistant. While it is functional, it may contain unexpected behaviors.
• Use at Your Own Risk: This is an open-source project provided "as is". The authors and contributors are not responsible for any damages or losses resulting from its use, including but not to API key leakage or financial loss. Please review the code and security configurations carefully before deploying in a production environment.
• Contributions Welcome: We welcome pull requests! Please note that contributions will also be reviewed by an AI.

🙏 Acknowledgements

This project is inspired by and builds upon the great work of others in the open-source community.

• gemini-balance by snailyp: The original Python project that provided the core inspiration for this gateway.
• lemmy by badlogic: For demonstrating robust and scalable application architecture.
• gemini-balance-nextjs: The predecessor to this project, which laid the groundwork for the current implementation.
• openai-gemini by PublicAffairs: A project that provides OpenAI-compatible API for Gemini models.