Account Scheduling & Routing
Relevant source files
The following files were used as context for generating this wiki page:
Account Scheduling & Routing manages the distribution of downstream requests across a multi-account pool of Freebuff credentials. It handles automatic failover, sticky session reuse, and quota protection to ensure high availability despite upstream limitations like daily session caps and concurrency slots.
The system operates on a "Hot Session First" principle, prioritizing the reuse of existing active sessions for the same model to minimize costs and avoid the overhead of new session admissions. When failures occur, it automatically cycles through eligible accounts based on their current health and quota status.
Sources: src/AGENTS.md:73-88, README_EN.md:72-88, dashboard/locale/dict/accounts.ts:255-259
Scheduling Principles and Logic
The scheduler follows a strict priority list when selecting accounts for a request. It favors stability and efficiency over load balancing to avoid triggering upstream "account farm" detection.
Sticky-First Scheduling (Drain, not Rotate)
The proxy never平摊 (evenly distributes) concurrency across multiple accounts by default. It prioritizes candidates in the following order:
- Hot Sessions: Existing active sessions for the requested model.
- Recently Used: Accounts that have been used but do not currently have an active session for that model.
- Fresh Accounts: Accounts that have never been scheduled.
Sources: src/AGENTS.md:82-84, README_EN.md:126-128
Failover and Cooldown Rules
The system reacts differently depending on the type of error returned by the upstream:
- Account-level failures: Errors like
rate_limited,spend_limited,ip_capped, orbannedtrigger a cooldown for the entire account. - Model-level failures:
model_unavailableonly cools down that specific model for the account. - Transient errors: Slot-based errors (e.g.,
purchase_capacity) or 503 errors cause the scheduler to skip the account without triggering a long-term cooldown. - Client errors (4xx): These do not trigger account switching.
Sources: src/AGENTS.md:78-81, README_EN.md:126-128
Quota Management and Protection
The system implements dual-gate quota protection. Scheduling depends on both time-based units and currency-based balance.
Dual-Gate Enforcement
Both gates must pass for an account to be eligible for scheduling:
- Freebucks (FB): The actual currency balance. This is the primary refusal criterion for the upstream.
- Session Units: Measured as
rateLimitsByModel.recentCount(typically capped at 6).
Sources: src/AGENTS.md:73-75, dashboard/views/overview/accounts/sections.ts:58-81
Paid Window Preservation
An admit action buys a full hour for a specific model. During this hour, additional requests have zero marginal cost. To protect this investment:
- The service never releases a session just because it is idle during the paid window.
- Switching models during a paid hour is prevented, as it would void the remaining time.
Sources: src/AGENTS.md:76-77, README_EN.md:92-106, dashboard/locale/dict/accounts.ts:223-228
Account State Workflow
The following diagram illustrates the lifecycle of an account within the scheduling pool:
The diagram shows how accounts transition between different states (Active, Banned, Exhausted, Warning) based on upstream feedback and balance checks.
Sources: dashboard/views/overview/accounts/sections.ts:13-33, src/AGENTS.md:78-81
Routing and Classification
Accounts are classified into UI sections based on their "worst-case" status. This classification directly influences their eligibility in the candidates.ts logic.
Classification Tiers
| Section | Tone | Scheduling Behavior |
|---|---|---|
| Banned | Error | Excluded; never scheduled. |
| Exhausted | Error | Excluded; no remaining Freebucks or daily limit reached. |
| Warning | Warn | Temporarily cooled down due to rate limits or probe failures. |
| Low Balance | Warn | Eligible; balance below threshold (default 15 FB) but can still afford the model. |
| Active | OK | Eligible; has live sessions or recent usage. |
| Fresh | Idle | Eligible; never used. |
Sources: dashboard/views/overview/accounts/sections.ts:13-33, dashboard/views/overview/accounts/sections.ts:39-56
Scheduling Controls
Users can manually exclude accounts from the routing pool using the "Schedule" switch.
- On (Default): The account is eligible for selection and new session admission.
- Off: The account is excluded from the candidate list. This does not release existing sessions; purchased windows are kept until they expire.
Sources: README_EN.md:72-83, dashboard/locale/dict/accounts.ts:187-198
Technical Implementation Details
The scheduling logic is distributed between the backend runtime and the proxy transport layer.
Core Components
- AccountRuntimes: Manages the multi-account pool, model aliases, and quota tracking.
- SessionManager: Handles the lifecycle of upstream sessions (admit, reuse, release).
- Proxy Transport: Routes downstream requests to the assigned account and handles tool name remapping.
- CLI-Bridge Delegate: The actual upstream communication is delegated to a Bun-based bridge that mimics the official client request shape.
Sources: src/AGENTS.md:7-14, src/AGENTS.md:112-118, cli-bridge/AGENTS.md:5-9
Request Path Sequence
The sequence diagram below describes the routing of a single chat completion request:
The diagram shows the delegation flow from the initial request through the scheduler and the bun bridge to the upstream provider.
Sources: src/AGENTS.md:67-71, README_EN.md:113-124, cli-bridge/AGENTS.md:5-9
Summary
Account Scheduling & Routing ensures that Freebuff free quotas are utilized efficiently by maintaining a sticky, failover-capable pool of accounts. By enforcing dual-gate quota checks and preserving paid session windows, the system maximizes uptime while minimizing the risk of account bans or unnecessary credit consumption. All scheduling states are persistent and manageable through the web console, requiring no manual configuration file edits.
Sources: src/AGENTS.md:85-88, README_EN.md:72-88