Project Introduction
Relevant source files
The following files were used as context for generating this wiki page:
Freebuff-proxy transforms Freebuff free quotas into OpenAI-compatible API endpoints. The service manages Freebuff credentials via a multi-account pool, handles session admission, and shapes requests to match official client signatures. It supports both streaming and non-streaming responses, passing them through to downstream agents unchanged.
Sources: README_EN.md:4-10, README.md:12-14
The project targets ultra-lightweight deployment using Node 22 and Docker. It operates on a "Bring Your Own Account" model rather than "Bring Your Own Key" (BYOK), specifically prohibiting third-party providers like OpenRouter or OpenAI-compatible keys in the upstream. All operational management, including account imports and proxy settings, occurs through a built-in web console.
Sources: CLAUDE.md:27-31, AGENTS.md:42-46, README_EN.md:23-28
System Architecture
The architecture consists of a Node.js main service and a specialized cli-bridge component. The main service handles user authentication, account scheduling, and API routing. It RPC-delegates upstream requests to cli-bridge, which executes using the Bun runtime to match official client behaviors exactly, including tool signatures and system templates.
The diagram illustrates the request flow from downstream agents through the proxy layers to the Freebuff upstream.
Sources: README_EN.md:129-140, README.md:144-150
Core Components
| Component | Technology | Responsibility |
|---|---|---|
| Main Service | Node.js 22 | User management, API key validation, account scheduling, and web console. |
| CLI Bridge | Bun | Protocol reverse engineering, official tool mapping, and device signing. |
| Dashboard | TypeScript (Vanilla) | Web interface for configuration, account login, and monitoring. |
| Data Store | JSON Files | Persistent storage for proxies, credentials, users, and account states in /data. |
Sources: CLAUDE.md:33-40, README_EN.md:83-93, AGENTS.md:48-55
Key Features and Mechanisms
Multi-Account Scheduling
The system uses a pool of Freebuff accounts to overcome upstream limitations. Each account includes a "Schedule" switch in the console. When enabled, the account enters the candidate list for new sessions. When disabled, the account is excluded from new admissions, though existing paid sessions are retained until expiration.
Sources: README_EN.md:98-106, README.md:104-110
Quota and Billing Protection
Freebuff bills in "Freebucks" (FB), where one session admission purchases a full hour of access. The proxy protects user quota by preventing idle session releases during the paid hour.
- Hourly Buyout: Admission buys one hour; margin cost for additional requests is zero.
- Refund Policy: Early deletion does not refund Freebucks; the service maintains the session.
- Live Pricing: The service reads
freebucks.pricesfrom upstream responses rather than hardcoding values.
Sources: README_EN.md:112-120, README.md:118-125
Request Shaping and Tool Mapping
The src/upstream/signals module translates downstream tool calls into official upstream formats. This translation layer ensures compatibility with official client fingerprints.
The sequence shows how tool names and parameters are mapped between client and official formats.
Sources: src/upstream/signals/AGENTS.md:7-12, README_EN.md:144-148
API and Integration
Downstream agents connect using standard OpenAI parameters. The proxy provides several management and status endpoints.
| Path | Method | Description |
|---|---|---|
/v1/chat/completions | POST | Main endpoint for chat sessions. |
/v1/models | GET | Returns the available model catalog. |
/v1/freebuff/status | GET | Snapshots account and session states. |
/healthz | GET | Liveness probe for the service. |
Sources: README_EN.md:74-81, README.md:78-85
System Prompt Requirements
The upstream requires specific opening prefixes for system messages to pass "free-mode" gate checks. The proxy automatically ensures messages start with the correct identity string based on the agent version:
- Standard Opening:
You are Buffy, the strategic coding assistant. - Base3 Opening:
You are Buffy, the coding agent behind Codebuff.
Sources: src/free-mode/system.ts:10-23, src/free-mode/system.ts:60-70
Development and Deployment
The project enforces strict code quality through "gates" (17 automated checks). Deployment is recommended via Docker in host networking mode to simplify proxy connectivity.
# Quick start command
docker compose up -d
Sources: README_EN.md:46-51, CLAUDE.md:65-72, package.json:37-45
The proxy maintains high technical accuracy by deriving all behaviors from official client captures, ensuring that parameters like repository_stats and current_date are rendered dynamically to match expected official signatures.
Sources: test/suites/entries/verify/system-prompt-dynamic.ts:13-25, CLAUDE.md:92-97