System Settings & Proxy View
Relevant source files
The following files were used as context for generating this wiki page:
The System Settings and Proxy View manage global configurations for the proxy service. This module allows users to configure upstream request channels, account scheduling policies, quota protection, and proxy pools directly through a web interface. The system persists these settings to /data/settings.json and applies changes immediately without requiring manual configuration file edits.
Sources: dashboard/views/settings/index.ts:13-20, dashboard/locale/dict/system.ts:208-212
Page Architecture and Navigation
The settings interface uses a Single Page Application (SPA) architecture with a side navigation bar and a content panel. The renderSettings function manages the lifecycle of the view, using a DOM cache to preserve input states and scroll positions when switching between sections.
Navigation Structure
The page is divided into logical sections identified by slugs in the URL hash (e.g., #settings/tools). The navigation ensures that each sub-page is directly addressable and shareable.
| Section | Icon | Purpose |
|---|---|---|
| Official Tools | terminal | Configure tool injection and compatibility. |
| Upstream | box | Set request channels and tool fallback logic. |
| System Prompt | chat | Manage global system prompts and placeholders. |
| Scheduling | gauge | Define account picking and concurrency limits. |
| Network | globe | Manage global proxy pools and egress IPs. |
| Models | cpu | Reconcile local models with the upstream catalog. |
| Advanced | settings | Adjust low-level tunables requiring a restart. |
Sources: dashboard/views/settings/index.ts:31-40, dashboard/views/shell/index.ts:70-85
View Lifecycle and State Management
The system uses viewCache to prevent re-fetching data or re-rendering complex components like the Monaco editor when navigating back and forth. The cache is only invalidated upon explicit refreshes, account changes, or user logout.
Proxy Pool and Egress Management
The network section manages the global proxy pool. The proxy view communicates with the /api/proxy endpoint to save and test proxy configurations.
Proxy Configuration
- Global Pool: Users provide one proxy per line (HTTP or SOCKS5).
- Egress Assignment: The system internally assigns accounts to specific proxies to maintain stable egress IPs.
- Testing: Users can test individual proxies or the entire configured pool. The test reports egress IP, country, latency, and upstream connectivity status.
Sources: dashboard/locale/dict/system.ts:6-25, dashboard/views/proxy/index.ts:241-260
Proxy Test Flow
Upstream Channel and Tool Configuration
This section controls how the proxy identifies itself to the upstream and how it handles tool signatures.
Feature Controls
- Upstream Channel: Switches between
official(mirrors official client capture) andlegacy. - Tool Signature Compatibility: Fills in official signed tools to prevent third-party client detection.
- Third-party Tool Carrier: Wraps downstream tools without official equivalents into an official custom tool format for upstream transmission.
- Tool Fallback: Automatically retries requests without tools if the upstream rejects a tool-bearing request.
Sources: dashboard/locale/dict/system.ts:50-95, dashboard/views/proxy/index.ts:320-336
Official Tool Injection
Users can specifically select which of the 37 official tools to inject. If unconfigured, the system auto-trims the list based on the tools declared by the downstream client.
Sources: dashboard/locale/dict/system.ts:98-115, src/web/routes/control/prompts.ts:140-160
Account Scheduling and Quota Protection
The scheduling section defines how the proxy selects accounts for incoming requests and manages session lifecycles to protect Freebucks quota.
Scheduling Modes
- Sticky-first (Default): Concentrates requests on as few accounts as possible to minimize new billing sessions. Requests queue on a full account until a timeout occurs.
- Spread-first: Switches to the next available account immediately when an account reaches its concurrency limit.
Sources: dashboard/locale/dict/system.ts:167-175, dashboard/views/proxy/index.ts:190-205
Quota Protection Policy
The service adheres to a "buy-once, use-fully" policy. Since one admission buys a full hour of access, the service avoids releasing sessions during the paid window unless a slot is required for a different model.
| Setting | Description | Default |
|---|---|---|
idleReleaseSec | Seconds to wait before releasing an idle session (outside paid window). | 60s |
maxNewSessionsPerRequest | Limit on how many new upstream sessions a single request can trigger. | 2 |
accountMaxConcurrency | Simultaneous streams allowed per account. | 2 |
lowBalanceThreshold | Freebucks threshold for grouping accounts as "low balance". | 15 FB |
Sources: dashboard/views/proxy/index.ts:50-65, dashboard/locale/dict/system.ts:213-225, dashboard/locale/dict/views.ts:265-275
Idle Release Advice
The system provides a dynamic recommendation for idleReleaseSec based on the current account pool and model distribution.
- Tight Ratio: If the number of distinct models is close to the number of accounts (ratio ≥ 0.8), it suggests 60s.
- Relaxed Ratio: If models are concentrated (ratio ≤ 0.5), it suggests 300s.
- Balanced: Otherwise, it suggests 120s.
Sources: dashboard/views/proxy/index.ts:108-132
System Prompt Management
The System Prompt section allows users to customize the global system prompt sent to the upstream.
Operational Modes
- Official: Uses the exact captured official system prompt template.
- Custom: Uses user-defined text, supporting dynamic placeholders.
- None: Disables the official system prompt entirely while preserving client-provided system messages.
Sources: dashboard/locale/dict/system.ts:122-140, src/web/routes/control/prompts.ts:153-165
Placeholder Support
The system resolves {CODEBUFF_*} placeholders at runtime. Some values (like CURRENT_DATE and AGENT_NAME) are resolved by the proxy, while others (like PROJECT_ROOT) are resolved to empty strings as they originate from the client's local environment.
Sources: dashboard/locale/dict/system.ts:123-132, cli-bridge/lib/system.ts:102-130
Conclusion
The System Settings & Proxy View serves as the central control plane for the Freebuff Proxy. By abstracting complex billing logic into scheduling modes and providing visual feedback for proxy health and tool compatibility, it enables administrators to optimize resource usage and maintain high compatibility with official upstream protocols without manual configuration overhead.
Sources: dashboard/views/settings/index.ts:13-20, dashboard/locale/dict/views.ts:275-285