Freebuff2Opencode Proxy

OpenAI- and Anthropic-compatible proxy server for Freebuff, providing free access to multiple LLM models through a unified API. Translated from the Go implementation Frebuff2API to Node.js/Bun.

models:

country detection + bypass:

Features

OpenAI-Compatible API — Standard /v1/chat/completions and /v1/models endpoints
Anthropic API Support — /v1/messages and /v1/messages/count_tokens with automatic format conversion
Streaming Support — SSE streaming for both OpenAI and Anthropic endpoints
Multi-Token Rotation — Round-robin across multiple auth tokens with automatic CLI token detection
Dynamic Model Registry — Fetches available models from Freebuff source code on GitHub
Free Session Management — Automatic session handling with queue/waiting room and model-lock support
Run Chain Management — Dual run chains (normal + gemini) with context-pruner child run and automatic finalization
Tool Schema Normalization — Resolves $ref and definitions in tool schemas before forwarding
Dashboard UI — Liquid glass effects, Bing wallpaper, OAuth flow, toggleable models
Ad Integration — Fetches and displays upstream ads in the dashboard
Version Auto-Update — Tracks Bun, Freebuff CLI, and SDK versions from upstream sources; shows Windows alert and exits if proxy is outdated
Auto-Config — Automatically configures opencode provider on startup
Warp Plus Proxy — SOCKS5 proxy via Cloudflare WARP for bypassing rate limits on limited-tier sessions
Request Debounce — Global 1.3s minimum gap between requests to prevent upstream rate limiting
429 Retry — Automatic retry on rate limit errors (3 attempts with progressive delay: 3s, 6s, 9s)
HAR-style Fingerprinting — Sends browser-compatible headers (Accept-Encoding, Connection, Host) for upstream compatibility
Agent Validation — Validates agent definitions with upstream before chat requests
Ad Chain + Streak — Completes ad flow and streak check before session creation
Message Normalization — Converts developer → system, injects system prompt

Available Models

The proxy fetches models from Freebuff's TypeScript source. Current user-selectable models:

Model	Agent ID	Tier	Data Training
`minimax/minimax-m2.7`	`base2-free`	Free	No
`minimax/minimax-m3`	`base2-free-minimax-m3`	Free	Yes
`deepseek/deepseek-v4-flash`	`base2-free-deepseek-flash`	Free	Yes
`mimo/mimo-v2.5`	`base2-free-mimo`	Free	No
`google/gemini-3.1-flash-lite-preview`	`base2-free-deepseek-flash`	Free	No
`deepseek/deepseek-v4-pro`	`base2-free-deepseek`	Limited	Yes
`mimo/mimo-v2.5-pro`	`base2-free-mimo-pro`	Limited	No
`moonshotai/kimi-k2.6`	`base2-free-kimi`	Limited	No

Model characteristics:

MiniMax M3 — smartest unlimited model, multimodal. Its API collects data for training.
MiniMax M2.7 — fastest unlimited model.
DeepSeek V4 Pro — smartest. Its API collects data for training.
MiMo 2.5 Pro — smartest and multimodal, but slower.
Kimi K2.6 — balanced and multimodal.
DeepSeek V4 Flash — most efficient. Its API also collects data for training.
MiMo 2.5 — multimodal.
Gemini 3.1 Flash Lite — efficient Google model.

Shortcuts (auto-resolve to full model name):

deepseek-v4-pro → deepseek/deepseek-v4-pro
deepseek-v4-flash → deepseek/deepseek-v4-flash
deepseek-v3.1-terminus → deepseek/deepseek-v4-pro
mimo-v2.5-pro → mimo/mimo-v2.5-pro
mimo-v2.5 → mimo/mimo-v2.5
kimi-k2.6 → moonshotai/kimi-k2.6
minimax-m2.7 → minimax/minimax-m2.7
minimax-m3 → minimax/minimax-m3
gemini-3.1-flash-lite → google/gemini-3.1-flash-lite-preview

Models are toggleable in the dashboard UI.

Warnings

Data Collection & Training

DeepSeek models collect your data for training. The upstream Freebuff source explicitly marks both deepseek/deepseek-v4-pro and deepseek/deepseek-v4-flash with the warning: "Collects data for training". This means your prompts, code, and chat content sent through these models may be used by DeepSeek to train their models.

If you are working with sensitive, proprietary, or confidential code, avoid DeepSeek models. Use minimax/minimax-m2.7 or moonshotai/kimi-k2.6 instead — these do not carry the training data warning.

Account Ban Risk

