Workers and readiness
Queue vs direct execution, worker health, local AI CLIs, and the platform doctor.
Workflow runs either execute in-process (direct mode) or wait in BullMQ for a platform worker (queue mode). Settings → Workers shows the public status the UI and GET /api/v1/workers/status share.
Queue vs direct
REDIS_URL set → queue mode (queue.mode: "bullmq", enabled: true). The worker process (pnpm platform worker / Compose worker) consumes queue workflow-runs. Default concurrency is WORKFLOW_RUNNER_CONCURRENCY (default 4).
REDIS_URL unset → direct mode. POST /api/v1/workflows/{id}/execute runs inline and returns 201 with queued: false.
FLUXUS_E2E=true also forces inline execution even if Redis is configured (test harness). forceQueue is internal to smoke tests.
Execute with Redis: create a queued run, enqueue job id = run id, return 202 and queued: true. If enqueue fails, the run is canceled with reason Workflow queue enqueue failed before dispatch (deterministic runId retries are left queued). Jobs use 3 attempts, exponential backoff from 1s, keep 100 completed / 250 failed jobs.
Status and health
GET /api/v1/workers/status (bearer) or GET /api/workers/status?workspaceId= (session). Optional now= must be a valid date or 400.
Public status includes queue, persistence (durable vs memory), database/migrations, scheduler due counts, health (healthy | degraded | attention plus reasons[]), local AI CLI (no secrets), managed workspaces, agent runtime, side-effect transport names (env var names stripped), deployment readiness labels, active/queued/running counts, recent runs, latest smoke test, checkedAt.
Health turns attention when persistence is not durable, Redis/queue errors, due schedules piling up, required CLI nodes not ready, or deployment blockers. degraded covers milder mismatches (see reasons).
When FLUXUS_WORKSPACE_DERIVED_ACCESS=true, both web and worker also require the durable
FLUXUS_WORKSPACE_SURFACE_READINESS_ARTIFACT produced by the same-release readiness audit. The artifact
contains the checked authorization-inventory digest and completed cutover attestations; missing, unreadable,
or stale artifacts fail startup closed even when environment attestations are present.
Persistence setup statuses: memory_only, database_unreachable, migrations_pending, ready. Hosted environments throw if Prisma is required and DATABASE_URL is empty.
Local AI CLIs
Claude Code and Codex CLI blocks need a session-scoped CLI home on the worker/web image, not a pasted API key in the graph.
v1 (bearer; workspace from the key):
| Method | Path | Body / query |
|---|---|---|
| POST | /api/v1/workers/local-ai-cli/session | action: prepare | verify | disconnect; optional kind: claudeCode | codexCli |
| POST | /api/v1/workers/local-ai-cli/login | { kind } required |
| POST | /api/v1/workers/local-ai-cli/callback | { callbackUrl, kind?, loginSessionId? } |
| POST | /api/v1/workers/local-ai-cli/token | Claude Code only: { kind: "claudeCode", token } |
| GET | /api/v1/workers/local-ai-cli/models?kind= | claudeCode or codexCli (default codexCli) |
Session cookie twins live under /api/workers/local-ai-cli/* and take workspaceId as query/body. Invalid kind / action → 400. Verify that is ready persists credentials from the CLI home; failure to persist returns 500. Token capture is Claude Code only (400 otherwise). Public payloads omit home paths and raw tokens.
Doctor
GET /api/v1/workers/doctor compact report: persistence, database, queue (mode/enabled/error, no Redis URL), scheduler counts, worker health, deployment missing labels, local AI CLI, managed workspaces, agent runtime, optional n8n bundle inventory (bundlePath query), blockers, warnings, nextActions. Optional now= same as status.
Session: GET /api/workers/doctor?workspaceId=&bundlePath=.
CLI equivalent: pnpm platform:doctor -- --strict (and --app-url, --workspace).
Smoke tests
POST /api/v1/workers/smoke-test { targetWorkflowId?, useQueue?, waitForWorkerMs? }. Creates a temporary safe workflow + due schedule, processes that schedule, waits for a terminal run (or waitForWorkerMs in queue mode). HTTP 200 passed, 202 attention (still queued, or target not live-ready), 500 failed. Attention may retain the temp workflow so a worker can finish the job.
targetWorkflowId only audits that workflow (credentials, env flags, CLI, code secrets, missing/placeholder/reconstructed subflows). It does not execute the target’s side effects.
n8n: POST /api/v1/workers/n8n/smoke-test { bundlePath?, useQueue?, waitForWorkerMs? } — import/sync audit + the same safe smoke. LuminAI aliases: /api/v1/workers/luminai/smoke-test (and matching credential/subflow paths).
Worker process
The platform worker starts only after database reachable, migration table present, no pending migrations, and Redis reachable if REDIS_URL is set. Invalid DATABASE_URL / REDIS_URL fails fast as misconfigured. Otherwise it retries with backoff until WORKER_STARTUP_TIMEOUT_MS (default 300s). Failure logs redact connection URLs.
Tick interval: SCHEDULER_POLL_INTERVAL_MS (min 1s, default 60s). Each tick: due workflow schedules, Confluye Command schedules, timer wait sweep, A2A task sweep, pin-data retention (FLUXUS_PIN_DATA_RETENTION_DAYS, default 30, 0 disables), mailer/RSS polls, trigger outbox. File backup/GC ticks only in production. Command FIFO recovery redrives active queued command jobs when the command worker is up.