Configuration
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.
| Variable | Description | Default |
|---|---|---|
AUTH_KEY | Key for REST tasks and administration; MCP uses its own token. | Required |
LB_AUTH_KEY | Internal Load Balancer key; required even standalone, distinct from AUTH_KEY and identical to the Load Balancer's LB_AUTH_KEY. | Required |
PORT | HTTP port for the Worker API. | 3000 |
WEBSOCKET_PORT | Port for the WebSocket server (for real-time slot updates with the Load Balancer ; change only if you use it). | 3001 |
GROUP | Worker group for routing; the example sets default. | Required |
CONTRACT | The contract version implemented by this Worker. | 1 |
SLOTS | Number of parallel tasks the Worker can handle. | 10 |
DEFAULT_TIMEOUT | Default timeout (ms) for functions that do not set their own timeout. | 30000 |
LOG_LEVEL | Log verbosity: debug, info, warn or error. | info |
MAX_LOGS | Number of log lines to keep in memory (for /logs). | 1000 |
WEBHOOK_TIMEOUT | Timeout (ms) for webhook calls. | 5000 |
WEBHOOK_MAX_RETRIES | Number of times to retry a failed webhook. | 3 |
WEBHOOK_RETRY_DELAY | Delay (ms) between webhook retries. | 1000 |
WEBHOOK_HEADERS | JSON object of headers to send with webhook requests (see the warning below). | {} |
OPENAPI_ENABLED | Enable OpenAPI documentation endpoints (/docs and /openapi, unauthenticated). | false |
REQUEST_BODY_LIMIT | REST task request body limit; MCP has a separate fixed 1MiB limit. | 10mb |
CUSTOM_CONFIG | Example 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.
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 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_KEYandLB_AUTH_KEYare required, must not have leading or trailing whitespace, and must be distinct.GROUPis required and must not have leading or trailing whitespace.CONTRACTmust be a positive integer.PORTandWEBSOCKET_PORTmust be integers between 1 and 65535.LOG_LEVELmust bedebug,info,warnorerror.MAX_LOGSandSLOTSmust be positive integers.DEFAULT_TIMEOUT,WEBHOOK_TIMEOUTandWEBHOOK_RETRY_DELAYmust be integers between 1 and 2147483647 (ms).WEBHOOK_MAX_RETRIESmust be an integer greater than or equal to 0.WEBHOOK_HEADERSmust be a JSON object whose values are strings.REQUEST_BODY_LIMITmust be a positive size such as10mb(unitsb,kb,mborgb).
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.ymlreach the container. The MCP Compose override also loads.envfor 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.
| Variable | Meaning | Default |
|---|---|---|
MCP_AUTH_KEY | Dedicated 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_PATH | Configuration path relative to the Worker's application root (the folder containing package.json), or absolute. | mcp.json |
MCP_ALLOWED_ORIGINS | Comma-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.