Using this proxy violates Freebuff's terms of service. The upstream server explicitly rejects direct API calls:

403 error: "Free mode is only available through the freebuff CLI. Install it with 'npm i -g freebuff', then run 'freebuff'. Calling the API directly is not supported and may get your account banned."

This proxy works by omitting the cost_mode field from requests, which bypasses the CLI-only check but does NOT make it authorized. Your Freebuff/Codebuff account may be banned at any time if they detect unusual usage patterns. Use at your own risk.

What Freebuff/Codebuff Collects

Per their Privacy Policy and Privacy docs:

Chat session logs are stored for debugging and service improvement
Your codebase is not stored — the server acts as a thin router forwarding requests to model providers
Usage data: IP address, browser type, device info, page visit duration
Personal data: email, name (if provided), cookies
Analytics: Google Analytics, PostHog, advertising cookies
Data location: transferred to and processed in the United States
Ads: session context and basic profile data are used for ad targeting

They state they do not choose model providers that train on your data in standard modes — but DeepSeek is an exception (see above).

Limited Mode

Freebuff has two access tiers that determine which models you can use:

Tier	Available Models	Session Limit
Free	`minimax/minimax-m2.7`, `minimax/minimax-m3`, `deepseek/deepseek-v4-flash`, `mimo/mimo-v2.5`, `google/gemini-3.1-flash-lite-preview`	none
Limited	Free models + `deepseek/deepseek-v4-pro`, `mimo/mimo-v2.5-pro`, `moonshotai/kimi-k2.6`	5 one-hour sessions per day

Limited-tier sessions are limited to 5 one-hour sessions per day.

There are no premium models — all listed models are available under either the Free or Limited tier. The proxy can route limited-tier requests through a Cloudflare WARP SOCKS5 proxy to bypass rate limits.

When the upstream returns a session_model_mismatch error (e.g., requesting a limited-tier-only model on a free session), the proxy automatically switches to an available free model and retries.

When the upstream returns a model_locked error (the current free session is bound to a different model), the proxy attempts to end the existing session and create a fresh session for the requested model. Only if that fails does it fall back to the locked model.

For limited-tier sessions, the proxy also attempts to route requests through a Warp Plus SOCKS5 proxy (Cloudflare WARP) to bypass rate limits. If Warp Plus fails to start or connect, the proxy falls back to direct connection.

Deployment Hours

Models are available during deployment hours: 9am ET to 5pm PT every day. Outside these hours, requests may be rejected or routed to the fallback model (minimax/minimax-m2.7).

Session States

Sessions can be in various states:

active — Ready to use
queued — Waiting in queue (polled until active)
ended — Session expired (proxy auto-recreates)
superseded — Replaced by a newer session (proxy auto-recreates)
disabled — No session needed

The proxy handles all these states automatically — queued sessions are polled until active, ended/superseded sessions are recreated transparently, and model-locked sessions are ended and re-requested for the desired model when possible.

Supported Countries

Freebuff is available globally in 85+ countries. The live map shows real-time usage. Top countries include:

Country	Active Users
India	119
United States	54
Germany	29
Spain	29
China	22
Indonesia	19
United Kingdom	19
France	18
Vietnam	15
Canada	12

The proxy dashboard displays the upstream server's country_code (e.g. DE) from the session response. Availability may vary by region and time of day.

Authentication

Freebuff requires authentication via GitHub OAuth. There are three ways to get tokens:

Method 1: Freebuff CLI (Recommended)

npm install -g freebuff
freebuff

The CLI will guide you through GitHub OAuth login. After authentication, tokens are saved to:

Windows: C:\Users\<username>\.config\manicode\credentials.json
Linux/macOS: ~/.config/manicode/credentials.json

The proxy automatically detects and loads these tokens on startup.

Method 2: Dashboard OAuth UI

Start the proxy: node proxy.js
Open dashboard: http://localhost:8080
Click "Generate Auth Token" in the token status section
Click the login URL (opens browser)
Authenticate with GitHub at freebuff.com
Token is automatically added to config via polling

Method 3: Manual Configuration

Visit https://freebuff.llm.pm
Complete GitHub OAuth login
Copy your auth token
Add to .config/config.json:

{
  "AUTH_TOKENS": ["your-token-here"]
}

Installation

cd FREEBUFF-PROXY
npm install
node proxy.js

Or with Bun:

bun run proxy.js

Or use the Windows launchers:

start.cmd          # Auto-detects Bun, falls back to Node.js
start-node.cmd     # Forces Node.js

Configuration

