Workers

Workers execute queued jobs.

They are long-running runtime processes with explicit startup, shutdown, metrics, and queue configuration.

Start Workers

Run workers directly:

forj worker
./bin/app worker

Run workers with other enabled runtimes in local standalone mode:

forj app
./bin/app run

Runtime Boundary

The worker command starts the App lifecycle, starts the queue worker runtime, blocks while workers run, and shuts down on cancellation.

This makes workers a clear operational boundary separate from HTTP and scheduler processes when needed.

By default, worker starts workers for every configured generated queue. Use --queue when a process should work only one named queue:

forj worker --queue reports
./bin/app worker --queue reports

Repeat the flag to work a subset:

./bin/app worker --queue emails --queue reports

Configuration

Common worker-related variables include:

QUEUE_DRIVER=workerpool
QUEUE_WORKERS=30
QUEUE_NAME=default
QUEUE_SHUTDOWN_TIMEOUT=10s

Named queues use QUEUE_<NAME>_* variables. If a named queue does not set its own driver, it inherits QUEUE_DRIVER.

QUEUE_DRIVER=redis
QUEUE_EMAILS_WORKERS=6
QUEUE_REPORTS_WORKERS=2

Prefer named queues for operational priority. Give higher-priority work more worker capacity, and run dedicated worker --queue <name> processes when it needs separate scaling, CPU, memory, or deployment policy.

Some drivers support additional backend-specific queue weighting. Keep that as a driver detail; use Queue for the full package behavior.

Metrics

When metrics are enabled, worker processes can expose a dedicated metrics endpoint. The generated worker command includes metrics configuration when the App has metrics support.

Use metrics, inspects, logs, queue backend state, and Lighthouse to understand worker behavior.

Scaling

Use standalone mode first for local development.

Use explicit worker processes when production needs:

• independent scaling
• different resource limits
• restart isolation
• separate deploy topology
• queue-specific concurrency tuning
• queue-specific priority through worker allocation

The job code should not change when topology changes.

Common Mistakes

Common mistakes

• Do not run workers from HTTP handlers.
• Do not assume forj app is the only runtime shape.
• Do not start multiple scheduler processes accidentally when scaling workers.
• Do not ignore shutdown timeouts for long-running jobs.
• Do not hide worker startup in constructors or package globals.

Next Steps

• Runtime Topology explains process shapes.
• Jobs explains job handlers.
• Operations covers production runtime behavior.