freebuff2api-openai-proxy

# Freebuff2API OpenAI Proxy > Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection. Freebuff2API is an OpenAI-compatible proxy server written in Go that translates standard OpenAI API requests into Freebuff's backend format. It enables any OpenAI-compatible client, SDK, or CLI tool to use Freebuff's free models without modification. ## What It Does - Exposes standard OpenAI endpoints (`/v1/chat/completions`, etc.) - Dynamically randomizes client fingerprints to mimic official Freebuff SDK behavior - Rotates multiple auth tokens on a configurable interval - Routes outbound traffic through an optional HTTP proxy - Ships as a multi-arch Docker image for easy deployment ## Getting Auth Tokens Before deploying, obtain one or more Freebuff auth tokens: **Method 1 — Web (easiest):** Visit [https://freebuff.llm.pm](https://freebuff.llm.pm), log in with your Freebuff account, and copy the displayed token. **Method 2 — Freebuff CLI:** ```bash npm i -g freebuff freebuff # follow login prompts ``` Token is stored at: - **Linux/macOS:** `~/.config/manicode/credentials.json` - **Windows:** `C:\Users\<username>\.config\manicode\credentials.json` ```json { "default": { "authToken": "fa82b5c1-e39d-4c7a-961f-d2b3c4e5f6a7" } } ``` Copy the `authToken` value — this is your `AUTH_TOKENS` value. ## Installation & Deployment ### Docker (Recommended) ```bash # Single token docker run -d --name freebuff2api \ -p 8080:8080 \ -e AUTH_TOKENS="$FREEBUFF_TOKEN" \ ghcr.io/quorinex/freebuff2api:latest # Multiple tokens (comma-separated for higher throughput) docker run -d --name freebuff2api \ -p 8080:8080 \ -e AUTH_TOKENS="$FREEBUFF_TOKEN_1,$FREEBUFF_TOKEN_2,$FREEBUFF_TOKEN_3" \ ghcr.io/quorinex/freebuff2api:latest # With HTTP proxy and API key protection docker run -d --name freebuff2api \ -p 8080:8080 \ -e AUTH_TOKENS="$FREEBUFF_TOKEN" \ -e API_KEYS="$MY_PROXY_API_KEY" \ -e HTTP_PROXY="$HTTP_PROXY_URL" \ ghcr.io/quorinex/freebuff2api:latest ``` ### Docker Compose ```yaml # docker-compose.yml version: "3.8" services: freebuff2api: image: ghcr.io/quorinex/freebuff2api:latest container_name: freebuff2api restart: unless-stopped ports: - "8080:8080" environment: AUTH_TOKENS: "${FREEBUFF_TOKENS}" API_KEYS: "${PROXY_API_KEYS}" ROTATION_INTERVAL: "6h" REQUEST_TIMEOUT: "15m" # Or mount a config file: # volumes: # - ./config.json:/app/config.json # command: ["-config", "/app/config.json"] ``` ```bash # .env file FREEBUFF_TOKENS=token1,token2,token3 PROXY_API_KEYS=my-secret-key ``` ### Build from Source Requirements: Go 1.23+ ```bash git clone https://github.com/Quorinex/Freebuff2API.git cd Freebuff2API go build -o freebuff2api . # Run with config file ./freebuff2api -config config.json # Run with environment variables AUTH_TOKENS="$FREEBUFF_TOKEN" ./freebuff2api ``` ```bash docker build -t freebuff2api . docker run -d -p 8080:8080 -e AUTH_TOKENS="$FREEBUFF_TOKEN" freebuff2api ``` ## Configuration ### config.json ```json { "LISTEN_ADDR": ":8080", "UPSTREAM_BASE_URL": "https://codebuff.com", "AUTH_TOKENS": ["token1", "token2"], "ROTATION_INTERVAL": "6h", "REQUEST_TIMEOUT": "15m", "API_KEYS": ["my-proxy-api-key"], "HTTP_PROXY": "" } ``` ### Configuration Reference | Key / Env Var | Default | Description | |---|---|---| | `LISTEN_ADDR` | `:8080` | Proxy listen address | | `UPSTREAM_BASE_URL` | `https://codebuff.com` | Freebuff backend URL | | `AUTH_TOKENS` | — | Freebuff auth tokens (JSON array or comma-separated) | | `ROTATION_INTERVAL` | `6h` | How often to rotate tokens | | `REQUEST_TIMEOUT` | `15m` | Upstream request timeout | | `API_KEYS` | `[]` | Client API keys for proxy auth (empty = open access) | | `HTTP_PROXY` | `""` | HTTP proxy for outbound requests | **Note:** Environment variables override JSON file values when both are set. ## Using the Proxy Once running, point any OpenAI-compatible client at `http://localhost:8080`: ### curl ```bash curl http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $PROXY_API_KEY" \ -d '{ "model": "claude-3-5-sonnet", "messages": [{"role": "user", "content": "Hello!"}] }' ``` If `API_KEYS` is empty (open access), omit the Authorization header or use any value: ```bash curl http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "claude-3-5-sonnet", "messages": [{"role": "user", "content": "Hello!"}]}' ``` ### Python (openai SDK) ```python from openai import OpenAI import os client = OpenAI( base_url="http://localhost:8080/v1", api_key=os.environ.get("PROXY_API_KEY", "unused"), # any value if API_KEYS is empty ) response = client.chat.completions.create( model="claude-3-5-sonnet", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Explain async/await in Python."}, ], ) print(response.choices[0].message.content) ``` ### Streaming ```python from openai import OpenAI import os client = OpenAI( base_url="http://localhost:8080/v1", api_key=os.environ.get("PROXY_API_KEY", "unused"), ) stream = client.chat.completions.create( model="claude-3-5-sonnet", messages=[{"role": "user", "content": "Write a short poem."}], stream=True, ) for chunk in stream: if chunk.choices[0].delta.content is not None: print(chunk.choices[0].delta.content, end="", flush=True) print() ``` ### Node.js (openai SDK) ```javascript import OpenAI from "openai"; const client = new OpenAI({ baseURL: "http://localhost:8080/v1", apiKey: process.env.PROXY_API_KEY ?? "unused", }); const response = await client.chat.completions.create({ model: "claude-3-5-sonnet", messages: [{ role: "user", content: "Hello from Node.js!" }], }); console.log(response.choices[0].message.content); ``` ### LangChain (Python) ```python from langchain_openai import ChatOpenAI import os llm = ChatOpenAI( model="claude-3-5-sonnet", openai_api_base="http://localhost:8080/v1", openai_api_key=os.environ.get("PROXY_API_KEY", "unused"), ) result = llm.invoke("What is the capital of France?") print(result.content) ``` ## Common Patterns ### Multi-Token Setup for Higher Throughput Collect tokens from multiple Freebuff accounts: ```bash # config.json approach { "AUTH_TOKENS": [ "token-account-1", "token-account-2", "token-account-3" ], "ROTATION_INTERVAL": "3h" } # Environment variable approach (comma-separated) export AUTH_TOKENS="token1,token2,token3" ``` ### Securing the Proxy with API Keys ```json { "API_KEYS": ["secret-key-for-team", "another-key-for-ci"] } ``` Clients must then include `Authorization: Bearer secret-key-for-team`. ### Using with HTTP Proxy (Corporate/Regional) ```json { "HTTP_PROXY": "http://proxy.company.com:3128" } ``` Or via environment: ```bash docker run -d --name freebuff2api \ -p 8080:8080 \ -e AUTH_TOKENS="$FREEBUFF_TOKEN" \ -e HTTP_PROXY="$CORPORATE_PROXY" \ ghcr.io/quorinex/freebuff2api:latest ``` ### Health Check / Verify Running ```bash # Check the proxy is responding curl -s http://localhost:8080/v1/models | jq . # Or a minimal chat request curl -s http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"claude-3-5-sonnet","messages":[{"role":"user","content":"ping"}]}' \ | jq '.choices[0].message.content' ``` ## Troubleshooting ### Proxy returns 401 Unauthorized - If `API_KEYS` is configured, ensure your client sends `Authorization: Bearer <key>` matching one of the configured keys. - If `API_KEYS` is empty `[]`, the proxy is open — no auth header needed. ### Auth token rejected / 403 from upstream - Token may be expired — re-fetch from [https://freebuff.llm.pm](https://freebuff.llm.pm) or re-run `freebuff` CLI. - Check `AUTH_TOKENS` is set correctly (not empty, no extra whitespace). ### Request timeouts - Increase `REQUEST_TIMEOUT` beyond default `15m` for very long completions: ```json { "REQUEST_TIMEOUT": "30m" } ``` ### Connection refused on localhost:8080 - Confirm the container/process is running: `docker ps` or `ps aux | grep freebuff2api` - Check `LISTEN_ADDR` — if set to a specific interface (e.g., `127.0.0.1:8080`), ensure you're connecting to the right address. - For Docker, verify the port mapping: `-p 8080:8080` ### Docker container exits immediately ```bash # Check logs docker logs freebuff2api # Common cause: AUTH_TOKENS not set docker run --rm -e AUTH_TOKENS="$FREEBUFF_TOKEN" ghcr.io/quorinex/freebuff2api:latest ``` ### Multiple tokens not rotating - Verify tokens are comma-separated (env var) or a JSON array (config file). - Check `ROTATION_INTERVAL` is a valid Go duration string: `"1h"`, `"30m"`, `"6h"`, etc. ## Project Structure (Source) ``` Freebuff2API/ ├── main.go # Entry point, config loading, server startup ├── config.json # Default config file (gitignored if contains secrets) ├── Dockerfile # Multi-arch Docker build ├── go.mod / go.sum # Go module dependencies ├── README.md └── README_zh.md ``` ## Key CLI Flag ```bash ./freebuff2api -config /path/to/config.json ``` The only CLI flag is `-config` to specify an alternate config file path. All other configuration is via the JSON file or environment variables.