[quickbeard]

What

A macOS sandbox used to get a flat 4 GiB regardless of the machine or of what else was running. Sandboxes now share one budget — half the host's RAM. A sandbox that names no Memory of its own gets an even share of that budget or whatever is genuinely left of it, whichever is smaller, capped at 8 GiB each and floored at 2 GiB.

export function sandboxDefaultMemoryMiB(opts?: { sandboxes?: number; committedMiB?: number; totalBytes?: number }) {
  const budgetGiB = Math.floor((opts?.totalBytes ?? totalmem()) / 2 / 1024 ** 3)
  const shareGiB = Math.floor(budgetGiB / Math.max(opts?.sandboxes ?? 1, 1))
  const freeGiB = Math.floor((budgetGiB * 1024 - (opts?.committedMiB ?? 0)) / 1024)
  return Math.min(
    Math.max(Math.min(shareGiB, freeGiB) * 1024, SANDBOX_DEFAULT_MEMORY_FLOOR_MIB),
    SANDBOX_DEFAULT_MEMORY_CAP_MIB,
  )
}

Both measures are needed. An even share alone ignores that a sandbox which started alone took the whole budget and cannot give it back — on a 16 GiB Mac that put 12 GiB of VM on the machine. What-is-left alone would floor the second sandbox even when the first holds very little.

On a 16 GiB Mac:

Situation	New sandbox gets
Nothing else running	8 GiB
Two starting together (app launch)	4 GiB each
Added beside one holding 8 GiB	2 GiB (floor — the budget is spent)
Added beside one holding 2 GiB	4 GiB (even share binds, 6 GiB free)

The budget is the rule Windows applies to the WSL utility VM. The sharing is what makes it safe to borrow: WSL's ceiling covers every distro at once, while each sandbox here is its own VM holding its own reservation for as long as it runs.

Counted from what was reserved, not what was offered

RunningSandbox gains an optional memoryMiB that the vz backend fills in with the figure the VM was really built with — whichever of its four sources won, including a hand-typed limit the controller never chose. Bubblewrap and WSL leave it absent: neither reserves anything the sandbox owns (bubblewrap shares host memory like any process; WSL's limits belong to a utility VM the sandbox does not own), so their sandboxes correctly count for nothing.

Resolved at start, and only for the newcomer

A VM's memory is fixed at boot, so a second sandbox makes room by taking less itself, never by shrinking the one already up. The decision therefore belongs at start time — what else is running changes between create and start — and to the controller, the only thing that knows what is up:

• startSandboxInternal resolves the share after marking the sandbox starting, so it counts itself, and passes it to provider.start() as defaultMemoryMiB. A per-sandbox limit or a provider-wide default still outranks it.
• defaultResources() answers the Add dialog with activeSandboxes() + 1 and the same committed total, so the dialog quotes exactly what the start path will hand out.
• initialize() marks every sandbox it is about to start as starting before starting any of them. Otherwise a boot with two sandboxes handed the whole budget to whichever came first in the persisted file. Sandboxes still starting are absent from the running map and count nothing as committed, which is what lets a boot divide the budget evenly between them.
• The renderer refetches the defaults on any change in the sandboxes' runtime kinds, not on a change in how many are active — a sandbox reaching ready is when its memory is really taken, and that leaves the active count unchanged. Download-progress ticks carry no such change and are ignored.

Stopping or deleting a sandbox hands its reservation straight back to the next start.

Two deliberate choices

• CPUs are not shared out the same way. They are time-sliced, so four each oversubscribes nothing; memory is reserved, which is the whole reason this exists.
• The 2 GiB floor beats the budget. A second sandbox beside one that started alone gets the floor rather than nothing, because a guest too small to run the office toolchain is the worse outcome — and the user can still type a value. It sits above the validator's 1 GiB floor, which is what a deliberately-typed value may go down to.

The dialog can no longer mirror the default

It quotes the defaults in its field placeholders, and app/ must not import the node-flavoured @codev/sandbox, so it kept its own SANDBOX_DEFAULT_MEMORY_GIB = 4. A copy of a number that depends on the machine and on what is running on it is a guess, so it now reads them over a new sandbox-defaults IPC channel. The SANDBOX_*_RANGE mirrors stay: those are genuinely fixed.

Verification

• packages/codev-sandbox — 156 pass / 2 skip / 0 fail. The rule is pinned against fixed host sizes (the split across 1–8 sandboxes; the cap still applying to a share on a large machine; the floor beating the budget; a committed total that exceeds the budget, an over-sized hand-typed sandbox, and a zero count all producing sane answers). The wiring is pinned in the controller against whatever the test machine has: sandboxes booting together get the same share rather than first-come-takes-all, a third joining two gets a third, defaultResources() agrees with what the start path hands out, a stopped sandbox holds no share until started, and a sandbox's reservation is freed by both delete and stop. vz covers the controller's share being used when a sandbox names none and losing when it does.
• packages/app 25 pass, packages/desktop 108 pass. All three packages typecheck clean; prettier clean.

Not exercised: an actual VM boot at a shared size. The value only reaches VZVirtualMachineConfiguration, which the Swift helper already clamps to Apple's allowed min/max.

Docs

• CHANGELOG.md — Unreleased ▸ Sandbox, including why a second sandbox gets 2 GB and that a relaunch re-splits evenly.
• DIVERGENCES.md — the renderer-slice row now says the ranges come from the mirrored constants and the defaults from the sandbox-defaults channel.
• packages/codev-sandbox/README.md — the rule on provider.ts; on controller.ts, why the boot marks everything starting up front and why the total comes from the backends.

🤖 Generated with Claude Code