freebuff-gateway 0.1.0

Free OpenAI-compatible API gateway — route requests to free LLM providers with zero-code setup. Save thousands on API costs.

FreeBuff Gateway

Free OpenAI-compatible API gateway — route requests to free LLM providers with zero-code setup. Save thousands on API costs.

---

Why?

OpenAI API costs add up fast. FreeBuff Gateway is a transparent proxy that sits between your existing tools (anything that speaks OpenAI API) and free LLM providers:

• Primary: FreeBuff (freebuff.llm.pm) — free MiniMax M2.7, Gemini Flash, and more
• Fallback: OpenRouter free tier — additional free models
• Last resort: Local Ollama — completely free, runs on your machine

Just point your existing code at http://localhost:8080/v1 and keep using gpt-4, gpt-3.5-turbo, or any model name — the gateway maps it to the real free model automatically.

---

Quick Start

# Install
pip install freebuff-gateway

# Run the setup wizard
freebuff-gateway setup

# Start the gateway
freebuff-gateway start --port 8080

That's it. Your existing OpenAI-compatible tools now talk to free LLMs.

---

Features

Feature	Description
OpenAI-compatible API	Drop-in replacement for api.openai.com
Streaming + Non-streaming	Full SSE streaming support
Multi-provider failover	FreeBuff → OpenRouter → Ollama
Model mapping	gpt-4 → MiniMax M2.7, gpt-3.5 → MiniMax M2, etc.
Rate limiting	Per-IP and per-key sliding window
Usage dashboard	Beautiful HTML dashboard with live stats
Cost tracking	See how much you've saved vs. OpenAI pricing
SQLite storage	Lightweight, no external DB needed
CLI-first	freebuff-gateway start, setup, status, config

---

Usage

Start the server

# Default port 8080
freebuff-gateway start

# Custom port
freebuff-gateway start --port 9090 --host 127.0.0.1

Test with curl

# List models
curl http://localhost:8080/v1/models

# Chat completion (non-streaming)
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# Chat completion (streaming)
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "stream": true,
    "messages": [{"role": "user", "content": "Write a poem"}]
  }'

Dashboard

Open http://localhost:8080/v1/dashboard to see:

• Total tokens saved
• Costs avoided (vs. OpenAI pricing)
• Provider breakdown
• Recent request log

Status

freebuff-gateway status

Shows configuration and usage statistics.

---

Configuration

Environment variables

Variable	Default	Description
FREEBUFF_TOKEN	—	FreeBuff auth token (from freebuff.llm.pm)
FREEBUFF_BASE_URL	https://freebuff.llm.pm/v1	FreeBuff API endpoint
OPENROUTER_API_KEY	—	OpenRouter API key (free tier)
OLLAMA_BASE_URL	http://localhost:11434/v1	Local Ollama endpoint
PORT	8080	Gateway listen port
HOST	0.0.0.0	Gateway bind address
RATE_LIMIT_PER_IP	60	Max requests per minute per IP
RATE_LIMIT_PER_KEY	120	Max requests per minute per API key

Config file

Configuration is stored in ~/.config/freebuff-gateway/config.json.

Model mapping

The gateway automatically maps common model names:

Your request	Actual model
gpt-4	minimax/minimax-m2.7 (via FreeBuff)
gpt-4-turbo	minimax/minimax-m2.7
gpt-3.5-turbo	minimax/minimax-m2
claude-3-opus	minimax/minimax-m2.7
claude-3-haiku	google/gemini-2.5-flash-lite
gemini-pro	google/gemini-2.5-flash-lite

You can customize mappings in ~/.config/freebuff-gateway/config.json.

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Your Application                      │
│  (OpenAI SDK, curl, LangChain, any OpenAI-compatible)    │
└─────────────────────┬───────────────────────────────────┘
                      │ POST /v1/chat/completions
                      ▼
┌─────────────────────────────────────────────────────────┐
│              FreeBuff Gateway (localhost:8080)            │
│                                                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │ Rate     │→│ Model    │→│ Provider │→│ Usage  │ │
│  │ Limiter  │  │ Mapper   │  │ Router   │  │ DB     │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
│                                      │                   │
└──────────────────────────────────────┼───────────────────┘
                                       │
              ┌────────────────────────┼────────────────┐
              ▼                        ▼                ▼
     ┌────────────────┐      ┌──────────────┐    ┌──────────┐
     │ FreeBuff       │      │ OpenRouter   │    │ Ollama   │
     │ (Primary)      │      │ (Fallback 1) │    │(Fallback2)│
     │ free.llm.pm    │      │ openrouter.ai│    │ localhost │
     └────────────────┘      └──────────────┘    └──────────┘

Provider Setup

FreeBuff (Primary)

1. Visit https://freebuff.llm.pm
2. Log in or create an account
3. Open DevTools → Application → Local Storage → copy your auth token
4. Run freebuff-gateway setup and paste the token

Or set FREEBUFF_TOKEN=your_token_here in your environment.

OpenRouter (Fallback)

1. Visit https://openrouter.ai/keys
2. Create a free API key
3. Run freebuff-gateway setup or set OPENROUTER_API_KEY

Ollama (Local Fallback)

1. Install Ollama from https://ollama.com
2. Pull a model: ollama pull llama3.2
3. Start Ollama: ollama serve
4. The gateway will auto-detect it at http://localhost:11434

---

Development

# Clone and install in dev mode
git clone https://github.com/freebuff-gateway/freebuff-gateway.git
cd freebuff-gateway
pip install -e .

# Run tests
pytest

---

License

MIT

---

FreeBuff Gateway is not affiliated with OpenAI, FreeBuff, OpenRouter, or Ollama.