Skip to main content

Configuration

info

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.

VariableDescriptionDefault
PORTHTTP port for the Load Balancer API.4000
REDIS_HOSTHost for the Redis instance used by BullMQ.localhost
REDIS_PORTPort for the Redis instance used by BullMQ.6379
LB_AUTH_KEYKey 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_INTERVALInterval (ms) for polling Workers for status.1000
WORKER_DISCOVERY_TIMEOUTTimeout (ms) for Worker discovery requests.3000
WORKER_DISCOVERY_RETRIESNumber of retries for Worker discovery.10
WS_HEARTBEAT_INTERVALInterval (ms) for WebSocket heartbeat pings.3000
WS_HEARTBEAT_TIMEOUTTimeout (ms) for WebSocket heartbeat.3000
DASHBOARD_ENABLEDEnable or disable the dashboard interface on /dashboard.false
BULL_BOARD_ENABLEDEnable or disable the BullMQ dashboard interface on /bull.false
LOG_LEVELLog verbosity: debug, info, warn or error.info
MAX_LOGSNumber of log lines to keep in memory (for /logs).1000
TASK_TIMEOUTDeadline (ms) for a task, including time spent waiting in the queue. Also applies to MCP calls.300000
TASK_ATTEMPTSNumber of attempts for a task before failure (see retries).3
REQUEST_BODY_LIMITREST task request body limit (b, kb, mb or gb); MCP has a separate fixed 1MiB limit.10mb
WORKERS_CONFIG_PATHOptional 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_KEY must 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.
  • PORT and REDIS_PORT must be integers between 1 and 65535.
  • MAX_LOGS and TASK_ATTEMPTS must be positive integers; WORKER_DISCOVERY_RETRIES a non-negative integer.
  • WORKER_DISCOVERY_INTERVAL, WORKER_DISCOVERY_TIMEOUT, WS_HEARTBEAT_INTERVAL, WS_HEARTBEAT_TIMEOUT and TASK_TIMEOUT must be integers between 1 and 2147483647 (the largest delay a Node.js timer accepts).
  • REQUEST_BODY_LIMIT must be a positive size such as 10mb.

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 in WORKERS_CONFIG_PATH).
  • Each entry is an http:// or https:// 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, localhost is the Load Balancer container itself: use the Docker network addresses below.
["http://localhost:3000"]
info

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.json file (every WORKER_DISCOVERY_INTERVAL ms) 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 /off endpoint. 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 from workers.json.
  • Status and Health: The Load Balancer continuously monitors each Worker's status via /health and 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​

  1. Three Workers in group screenshot, contract 1, all expose the same function screenshot.
  2. One Worker is updated to add a parameter but keeps CONTRACT=1.
  3. 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.

VariableMeaningDefault
MCP_AUTH_KEYDedicated 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_PATHConfiguration path relative to the application root, or absolutemcp.json
MCP_ALLOWED_ORIGINSComma-separated exact browser origins; native clients need noneEmpty

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.