Workers

A worker runs things. It picks up work from a session's log, such as a turn to answer or a tool call to run, does it, and writes the result back. The Mod app runs one on your Mac (local). You can run others on your own servers with the CLI, a pool host picks up sessions when your devices are away, and a session can run in a VM.

How it works

There are two kinds of worker. Most take work off the log: an inference worker answers a turn, and a tool worker runs the calls the agent makes. An ingress worker does the reverse and brings something from outside onto the log. The capture worker, for example, streams Claude Code transcripts into session logs.

A tool call is claimed by writing the start of its result to the log. A call that already has a result is never run again, so two workers never run the same call twice. To stop two devices racing for the same work in the first place, a run names the device that serves it, and only that device claims it. If that device stops answering for thirty seconds, another eligible device may take the run over.

Where a session runs is its placement. Placement is recorded on the session, and it is never part of an address: the session, its documents and its log keep the same ids wherever it runs. A new session is placed when its first turn is sent. By default it goes to the device you are on, or your main Mac when it is present (local), then to your other machines that hold the harness's sign-in (your servers), then to the pool when the sign-in is an API key at Mod's edge. When nothing can serve it, the run says why, for example that the session is signed in on your Mac only and your Mac is away, rather than waiting in silence.

Placement reads which devices are present and what each can run. Each device records its harnesses, its sign-ins and its projects in the World's presence, and sends a short signed beat every ten seconds that is never stored. A device is present while a beat has arrived in the last thirty seconds.

Moving a session to another machine moves its placement, not its history. The log and the documents are already on every device. The old host stops taking new runs, finishes or interrupts the current turn, sends its last snapshot of the code, then writes the new placement. The new host picks up from the log. One device serves a session at a time, and a move never runs two copies.

Changing Mod's documents and acting on your Mac are approved separately. A tool that writes to documents is held for approval when nobody is there to give it. A session in a VM reaches your Mac only through actions you approve: a recipe is approved by name and by the command it runs, so changing the command needs a new approval.

Using it as you build

You choose which machines your work runs on by which ones run Mod. To see which devices are present in your World:

mod-next world devices

To serve a project from a machine with no window, such as a server, run its workers headless. With no names it starts what you last enabled, or the inference worker:

mod-next workers <projectId>
mod-next workers <projectId> inference capture --root ~/code/app

Without --root, the workers have Mod's project tools only: sessions and documents, no filesystem. With --root, and --checkout for the repository, the machine also serves file tools from that folder. Capture needs --root to find transcripts.

You decide what a session may do on a machine by approving its writes, its recipes and its forwarded ports as it asks. See VMs for what a session in a VM can reach.

Limits

• Resuming a session on another machine after the machine serving it crashes is being designed (RFC 0370). soon
• Moving a session between your own machines works today. A session on a subscription can only move to a machine that holds that sign-in.