# 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](/docs/workers/get-started) |
| Understand lines, stations, steps and workpieces | [Concepts](/docs/workers/concepts) |
| Run and debug a step locally | [Run steps locally](/docs/workers/run-steps) |
| See what's in each station's bins | [Inspect lines and workpieces](/docs/workers/inspect) |

<Callout type="info" title="Beta">
Running a worker needs an Orchestrator account: [sign up](https://console.finopsbricks.com/signup), then create an organisation in the Orchestrator. Running steps locally with fob-worker needs no account. fob-worker is in Beta; see [Beta limits](#beta-limits).
</Callout>

<Video title="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](https://orchestrator.finopsbricks.com) |
| **Worker repo** | Your Node.js project: steps under `src/steps/`, station files under `.orchestrator/` | Start from [worker-template](https://github.com/finopsbricks/worker-template) |
| **lib-worker** | The library a worker is built on: `defineStep()`, the polling loop, workpiece helpers | [finopsbricks/lib-worker](https://github.com/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

1. The Orchestrator starts a **station** run, on a schedule or when you trigger it, and creates a **work record**.
2. Your worker polls the Orchestrator, receives the station's first **step**, and runs your handler for it.
3. 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.
4. 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](/docs/workers/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](/docs/workers/reference/steps) 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](https://github.com/finopsbricks/fob-worker/issues).