Edit .config/config.json or set environment variables:

Key	Description	Default
`LISTEN_ADDR`	Proxy listen address	`:8080`
`UPSTREAM_BASE_URL`	Freebuff backend URL	`https://www.codebuff.com`
`AUTH_TOKENS`	Freebuff auth tokens (array)	`[]`
`REQUEST_TIMEOUT`	Upstream request timeout	`15m`
`API_KEYS`	Client API keys for proxy auth	`[]` (open access)
`OUTBOUND_PROXY`	SOCKS5/HTTP proxy for outbound requests	`null`
`ENABLED_MODELS`	Models to include in the opencode provider config	all registry models

Environment variables override JSON config values.

Setting Up API Keys

By default the proxy is open access — any client can connect. To restrict access, set API_KEYS in .config/config.json:

{
  "API_KEYS": ["my-secret-key-1", "my-secret-key-2"]
}

Or via environment variable (comma-separated):

set API_KEYS=my-secret-key-1,my-secret-key-2
node proxy.js

Clients must then include the key in requests:

# Using x-api-key header
curl -H "x-api-key: my-secret-key-1" http://localhost:8080/v1/models

# Using Authorization header
curl -H "Authorization: Bearer my-secret-key-1" http://localhost:8080/v1/models

Generate a random key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Usage

OpenAI-Compatible Clients

Point your client to http://localhost:8080/v1:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:8080/v1',
  apiKey: 'not-needed'
});

const response = await client.chat.completions.create({
  model: 'minimax/minimax-m2.7',
  messages: [{ role: 'user', content: 'Hello!' }]
});

Anthropic-Compatible Clients

const response = await fetch('http://localhost:8080/v1/messages', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'deepseek/deepseek-v4-pro',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello!' }]
  })
});

opencode Integration

The proxy automatically configures the opencode provider on startup. It writes to ~/.config/opencode/opencode.json (and ~/.opencode/opencode.json on Windows).

The auto-config:

Includes only enabled models (respects ENABLED_MODELS in config)
Prefixes limited model display names with [LIM] (matching the dashboard convention)
Creates a backup (openconfig.b4freebuff.json) on first run
Detects manual model removals from opencode.json and syncs them into ENABLED_MODELS in .config/config.json

To choose which models appear, use the dashboard toggles or set ENABLED_MODELS in .config/config.json:

{
  "ENABLED_MODELS": ["deepseek/deepseek-v4-pro", "minimax/minimax-m3"]
}

Restart opencode after the proxy starts.

Dashboard

Access the dashboard at http://localhost:8080:

Liquid Glass Effects — SVG displacement maps with canvas-generated refraction profiles
Bing Wallpaper — Daily rotating backgrounds via peapix.com
OAuth Token Generation — Browser-based authentication with auto-polling
Toggleable Models — Enable/disable models with checkboxes; changes persist to .config/config.json and propagate to opencode provider on restart
Token Status — View active tokens, sessions, instance IDs, country code, and remaining session time with live countdown
Country Display — Shows the upstream server's country code (e.g. DE) from the session response, with >US indicator when Warp Plus proxy is active
Session Countdown — Live Xm Ys left countdown in the Auth Token Status header, updated every second
Ad Integration — Gravity ad provider via upstream /api/v1/ads (surface: waiting_room), 30s rotation, impression tracking (/api/v1/ads/impression), toggleable display (checkbox in dashboard), and localStorage caching
SS Mode — Blur tokens for screenshots
Configuration Forms — Edit listen address, upstream URL, timeouts

API Endpoints

Core API

Method	Path	Description
`GET`	`/healthz`	Health check with token and session status
`GET`	`/v1/models`	OpenAI models list
`POST`	`/v1/chat/completions`	OpenAI chat completions (streaming supported)
`POST`	`/v1/messages`	Anthropic messages (auto-converted to OpenAI)
`POST`	`/v1/messages/count_tokens`	Anthropic token counting

Management API

Method	Path	Description
`GET`	`/api/config`	Get current configuration
`POST`	`/api/config`	Update configuration
`GET`	`/api/tokens`	List configured tokens (masked)
`POST`	`/api/auth/start`	Start OAuth flow
`POST`	`/api/auth/status`	Check OAuth status (auto-saves token)
`GET`	`/api/models`	List models from registry
`GET`	`/api/bg`	Get Bing wallpaper URL
`GET`	`/api/ads`	Fetch upstream ads
`POST`	`/api/ads/impression`	Record ad impression

Architecture

