Local

Your Mac is the first place your work runs. The Mod app starts a daemon that hosts workers on it, and each session that needs a machine gets its own VM there. When you close the lid, sessions that are working move to another host, and they come home when the Mac wakes.

How it works

The daemon is one process for the whole Mac. It syncs your World, claims the runs placed on this device, and drives each session's VM through a small VM service. On a Mac the VMs run under Apple's virtualisation through vfkit. The daemon never drives the hypervisor itself.

Your Mac is the default place for new work. A new session is placed when its first turn is sent: on the device you are on, or on your main Mac when it is present. A session on a Claude Code or Codex subscription can run here because the sign-in lives on your Mac, in a login volume your session VMs share. The subscription never leaves your machines.

Local is good for work you are watching. A session answers as fast as the harness does, it can reach your Mac through the tools you approve, and a document-only session needs no VM at all.

Placement reads presence. The daemon records in the World's presence what the Mac can run: its harnesses, where each is signed in, and its projects. It sends a short signed beat every ten seconds, and the Mac is present while a beat has arrived in the last thirty. Every other device reads the same presence, so your phone knows whether your Mac can take a turn.

When the Mac is about to sleep, the daemon has only seconds. It snapshots each session's code throughout the turn, so it hands over what has already synced. Each busy session is placed by its sign-in: one on an API key at Mod's edge goes to your servers or the pool, and one on a subscription goes only to another of your machines that holds that sign-in. If none does, the session pauses with one question on its log: move it to an API key, or wait for the Mac. You can answer from your phone. No turn starts on the Mac between the sleep notice and its being back online.

An idle session does not move at sleep, since there is nothing to run. If you send it a message while the Mac is silent, the device you send from places it, the same way a first turn is placed. When the Mac wakes, every session that left it comes home once it is idle, along with its uncommitted work.

The Mac also holds the clock for your reminders while it is awake. Before it sleeps it hands the clock to another present host, and asks for it back on wake.

Using it as you build

Installing the Mod app is all it takes: the app starts the daemon and keeps it running. To see what harnesses the Mac has and whether each is signed in:

mod-desktop status

To check whether the Mac is present, from any machine:

mod-next world devices

To move a session somewhere else, use the Move menu in the session's header. It offers only the hosts that can serve that session's sign-in.

You can tune how long an idle VM waits before it pauses or stops with MOD_SESSION_VM_IDLE_PAUSE_MIN and MOD_SESSION_VM_IDLE_STOP_MIN. A stopped VM frees its memory, and the next message boots it from its saved disk in a few seconds.

Limits

• Each session VM is capped at 768 MiB of memory and two virtual CPUs.
• An 8 GB Mac holds ten sessions working at once, alongside the app and your other work (RFC 0369).
• On a Mac, a paused VM keeps its memory. Only a stopped VM gives it back.
• A session on a subscription can only leave the Mac for another of your machines that holds the same sign-in.