Main and worker instances

A person can run more than one Legato. Main and worker instances let one Legato send a task to another, which works on it and sends the result back. With them, you can keep your board on your laptop and run the agents on an always-on machine, without moving the task by hand.

The two roles

Main instance: a Legato that you work from. It owns its tasks. You can have more than one, for example a workstation and a laptop.
Worker instance: a Legato that works on tasks that main instances hand to it. One worker can serve several main instances.

Each Legato has an instance ID. Legato makes it once and never changes it. Other instances know a Legato by its ID, not by its name.

Pair a main instance with a worker

You pair a main instance with a worker once, by four words, as you pair a phone. The main gets a token that can only hand tasks off, check on them and bring them back. It never gets the worker’s own web token, so a stolen main cannot drive the worker’s web UI.

On the worker, open Settings › Handoff › Main instances and choose Pair a main instance. Or run:
Terminal window
```
legato pair --main
```
It shows the worker’s address, four words and how long they last. The worker’s web server must be running.
On the main, open Settings › Handoff › Workers and choose Add a worker.
Enter the worker’s address, the four words, and this main’s name on the worker. The name starts as the main’s host name; the worker keeps it in lowercase letters, digits and dashes.
Choose Pair.

If the app or browser you use the main from already knows the worker, there is a shorter way:

From the Legato desktop or Android app: under Add a worker, From this app lists the app’s other servers. Choose the worker and agree in the app’s own dialog (“Make vm-1 a worker of workstation?”). The app opens the worker’s pairing request with the token it holds for it and hands the main the address and words, so you type neither. The page in front never sees the worker’s token.
From a browser where you added the worker as a server: From this browser lists those servers. Choose the worker and confirm; the page opens the request with the token this browser holds for it.

The server in front is never offered. If the worker cannot be reached, is too old to pair a main, or the main cannot reach it at that address, the reason shows above the form and the worker’s address is filled in, so you can pair it by hand.

Both sides then list each other. The worker lists the main under Main instances, with its instance ID, when it paired, when it last pulled and its open handoffs. The main lists the worker under Workers, with its address, its instance ID, when it last pulled and whether its sandbox is on. A worker without the sandbox refuses handoffs.

The words work once, for five minutes and five tries, like a phone’s. A phone cannot use a main’s words, and a main cannot use a phone’s.

Pairing again with the same main replaces its token. Renaming the main this way keeps it the same main: the worker knows it by its instance ID.
Another main under the same name is refused. Unpair the first one, or choose another name.
An old worker that cannot pair a main makes the main say “update the worker” before anything is sent.
Unpair under Main instances on the worker revokes the main’s token at once. It first says how many handoffs the main has open there. Their cards stay on the worker as ordinary cards, their agents still running, each with a note that the main was unpaired; the main shows them as no longer accepted. See Hand off tasks to a worker.
Remove under Workers on the main forgets a worker. It first says how many of your tasks are away there, brings back what it can and takes back the rest. See Hand off tasks to a worker.

The life of a handed-off task

 main instance                         worker instance
 ─────────────                         ───────────────
 task ── handoff ───────────────────▶  works on the task
 (away)                                      │
   ◀──────────────────────────────── return  │  with what the worker did
   or: recall ──────────────────────▶        │  take the task back early
   or: take back                             │  end it without the worker

Handoff. The main instance sends one of its tasks to a worker instance. See Hand off tasks to a worker.
Away. While the worker holds the task, the task is “away” on the main instance.
The task then comes back in one of three ways:
- Return. The worker finishes, and the task comes back with what the worker did.
- Recall. The main instance takes the task back before the worker finishes.
- Take back. The main instance ends the away task by itself, without the worker’s results. It does this when the worker cannot be reached or no longer has the task.

On the worker

When a main hands a task to a worker, the worker:

makes an ordinary card for it in a workspace named after the main, in the Doing column (or In Progress, else the first column). The card says where it came from under its title: “from workstation · K7Q2M9XA”, the main’s name and its own ID for the task;
adds the main’s notes to the card, marked as from the main;
starts an agent on the card at once, in a fresh clone of the task’s repository on the branch legato/<the main's task ID>, or on the pushed branch the task starts from, which the worker first fetches from GitHub. The agent always runs in Legato’s sandbox, with its tool’s own permission prompts off, and with a brief that tells it to work alone, record its decisions in notes, open draft pull requests only (or, to find something out, answer in notes and push nothing) and move the card to Done when it is through.

The worker refuses a handoff before it makes anything when it has no sandbox, does not know the agent tool asked for, or cannot clone the repository. If the agent then fails to start, for example because the clone failed, the handoff is marked failed with the reason. A pushed branch that GitHub does not have fails the handoff with “branch not on GitHub”. A handoff accepted just before the worker stopped starts when the worker starts again.

A worker can also review a make-a-change task’s pull requests with a second agent before the task is done. See Review passes.

On the worker, a handed-off card works like any other: you can move it, edit it, add notes and talk to its agent. But you cannot archive or delete it there: the worker says “this task belongs to workstation; return or recall it from there”, and archiving the Done column’s cards leaves it there. The task goes back to its main.

A card for a task from a ticket provider (Jira, Burnlite) shows the ticket’s text read-only, as a copy taken at handoff, then the task’s Legato details, which are the one part you can edit there; its title is read-only too. The worker never syncs it with the provider. See Hand off a task from Jira or Burnlite.

On the main, the task is away while the worker holds it: the main refuses to edit it, move it, start an agent on it or hand it off again, from the web UI, the TUI and the legato command, and says which worker has it. Notes can still be added there.

The Reeves of a main and its workers

A main’s Reeve can message each worker’s Reeve, to ask how it stands, without another pairing. On a worker, Settings › Main instances has a switch for each main, Its Reeve may message this one’s, on unless you turn it off. Each Reeve’s changes still need its own person’s approval.

Not to be confused with

A review handoff is the packet of decisions and evidence that an agent writes for a review. See Review handoff.
A delegation is a request from Argus that a Legato fix or find out something about a case.
A remote ticket is a task from a ticket provider such as Jira, not a task on a worker instance.

The glossary has these terms and the words to avoid.