Workers overview
What a worker is, what it does during a task, how it stays connected, and what happens when the control plane or the machine goes away.
A worker is a native Node.js process on a machine with your code and AI agents. It:
- connects outbound to the control plane over HTTPS and WebSocket — no inbound ports;
- serves a local UI and API on
127.0.0.1:47821, never exposed publicly by default; - runs agents only inside project folders you map on that machine;
- keeps credentials in the operating system's credential store (Windows Credential Manager, macOS Keychain, Linux Secret Service), with an encrypted file as fallback;
- runs as you, not as a system account, so agent logins, Git credentials and repositories belong to your user.
What happens when…
| Situation | Behaviour |
|---|---|
| Control plane unreachable | Running tasks continue. Events are buffered on disk and state changes are retried with the same idempotency id, then synced on reconnect. |
| The machine dies | Its leases stop being renewed. After the lease expires (5 minutes by default) the task is requeued from its last checkpoint for another worker, or marked RECOVERY_REQUIRED by policy. A worker that returns later is fenced off. |
| The worker restarts mid-task | On start it asks which tasks it still owns and continues them from the checkpoint. |
| An agent hits a limit | See Recovery. |
The first two are covered by the core's chaos tests.