Workers

A worker is a Node.js program you run on your own machine or server. It asks the FinOpsBricks Orchestrator for work, runs your code for each step, and reports back. Your code, your data and your credentials for other systems stay on the worker; the Orchestrator schedules runs and keeps a record of each one.

You want to…	Start here
Go from nothing to a step running on your machine	Get started
Understand lines, stations, steps and workpieces	Concepts
Run and debug a step locally	Run steps locally
See what's in each station's bins	Inspect lines and workpieces

Beta

Running a worker needs an Orchestrator account: sign up, then create an organisation in the Orchestrator. Running steps locally with fob-worker needs no account. fob-worker is in Beta; see Beta limits.

Video coming soon

Build and debug a worker step with fob-worker (3–4 min)

The pieces#

Piece	What it is	Where
Orchestrator	Stores your lines and stations, runs them on a schedule or on demand, and records every run as a work record	orchestrator.finopsbricks.com
Worker repo	Your Node.js project: steps under `src/steps/`, station files under `.orchestrator/`	Start from worker-template
lib-worker	The library a worker is built on: `defineStep()`, the polling loop, workpiece helpers	finopsbricks/lib-worker
fob-orc	CLI that pulls and pushes station and line definitions to the Orchestrator	`npm install -g @finopsbricks/fob-orc`
fob-worker	CLI that runs a step locally, shows what's in each bin, and runs the worker under pm2	`npm install -g @finopsbricks/fob-worker`

fob-worker reads and writes files in your worker repo only. It never calls the Orchestrator; that's fob-orc's job.

How a run works#

The Orchestrator starts a station run, on a schedule or when you trigger it, and creates a work record.
Your worker polls the Orchestrator, receives the station's first step, and runs your handler for it.
The worker reports the step's output. The Orchestrator queues the next step, and the next poll picks it up. Each step can read the outputs of the steps before it.
When the last step finishes, the work record is complete, with any report and documents your steps attached.

On a multi-station line, stations hand work to each other as workpieces: folders that move through bins on the worker's disk. See Concepts.

What fob-worker does#

Command	What it's for
`steps list`, `steps run`	List your steps; run one with a station's config, a saved scenario or an empty config
`lines list`, `lines show`, `lines status`	Your lines and stations, and how many workpieces sit in each bin
`stations status`	One station's bins, with the workpieces in each
`workpieces list`, `show`, `watch`	Where each workpiece is, what happened to it, and a live tail
`lines empty-bins`, `stations empty-bins`	Clear bins while you develop
`procs list`, `start`, `stop`, `restart`, `logs`, `monit`	Run your worker in the background with pm2
`config show`	Which folders and environment variables fob-worker sees

The command reference lists every option.

Beta limits#

Built-in steps don't run locally. steps run runs the steps in your src/steps/. lib-worker's built-in lib-worker:move_files conveyor isn't among them, so move workpiece folders between bins yourself when testing a line locally.
Local runs have no item. steps run builds the task the Orchestrator would send, with your config and earlier step outputs, but no item.
steps run output is for reading, not parsing. Step outputs are saved as JSON in temp/.
No live Orchestrator view. lines and stations show the station files fob-orc last pulled, and the bins on this machine.
procs is macOS and Linux only, and manages workers started with pm2.
Optional lib-worker add-ons are private. The template mentions libraries for AI, Google, PDF extraction, ERPNext and email; ask FinOpsBricks for access.

Missing something? Open an issue on GitHub.