Skip to main content

Configuration

info

For detailed security recommendations (HTTPS, etc.), see the Deployment page.

Runtime settings and secrets come from environment variables, loaded from .env at startup. src/config/index.ts extends Worker Core configuration. MCP function selection lives separately in mcp.json and reloads without restarting.

Environment Variables​

Below are the main environment variables used by the Base Worker.

VariableDescriptionDefault
AUTH_KEYKey for REST tasks and administration; MCP uses its own token.Required
LB_AUTH_KEYInternal Load Balancer key; required even standalone, distinct from AUTH_KEY and identical to the Load Balancer's LB_AUTH_KEY.Required
PORTHTTP port for the Worker API.3000
WEBSOCKET_PORTPort for the WebSocket server (for real-time slot updates with the Load Balancer ; change only if you use it).3001
GROUPWorker group for routing; the example sets default.Required
CONTRACTThe contract version implemented by this Worker.1
SLOTSNumber of parallel tasks the Worker can handle.10
DEFAULT_TIMEOUTDefault timeout (ms) for functions that do not set their own timeout.30000
LOG_LEVELLog verbosity: debug, info, warn or error.info
MAX_LOGSNumber of log lines to keep in memory (for /logs).1000
WEBHOOK_TIMEOUTTimeout (ms) for webhook calls.5000
WEBHOOK_MAX_RETRIESNumber of times to retry a failed webhook.3
WEBHOOK_RETRY_DELAYDelay (ms) between webhook retries.1000
WEBHOOK_HEADERSJSON object of headers to send with webhook requests (see the warning below).{}
OPENAPI_ENABLEDEnable OpenAPI documentation endpoints (/docs and /openapi, unauthenticated).false
REQUEST_BODY_LIMITREST task request body limit; MCP has a separate fixed 1MiB limit.10mb
CUSTOM_CONFIGExample Worker-specific setting (see src/config/index.ts).default-value

The table lists runtime defaults. The sample .env.example sets GROUP=default and keeps OPENAPI_ENABLED=false.

Keys

Generate AUTH_KEY and LB_AUTH_KEY as two distinct random values, for example with openssl rand -hex 32. LB_AUTH_KEY must be the same value on the Load Balancer and on every Worker it manages; otherwise the Load Balancer never discovers the Worker. A hexadecimal value is recommended, because the Load Balancer also sends this key as a WebSocket subprotocol.

Webhook headers

WEBHOOK_HEADERS are sent to whatever webhook URL an authenticated REST caller supplies. Do not put secrets there that API callers must not learn.

Validation​

The configuration is validated at startup. An invalid value stops the Worker with an error message naming the variable:

  • AUTH_KEY and LB_AUTH_KEY are required, must not have leading or trailing whitespace, and must be distinct.
  • GROUP is required and must not have leading or trailing whitespace.
  • CONTRACT must be a positive integer.
  • PORT and WEBSOCKET_PORT must be integers between 1 and 65535.
  • LOG_LEVEL must be debug, info, warn or error.
  • MAX_LOGS and SLOTS must be positive integers.
  • DEFAULT_TIMEOUT, WEBHOOK_TIMEOUT and WEBHOOK_RETRY_DELAY must be integers between 1 and 2147483647 (ms).
  • WEBHOOK_MAX_RETRIES must be an integer greater than or equal to 0.
  • WEBHOOK_HEADERS must be a JSON object whose values are strings.
  • REQUEST_BODY_LIMIT must be a positive size such as 10mb (units b, kb, mb or gb).

Usage​

  • Environment settings are loaded at startup; restart after changing them.
  • These variables control authentication, routing, logging, slot management, and advanced features.
  • With Docker Compose, only the variables declared in docker-compose.yml reach the container. The MCP Compose override also loads .env for MCP settings.

Example .env​

# Required: generate two distinct values, for example with `openssl rand -hex 32`.
# LB_AUTH_KEY must be the same value as the Load Balancer's LB_AUTH_KEY.
AUTH_KEY=<distinct-random-key>
LB_AUTH_KEY=<same-value-as-the-load-balancer>
PORT=3000
WEBSOCKET_PORT=3001
GROUP=default
CONTRACT=1
SLOTS=10
DEFAULT_TIMEOUT=30000
LOG_LEVEL=info
MAX_LOGS=1000
WEBHOOK_TIMEOUT=5000
WEBHOOK_MAX_RETRIES=3
WEBHOOK_RETRY_DELAY=1000
WEBHOOK_HEADERS={}
# /docs and /openapi need no authentication.
OPENAPI_ENABLED=false
REQUEST_BODY_LIMIT=10mb
# Example Worker-specific setting read by src/config.
CUSTOM_CONFIG=default-value

# Optional MCP: keep empty to disable.
MCP_AUTH_KEY=
MCP_CONFIG_PATH=mcp.json
MCP_ALLOWED_ORIGINS=

Optional MCP​

The local mcp.json selects functions exposed to agents. MCP is enabled only when both MCP_AUTH_KEY is valid and the configuration file exists. See Worker MCP setup.

VariableMeaningDefault
MCP_AUTH_KEYDedicated agent token without whitespace, distinct from AUTH_KEY and LB_AUTH_KEY; otherwise MCP is disabled with a warning in the logs.Empty: disabled
MCP_CONFIG_PATHConfiguration path relative to the Worker's application root (the folder containing package.json), or absolute.mcp.json
MCP_ALLOWED_ORIGINSComma-separated exact browser origins; native clients need none.Empty

No extra credential configuration is needed for local functions. Selections reload live; environment values require restart.