Pool

The pool is the hosts that pick up your sessions when your own devices are away. A pool host is either a daemon you run yourself with --pool, or capacity Mod runs for you. Your session keeps working while your Mac is asleep, and comes home when it wakes.

How it works

A pool host is a device like any other: it joins your World and beats in presence, but as kind pool rather than desktop. It serves only sessions placed on it as pool, and never takes a session placed on one of your own machines. In Mod's pool, each session VM runs its own daemon, and an idle VM stops billing.

Placement chooses your own devices first. A new session goes to the device you are on, or your main Mac when it is present. Then it goes to your other present machines that hold the harness's sign-in. The pool comes last, and only for a session whose sign-in is an API key at Mod's edge. A session on a Claude Code subscription is never placed in the pool. When nothing can serve a session, the run says why, rather than waiting in silence.

Handover works the same as any move. When your Mac sleeps, it places each busy session by that order. If no own host can take an edge-signed session, it goes to the pool, with its last snapshot of the code. A subscription session pauses instead, with one question on its log: switch it to an API key so it can follow, or wait for the Mac. If you message an idle session while its host is silent, the device you send from places it, and the pool takes it if nothing of yours can. When the Mac wakes, each session that left comes home once it is idle.

The pool also keeps time. The clock for your reminders runs on a present desktop first, then a pool host. When your Mac sleeps, it hands the clock over in a record on the World. When a reminder is due and the session it wakes is away, the clock host places that session on a present host by the same order, and the turn runs there. If the session's sign-in cannot leave your Mac, the reminder records why. Mod also runs a shared clock for subscribers that sees only due times, never content. The World agent runs on a desktop, so a reminder for it gets its event at once and its turn when a desktop wakes.

A pool host never acts as you. It acts as the session. When you start a session, your device mints a key for that session and grants it what the session may reach. The key is held by the host daemon the placement names, never inside the VM guest; the guest holds only the harness and its checkout. Moving a session, or handing it over at sleep, is when your device wraps the key to the new host. Each session's key opens only that session's documents, and inference uses a billing token for that session alone, so the VM never holds your Google sign-in. A broken pool host can reach only what that session could, until you revoke the session, and nothing else of yours.

Using it as you build

To make a machine of your own a pool host, start its daemon with --pool, or set MOD_DESKTOP_POOL=1:

mod-desktop --pool --host-world --supervise

Use this for a box that should only catch sessions when your other devices are away. A server you want to choose by name should run without --pool (see your servers).

To keep time on a machine of your own and do nothing else, run a clock worker. Repeat --world to keep time for several Worlds from one process:

mod-desktop clock --world <worldId>

For a session to follow you into the pool, it needs an API key at Mod's edge rather than a subscription (see models). To move a session there by hand, pick the pool in its Move menu. The menu offers it only when the session's sign-in allows it.

Limits

• Only sessions on an API key at Mod's edge can run in the pool. A Claude Code subscription stays on your own machines.
• A pool host serves only sessions placed on it as pool.
• The World agent does not run in the pool. A reminder that wakes it waits for a desktop to take its turn.