proxy.js (~2218 lines)
├── Version Tracking     — Auto-updates Bun/CLI/SDK versions from upstream
├── Config System        — JSON + env vars + CLI token auto-detection
├── ModelRegistry        — Parses TypeScript sources from GitHub
├── UpstreamClient       — HTTP client with HAR-style headers, agent validation, ad chain
├── TokenPool            — Session management with mutex locking
├── WarpPlusManager      — SOCKS5 proxy via warp-plus binary for rate limit bypass
├── Run Chain Helpers    — Normal (with context-pruner) and Gemini run lifecycle
├── Message Normalization — developer→system, Buffy prompt injection
├── Tool Schema Norm.    — $ref resolution and schema normalization
├── HTTP Handlers        — OpenAI + Anthropic + management endpoints
├── OAuth Flow           — Browser-based GitHub authentication
└── Server Startup       — Validation, prewarm, token reload loop

dashboard.html (1023 lines)
├── Liquid Glass Engine  — Canvas-based displacement/specular maps
├── OAuth UI             — Token generation with polling
├── Model Manager        — Toggleable model checkboxes
├── Ad System            — Upstream ads with impression tracking
└── Configuration UI     — Settings forms

Startup Flow

loadConfig() — Load .config/config.json + env vars (auto-creates .config/ if missing)
loadFreebuffCLITokens() — Auto-detect CLI tokens from ~/.config/manicode/credentials.json
checkAndUpdateVersions() — Fetch latest versions from upstream sources
ModelRegistry.start() — Fetch and parse model definitions from GitHub
setupOpencodeConfig() — Write opencode provider config (respects ENABLED_MODELS, adds [LIM] for limited models, detects manual model removals and syncs to config)
validateAllTokens() — Verify each token via createSession()
TokenPool — Initialize with valid tokens
http.createServer() — Start HTTP server
setInterval — Token reload check every 5 minutes
setInterval — Version check every 1 hour

Troubleshooting

No Valid Tokens

If you see "No tokens configured":

Run freebuff CLI to authenticate
Use dashboard OAuth UI
Manually add token to .config/config.json

Port Already in Use

netstat -ano | findstr :8080
taskkill /PID <pid> /F

Or change port in .config/config.json:

{
  "LISTEN_ADDR": ":9000"
}

Models Not Showing

Check network connectivity to GitHub:

https://raw.githubusercontent.com/CodebuffAI/codebuff/main/common/src/constants/free-agents.ts
https://raw.githubusercontent.com/CodebuffAI/codebuff/main/common/src/constants/freebuff-models.ts

Syntax Errors

Multiple edits can create duplicate code blocks:

node --check proxy.js

Warp Plus Issues

If Warp Plus fails to start or the SOCKS5 proxy on port 8086 is not reachable:

The proxy automatically falls back to direct connection
Check if another process is using port 8086
The warp-plus.exe binary is downloaded automatically on first use
The last working WARP endpoint (IP:port) is cached and reused on restart; if connectivity fails, the cache is cleared and a new endpoint is fetched

Model Lock Errors

If you see session_model_mismatch errors:

Your session is in limited tier and the requested model is not available on it
The proxy automatically switches to an available free/limited model and retries
No user action needed — this is handled transparently

If you see model_locked errors:

Your token currently has an active free session bound to another model
The proxy attempts to end that session and create a new one for the requested model
If the upstream rejects the unlock attempt, the proxy falls back to the locked model

Dependencies

freebuff (^0.0.96) — CLI token detection
node-forge (^1.4.0) — Cryptographic operations
node-fetch (^2.7.0) — HTTP client with SOCKS5 proxy support
socks-proxy-agent (^8.0.0) — SOCKS5 proxy agent for Warp Plus
https-proxy-agent (^9.1.0) — HTTP CONNECT proxy support
socks (^2.8.9) — SOCKS protocol implementation

Plus Node.js built-ins: fs, path, os, http, https, url, crypto.

Credits

Inspired by freebuff-proxy by ferdiunal
Original Go implementation: Frebuff2API by Quorinex
Freebuff and Codebuff for the backend API
freebuff2api_rs for version tracking

License

MIT

Name		Name	Last commit message	Last commit date
AGENTS.md		AGENTS.md
DASHBOARD_GUIDE.md		DASHBOARD_GUIDE.md
README.md		README.md
dashboard.html		dashboard.html
package.json		package.json
proxy.js		proxy.js
skills.md		skills.md
start-node.cmd		start-node.cmd
start.cmd		start.cmd

Latest commit

History

Folders and files

Repository files navigation