Environment Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Environment configuration manages the settings, variables, and runtime parameters that control the behavior of the freebuff-proxy service. The system prioritizes lightweight deployment and ease of use, centralizing most day-to-day operations in a web console while utilizing environment variables and YAML files for core service bootstrapping.
Sources: README_EN.md:12-16, CLAUDE.md:65-67
Configuration Hierarchy and Loading
The service loads configuration by merging multiple sources in a specific order of precedence. Hardcoded defaults serve as the baseline, followed by YAML configuration files, and finally environment variable overrides.
Precedence Logic
- Environment Variables: Highest priority for server operations (host, port, credentials).
- YAML Configuration: Mid-priority; values in
config.yamloverride internal defaults. - Default Values: Hardcoded in the system as a fallback.
Sources: src/config/load.ts:1-7, src/config/load.ts:114-124
Configuration Loading Flow
The loadConfig function orchestrates the assembly of the runtime configuration object.
The diagram shows the sequential merging process where environment variables and hardcoded upstream constants finalize the configuration state.
Sources: src/config/load.ts:109-146
Core Environment Variables
The system uses specific FREEBUFF_PROXY_* environment variables to control server behavior, logging, and data persistence.
| Variable Name | Configuration Target | Description |
|---|---|---|
FREEBUFF_PROXY_DATA_DIR | server.dataDir | Sets the absolute or relative path for data storage. |
FREEBUFF_PROXY_HOST | server.host | Defines the host address the proxy binds to (default: 0.0.0.0). |
FREEBUFF_PROXY_PORT | server.port | Defines the listening port (default: 8787). |
FREEBUFF_PROXY_LOG_LEVEL | logging.level | Sets the minimum log severity level. |
FREEBUFF_PROXY_CONFIG | - | Explicitly defines the path to the YAML config file. |
ADMIN_USERNAME | users.defaultAdminUsername | Sets the initial administrator username. |
ADMIN_PASSWORD | users.defaultAdminPassword | Sets the initial administrator password. |
FREEBUFF_UPSTREAM_API_BASE | upstream.apiBase | Overrides the hardcoded upstream URL (testing only). |
Sources: src/config/load.ts:27-38, src/config/load.ts:110-113, src/config/load.ts:126-130
Upstream API Configuration
The service enforces strict rules regarding the upstream API base URL to prevent deployment failures. The UPSTREAM_API_BASE is hardcoded to https://www.codebuff.com to ensure consistency and avoid 401 errors caused by missing subdomains.
- Hardcoding Requirement: The
config.yamlfile must not containapi_baseto prevent user error. - Environment Override: Only the
FREEBUFF_UPSTREAM_API_BASEvariable can override this value, typically for local mock testing or contract validation.
Sources: scripts/check-config-consistency.ts:1-20, src/config/load.ts:126-130
Path Resolution and Sanitization
The configuration module resolves relative paths against the project root and cleans proxy URLs to prevent runtime errors during egress agent construction.
Directory Resolution
The system automatically resolves the data directory and credentials directory. If a relative path is provided for the data directory, it is resolved against the module's project root. If the credentialsDir is not explicitly set, it defaults to a credentials sub-folder within the data directory.
Sources: src/config/load.ts:74-92
Proxy Sanitization Logic
Proxy lists are processed to ensure only valid URL strings are used.
The sanitization process prevents ERR_INVALID_URL errors when the proxy agent attempts to connect to upstream.
Sources: src/config/load.ts:51-66
Client Fingerprint Environment
The proxy generates a specific freebuff_client_env descriptor to mimic the official client fingerpint. This string aggregates terminal, system, and network facts.
Descriptor Composition
The environment descriptor uses a versioned semicolon-separated string (e.g., v1;in=0;out=0;...). Key fields include:
in/out: TTY status (set to0for service environments).ci: Set to1if running in environments like GitHub Actions.px: Proxy bucket classification (none,loopback, orremote).tls: SSL/TLS rejection status based onNODE_TLS_REJECT_UNAUTHORIZED.
Sources: src/upstream/fingerprint/client-env.ts:31-41, src/upstream/fingerprint/client-env.ts:103-128
Tunables and Web Console Settings
While environment variables handle bootstrap settings, "Tunables" are high-level settings managed through the web console.
| Tunable Category | Key Components |
|---|---|
| Upstream | Channel selection (legacy vs official), tool signature settings. |
| Scheduling | Concurrency limits, scheduling mode (sticky vs spread), and wait timeouts. |
| Quota | Idle release seconds, session budgets, and balance thresholds. |
| Prompts | System prompt modes (official, custom, none) and custom text. |
Sources: src/web/routes/control/settings/read.ts:106-146
Persistence of Settings
Settings saved in the web console are stored in settings-store.ts logic. Tunables that require a service restart are merged into the main config object upon subsequent startup.
Sources: src/web/routes/control/settings/read.ts:155-165
Conclusion
Environment configuration in freebuff-proxy ensures that the service remains ultra-lightweight while providing robust controls for administrators. By utilizing a strict hierarchy of environment variables for core operations and a web-based tunable system for service logic, the project minimizes manual configuration file editing while maintaining the security and stability of upstream connections.