Skip to content

Configuration Reference

All configuration is via environment variables, loaded from .env at startup via python-dotenv.

Required

Variable Type Description
URL_BLACKBOARD str Base URL of the workflow engine blackboard API (e.g., http://localhost:3030)
DIR_FUNCTION_BLOCKS str Comma-separated list of directories to scan for function block modules

Worker Identity

Variable Type Default Description
WORKER_NAME str None Human-readable name for this worker instance (appears in engine UI)
WORKER_IP_ADDRESS str None IP address reported to the workflow engine

Timing

Variable Type Default Description
POLL_INTERVAL int 10 Seconds between job polling requests
HEARTBEAT_INTERVAL int 20 Seconds between heartbeat pings
SHUTDOWN_TIMEOUT int 60 Seconds a running job gets to finish after a shutdown request; then the worker deregisters and ends its process, stopping the job wherever it is (the engine fails it as worker-offline)
API_REQUEST_TIMEOUT int 30 Timeout in seconds for individual API requests
RESULT_PUSH_TIMEOUT int 300 Seconds to keep re-sending a job result while the engine is unreachable; keep it below the engine’s stuck-job timeout (12 min by default)
STARTUP_RETRY_TIMEOUT int 120 Seconds to keep retrying worker and function-block registration at startup before exiting 1

Diagnostics

Variable Type Default Description
BLOCKING_DETECTION_THRESHOLD float 0.5 Seconds of blocking before a warning is logged. Set to 0 to disable.
HEALTH_FILE str /tmp/neops-worker-alive File the worker touches on every poll cycle, after every job and on every heartbeat tick, read by the healthcheck. Removed at startup. Set it empty to disable.
HEALTH_STALL_TIMEOUT int 720 Seconds one job may hold up the poll loop before heartbeats stop refreshing HEALTH_FILE, so a hung job turns the worker unhealthy. The default matches the engine’s BLACKBOARD_STUCK_JOB_TIMEOUT (720000 ms, 12 min); raise the two together.

Logging

Every line goes to stdout and, unless pushing is off, to the workflow engine, which stores it in its log store and serves it in the run view. Pushing is best-effort: it never delays a job by more than one push interval and never fails one. Lines of a running job are pushed with the job’s lease (POST /blackboard/job/logs); every other line goes to POST /workers/<uuid>/logs.

Variable Type Default Description
NEOPS_LOG_LEVEL str debug Lowest level written to stdout: error, warn, info or debug
NEOPS_LOG_FORMAT str json when stdout is not a terminal, else text Stdout format. JSON lines carry the run, step, job and worker keys at the top and every other context key under fields
NEOPS_LOG_PUSH_LEVEL str info Lowest level pushed to the engine; off disables pushing
NEOPS_LOG_PUSH_INTERVAL_MS int 1000 Milliseconds between two pushes; a value below 1000 is raised to 1000 with a warning. A job’s lines are also pushed right before its result, and what is left at shutdown gets 5 s
NEOPS_LOG_PUSH_BUFFER_MAX_RECORDS int 10000 Lines held while the engine is unreachable; beyond it the oldest are dropped, and the next push says how many. A value below 5000 refuses startup
NEOPS_LOG_REDACT_EXTRA_KEYS str (unset) Comma-separated key parts masked on top of password, secret, token, passphrase and api_key, e.g. community,pin. Replaces LOG_REDACT_EXTRA_KEYS, which is no longer read
NEOPS_LOG_VERBOSE_RESULTS bool false Log the parameters and result data of every job; by default only a failed job’s are logged

A variable set to the empty string counts as unset.

Testing

Variable Type Default Description
REMOTE_LAB_URL str (unset) Base URL of the remote lab server for integration tests

CMS / GraphQL

CMS & GraphQL

The CMS provides entity data that function blocks access through WorkflowContext. CMS documentation is forthcoming. See the Glossary for a conceptual overview and the engine’s Context concept for how entity data flows into function blocks.

Variable Type Default Description
URL_GRAPHQL str None GraphQL endpoint of the neops CMS (used for data queries)

Example .env

# Required
URL_BLACKBOARD=http://localhost:3030
DIR_FUNCTION_BLOCKS=./my_function_blocks

# Worker identity
WORKER_NAME=lab-worker-01
WORKER_IP_ADDRESS=10.0.0.50

# Timing (optional — defaults are sensible for most deployments)
POLL_INTERVAL=10
HEARTBEAT_INTERVAL=20
SHUTDOWN_TIMEOUT=60

# Diagnostics
BLOCKING_DETECTION_THRESHOLD=0.5
HEALTH_FILE=/tmp/neops-worker-alive

# Logging (optional)
NEOPS_LOG_FORMAT=json
NEOPS_LOG_PUSH_LEVEL=info

# CMS
URL_GRAPHQL=http://localhost:8000/graphql