Configuration
For detailed security recommendations (HTTPS, etc.), see the Deployment page.
Runtime settings and secrets come from the environment, loaded from .env at startup. Worker URLs live in workers.json; MCP targets and function allowlists live in mcp.json. Both JSON configurations support live reload.
Environment Variables
Below are the main environment variables used by the Load Balancer. All variables are set in your .env file.
| Variable | Description | Default |
|---|---|---|
PORT | HTTP port for the Load Balancer API. | 4000 |
REDIS_HOST | Host for the Redis instance used by BullMQ. | localhost |
REDIS_PORT | Port for the Redis instance used by BullMQ. | 6379 |
LB_AUTH_KEY | Key for the Load Balancer endpoints and for LB-to-Worker calls. Must be identical on the Load Balancer and every Worker. Use token characters only (hex recommended, e.g. openssl rand -hex 32): it is also sent as a WebSocket subprotocol. | Required |
WORKER_DISCOVERY_INTERVAL | Interval (ms) for polling Workers for status. | 1000 |
WORKER_DISCOVERY_TIMEOUT | Timeout (ms) for Worker discovery requests. | 3000 |
WORKER_DISCOVERY_RETRIES | Number of retries for Worker discovery. | 10 |
WS_HEARTBEAT_INTERVAL | Interval (ms) for WebSocket heartbeat pings. | 3000 |
WS_HEARTBEAT_TIMEOUT | Timeout (ms) for WebSocket heartbeat. | 3000 |
DASHBOARD_ENABLED | Enable or disable the dashboard interface on /dashboard. | false |
BULL_BOARD_ENABLED | Enable or disable the BullMQ dashboard interface on /bull. | false |
LOG_LEVEL | Log verbosity: debug, info, warn or error. | info |
MAX_LOGS | Number of log lines to keep in memory (for /logs). | 1000 |
TASK_TIMEOUT | Deadline (ms) for a task, including time spent waiting in the queue. Also applies to MCP calls. | 300000 |
TASK_ATTEMPTS | Number of attempts for a task before failure (see retries). | 3 |
REQUEST_BODY_LIMIT | REST task request body limit (b, kb, mb or gb); MCP has a separate fixed 1MiB limit. | 10mb |
WORKERS_CONFIG_PATH | Optional override for the Worker URL-list file, relative to the working directory or absolute. | Application-root workers.json |
The table lists runtime defaults. The sample .env overrides some values for Docker: REDIS_HOST=redis, a 3000ms discovery interval, and both optional dashboards enabled. Keep the dashboards disabled unless they are protected (see Dashboard and BullMQ).
Validation
The configuration is validated at startup, and an invalid value stops the Load Balancer with an error:
LB_AUTH_KEYmust be set and must not start or end with whitespace. A key containing characters that WebSocket subprotocols reject is accepted, but the Load Balancer logs a warning and real-time slot updates fall back to polling.PORTandREDIS_PORTmust be integers between 1 and 65535.MAX_LOGSandTASK_ATTEMPTSmust be positive integers;WORKER_DISCOVERY_RETRIESa non-negative integer.WORKER_DISCOVERY_INTERVAL,WORKER_DISCOVERY_TIMEOUT,WS_HEARTBEAT_INTERVAL,WS_HEARTBEAT_TIMEOUTandTASK_TIMEOUTmust be integers between 1 and 2147483647 (the largest delay a Node.js timer accepts).REQUEST_BODY_LIMITmust be a positive size such as10mb.
Example .env
PORT=4000
REDIS_HOST=redis
REDIS_PORT=6379
LB_AUTH_KEY=<random-key>
WORKER_DISCOVERY_INTERVAL=3000
WORKER_DISCOVERY_TIMEOUT=3000
WORKER_DISCOVERY_RETRIES=10
WS_HEARTBEAT_INTERVAL=3000
WS_HEARTBEAT_TIMEOUT=3000
DASHBOARD_ENABLED=true
BULL_BOARD_ENABLED=true
LOG_LEVEL=info
MAX_LOGS=1000
TASK_TIMEOUT=300000
TASK_ATTEMPTS=3
REQUEST_BODY_LIMIT=10mb
Worker List
General
- The list of available Workers is managed in the file
workers.json(at the project root, or the path set inWORKERS_CONFIG_PATH). - Each entry is an
http://orhttps://URL (e.g.,http://localhost:3000) pointing to a Worker instance, without credentials, query string or fragment. - This file is read at startup and can be hot-reloaded for dynamic cluster management. If the file is invalid, unreadable or deleted, the Load Balancer keeps the last valid list and logs the error once (until a different error occurs). Write
[]to remove all Workers. - When the Load Balancer runs in Docker,
localhostis the Load Balancer container itself: use the Docker network addresses below.
["http://localhost:3000"]
It is strictly recommended to use HTTPS for your Workers if they are exposed on the Internet (this is not necessary when using the Load Balancer, which can be the only one exposed). The LB connects to the Worker WebSocket port using ws:// for HTTP Worker URLs and wss:// for HTTPS URLs. HTTPS deployments must also terminate TLS on the advertised WebSocket port.
Docker network
When using Docker on your Mac/Windows machine, your Load Balancer and Workers can communicate using the host.docker.internal domain. Example of a workers.json file when you're working on your machine:
["http://host.docker.internal:3000"]
This works out of the box, as host.docker.internal is resolved by Docker.
That said, it won't work on a Linux-type production machine, which is why the Load Balancer and Andera Workers use an andera-net network. In this configuration, this syntax must be used for production:
["http://service-name:3000"]
Where service-name is the Docker Compose service name.
Worker Management
The Load Balancer supports dynamic, hot-reloadable management of Workers:
- Hot Reload: The Load Balancer periodically reloads the
workers.jsonfile (everyWORKER_DISCOVERY_INTERVALms) and re-discovers all Workers. You can add or remove Workers at runtime without restarting the Load Balancer. - Adding a Worker: Add its URL to
workers.json. The Load Balancer will discover and include it in routing if it is healthy and contract-valid. - Removing a Worker: Remove its URL from
workers.json. The Load Balancer will stop routing new tasks to it as soon as it is no longer in the list. - Best Practice: Before removing a Worker, set it to maintenance mode by calling its
/offendpoint. This ensures the Worker finishes any tasks in progress and does not accept new ones. Once all tasks are complete, you can safely remove it fromworkers.json. - Status and Health: The Load Balancer continuously monitors each Worker's status via
/healthand WebSocket. Workers in maintenance or unreachable are excluded from routing until they are back online or set to/on.
Groups and Contracts
Workers behind the Load Balancer are organized by group and contract version:
- Group (
GROUP): Each Worker declares a group (e.g.,default,screenshot,translate). A group represents a logical set of Workers able to process the same type of tasks. - Contract (
CONTRACT): Each Worker declares a contract version (integer). A contract defines the interface (available functions and their parameters) for a group.
Consistency Constraints
- All Workers in the same group and contract version must expose exactly the same interface (functions and parameters).
- The Load Balancer fetches the interface of each Worker (via
/health) and validates that all Workers for a given group/contract are consistent. Function names and parameter rules are compared; parameter descriptions are not. - If a Worker in a group/contract exposes a different interface, it is marked as invalid and excluded from routing.
- When submitting a task, the Load Balancer only routes to valid Workers matching the requested group and contract.
- If no valid Worker is available for a group/contract, the task is rejected with an error.
What happens if contracts mismatch?
- If Workers in the same group declare the same contract version but expose different functions or parameters, they are excluded from routing.
- This ensures that all tasks for a group/contract are processed consistently and safely.
- Best practice: When changing the interface of a group, increment the contract version (
CONTRACT=2, etc.) on all relevant Workers.
Example
- Three Workers in group
screenshot, contract1, all expose the same functionscreenshot. - One Worker is updated to add a parameter but keeps
CONTRACT=1. - The Load Balancer marks this Worker as invalid and does not route tasks to it until its interface matches the others or the contract version is incremented.
Optional MCP
Configure exposed targets in mcp.json and keep credentials in the environment. See MCP setup.
| Variable | Meaning | Default |
|---|---|---|
MCP_AUTH_KEY | Dedicated agent bearer token. Must contain no whitespace and differ from LB_AUTH_KEY, otherwise MCP stays disabled and a warning is logged. | Empty: disabled |
MCP_CONFIG_PATH | Configuration path relative to the application root, or absolute | mcp.json |
MCP_ALLOWED_ORIGINS | Comma-separated exact browser origins; native clients need none | Empty |
Each MCP target's workerAuthKeyEnv names an additional environment variable containing the AUTH_KEY of that target's Workers. Selections reload live; environment values require restart.