Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
The freebuff-proxy project converts Freebuff free quota into an OpenAI-compatible API endpoint. This service manages multi-account pools, session admission, and request shaping while passing streaming and non-streaming responses to downstream agents.
Sources: README_EN.md:4-10, README.md:12-14
System Requirements
The project runs on Node.js version 22 or higher. It utilizes a lightweight architecture based on node:22-alpine with only two runtime dependencies: undici and yaml.
Sources: package.json:11-13, README_EN.md:33-35, CLAUDE.md:38-41
Deployment Steps
Deploy the proxy using Docker Compose for a consistent environment.
- Clone the repository: `git clone https://github.com/HengXin666/freebuff-proxy.git%60
- Navigate to the directory:
cd freebuff-proxy - Prepare environment variables:
cp .env.example .env(It is recommended to setADMIN_PASSWORD). - Start the service:
docker compose up -d. This pulls the prebuilt GHCR image. - Access the console at
http://<host-ip>:8787/.
Sources: README_EN.md:37-43, README.md:41-47
Service Initialization Flow
The following diagram illustrates the deployment and initial login flow:
The diagram shows the sequential steps from cloning the repository to having the proxy ready for API requests.
Sources: README_EN.md:45-48, README.md:49-52
Connecting Downstream Agents
Downstream agents require three specific values to interact with the proxy.
| Setting | Value |
|---|---|
base_url | http://<host-ip>:8787/v1 |
api_key | Generated in console Me page (sk-fb-...) |
model | Any name returned by GET /v1/models |
Sources: README_EN.md:58-64, README.md:62-68
API Authentication and Storage
Internal user accounts and API keys are stored in data/users.json. The UserStore class manages these credentials, ensuring admin presence and handling password hashing via scrypt.
Sources: src/web/store/session/user-store.ts:13-20, src/web/store/session/user-store.ts:60-65
Core API Endpoints
The proxy exposes several endpoints for chat completion, model discovery, and health monitoring.
| Path | Method | Purpose |
|---|---|---|
/v1/chat/completions | POST | Main chat path (session + passthrough) |
/v1/models | GET | List available model catalog |
/v1/freebuff/status | GET | View account and session snapshots |
/healthz | GET | Liveness probe |
Sources: README_EN.md:73-81, README.md:77-85
Configuration Management
Day-to-day operations occur entirely through the web console. Manual editing of config.yaml is not required for standard usage as it only serves as a fallback.
| Configuration | Location | Persistent Storage |
|---|---|---|
| Global Proxies | Console Proxy settings | /data/proxies.json |
| Upstream Accounts | Console Overview | /data/credentials/ |
| Users / API Keys | Console Users | /data/users.json |
| Admin Password | .env variable | .env |
Sources: README_EN.md:88-97, README.md:92-101, CLAUDE.md:52-54
Operations and Maintenance
Log Inspection
If ADMIN_PASSWORD is not set in .env, the service generates a random password on the first start. Retrieve it using:
docker compose logs freebuff-proxy | grep -A6 "首次启动"
Sources: README_EN.md:45, README.md:49
Network Configuration
The service uses host networking (network_mode: host). It listens on 0.0.0.0 at the port defined by FREEBUFF_PROXY_PORT. In host mode, Docker ports mappings are ignored.
Sources: CLAUDE.md:47-50, README_EN.md:50-51
Quota and Scheduling
Upstream billing is based on Freebucks (FB). The proxy never releases a session early because an early DELETE does not refund quota. Users can toggle the Schedule switch for individual accounts to exclude them from the candidate pool without releasing already paid sessions.
Sources: README_EN.md:104-109, README_EN.md:118-122
This guide provides the necessary steps to transition from repository cloning to a functional OpenAI-compatible proxy using Freebuff resources. Detailed logic for specific components can be found in the Configuration Reference.
Sources: README_EN.md:179-190