Skip to content

Sandbox lifecycle management

While an Agent waits for external responses or data, its CPU may be idle while memory holding task context remains resident. On supported paths, pVisor handles waiting I/O on the Host and combines it with guest idle information to manage pausing, memory offload and resumption as the Agent task progresses.

How the Host handles waiting I/O

In the VM path, OverlayCore and OverlayNet connect file and network interactions to the Host, while the Runtime executes vCPUs and devices. The Host can continue some backend work while the guest is paused:

Wait scenario Work the Host can continue
Model response Await the model response associated with this execution and collect bounded response data in supported configurations.
Network download Receive data on supported, authorized download paths, maintain backpressure and prepare delivery to the guest.
Lazy-image file read Fetch and verify file contents on demand through supported read-only paths, holding the result in Host buffers.

The three scenarios provide different wait signals and share the Pause, Offload and Resume operations below. Pausing requires guest idle information, coordinated device access to memory and wake conditions; a pending request alone is insufficient. Data readiness or another wake event resumes the guest to continue tool execution. See Automatic wait management: design and validation for each path's enablement conditions.

How Pause, Offload and Resume work together

Operation Effect
Pause: suspend execution Stops vCPUs; guest RAM normally remains resident.
Offload: reclaim resident memory After execution and device access are quiescent, synchronizes RAM to backing storage and requests reclamation of resident pages.
Resume: continue execution Restores execution and device access; offloaded pages may fault back in on later access.

Depending on the wait, choose between two paths:

  • Pause execution only: running → Pause → Resume.
  • Also reclaim memory: running → pause and satisfy offload conditions → Offload → Resume.

Offload is optional; the decision depends on wait duration and the cost of offloading and recovery. All three operations act on the same live VM and require the original owner/VMM and a reliable memory recovery source. See Memory offload.

Live Resume continues the original live instance. See VM execution checkpoints for the semantics of rebuilding an instance from saved state.

Further reading