Configuration
All configuration is via environment variables. No config files are required. The engine reads .env if present (via dotenv).
Runtime & Logging
| Variable | Default | Description |
|---|---|---|
NODE_ENV |
development |
development, production, or test |
DEBUG |
false |
Enable verbose validation errors |
LOG_LEVEL |
info |
error, warn, info, debug. Defaults to debug when DEBUG=true |
LOG_FORMAT |
pretty |
json (production) or pretty (development). Auto-selects json in production |
PORT |
3030 |
HTTP server port |
Database
The engine requires PostgreSQL 15+.
| Variable | Default | Description |
|---|---|---|
POSTGRES_HOST |
localhost |
Database hostname |
POSTGRES_PORT |
5434 |
Database port |
POSTGRES_USER |
postgres |
Database user |
POSTGRES_PASSWORD |
unsafe |
Database password (override in production) |
Change the default password
The default password unsafe is for local development only. Always set a strong
password in production deployments.
Database Setup
Run migrations to create the schema:
npx mikro-orm migration:fresh # development (drops and recreates)
npx mikro-orm migration:up # production (applies pending migrations)
CMS Connection
The engine communicates with the neops CMS via GraphQL for entity acquisition and locking.
| Variable | Default | Description |
|---|---|---|
NEOPS_CMS_URL |
http://localhost:8000/graphql |
CMS GraphQL endpoint |
NEOPS_CMS_TOKEN |
unsafe |
Authentication token for CMS API (override in production) |
CMS dependency
The CMS is required for entity acquisition and locking. Without a CMS connection,
workflows that use acquire clauses or seedEntity other than global will fail
during the resource discovery phase.
Worker Management
These thresholds control how the engine detects and handles unresponsive workers. The defaults cascade: unreachable (2 min) -> offline (3x = 6 min) -> stuck job (2x offline = 12 min).
| Variable | Default | Description |
|---|---|---|
WORKER_UNREACHABLE_THRESHOLD_MS |
120000 (2 min) |
Time since last heartbeat before worker is marked unreachable |
WORKER_OFFLINE_THRESHOLD_MS |
360000 (6 min) |
Time since last heartbeat before worker is marked offline and its jobs are failed |
WORKER_OFFLINE_DELETE_THRESHOLD_MS |
86400000 (24 h) |
Time before an offline worker is soft-deleted |
WORKER_CLEANUP_ENABLED |
true |
Enable automatic deletion of stale workers |
WORKER_CLEANUP_INTERVAL_MS |
3600000 (1 h) |
How often to check for stale workers |
Blackboard (Job Management)
| Variable | Default | Description |
|---|---|---|
BLACKBOARD_JOB_CHECK_INTERVAL |
60000 (1 min) |
How often the engine checks for stuck jobs |
BLACKBOARD_STUCK_JOB_TIMEOUT |
720000 (12 min) |
Jobs in POLLED state longer than this are auto-failed |