moca · sandbox service · ADR-0048
Per-Exec mode gives each Exec a fresh microVM. Files persist. Nothing else persists. Repeated CPU-heavy work pays a cold start every time. Lease mode keeps one guest warm between Execs. Level 1 kills every process at the end of each Exec. Level 2 lets process_start processes survive. Step through each flow. Press Next for one step. Press Prev to go back one step. The wire box below the stage shows the messages of the current step. The messages stay until you move on.
‹ moca docs · written page: Keep a guest between commands (lease mode)
The decision
Per-Exec stays the default. A lease keeps one guest warm between Execs. At level 1, every process dies at the end of each Exec. At level 2, only process_start processes survive. Survival is asked for. It is never a side effect.
The rules behind the flow
per-exec: a fresh guest for each Exec. No process survives. lease: the same guest until the lease ends. No process survives an Exec. lease+processes: the same guest. Only process_start processes survive.
Idle is measured from the last Exec end. The default timeout is 300 s. A keepalive never resets idle. The maximum duration marks the lease expiring. The lease then ends at the next idle, or at the grace limit. Defaults: 8 h at level 1, 4 h at level 2, grace 30 min. Keepalive loss ends the lease after 120 s.
A lease VM is a third accounting class. The charge starts at 192 MiB, then follows the measured memory.current × 1.25. An idle lease VM holds no concurrency slot. Under pressure the worker ends the lease idle longest. A lease with an Exec in flight is never reclaimed.
In a lease, an Exec runs as an unprivileged uid with no capabilities and no_new_privs. The cgroup tree is root-owned and not delegated. The agent stays root as PID 1, non-dumpable. Each tracked process gets its own uid. cgroup.kill ends every Exec process. setsid cannot escape.
The owner changes the mode through mocactl, with the user API token. The agent gets no tool for it. The control plane signs the mode and the epoch into a set-mode token, and into every sandbox token. The relay sets mode and mode_epoch from the verified claims on every frame. The worker refuses a stale epoch. An unknown epoch fails closed to per-exec.
Every end reason sends one notice on the next tool result and in sandbox_info. Every end writes an audit record. At level 2 the notice lists the stopped processes. The end reasons are idle, max_duration, grace_limit, keepalive_lost, reset, mode_change, memory_reclaim, worker_restart, teardown_failed, agent_dead, sandbox_deleted.
Why a lease at all
E15 · metal
On AWS m7i.metal-24xl at 9.5% duty, per-Exec held 80 sessions. Resident with a 300 s idle timeout held 128. The idle timeout kept all of the benefit and gave memory back.
the target
The workload that hurts is repeated cache-heavy or CPU-heavy work in one project: a dataset re-read, a heavy import, a test suite rerun. Each run starts in a cold guest. Level 1 serves on-disk caches through a warm page cache. Level 2 serves in-memory process state.
the bound
A build-vs-adopt assessment (2026-11-05) required self-operation, your own identity provider, and no vendor control plane. A hosted resident provider does not meet that bound. So the warm guest comes to the sandbox service, as an opt-in mode.