Introduction¶

pVisor provides controlled execution, file-change delivery and checkable records for agents on one machine. Use native Jobs to run and review tasks, Docker-style commands for independent Linux VMs, or OpenSandbox/E2B SDKs against a local daemon. Shared images and optional memory mechanisms reduce duplicate resources; measure the benefit for each workload and platform.

PolicyVisor (pVisor) is an agent-native sandbox framework that provides file-level oversight of access and modifications, sandbox execution lifecycle management, and image and memory resource optimizations. Together, these capabilities support secure, controlled, high-density agent execution.

Agent-Native: pVisor integrates file-level oversight, sandbox lifecycle management, and resource reuse throughout agent execution. It uses files as the unit of management to bound access and modifications, isolate candidate changes, and support review; coordinates sandbox pause, memory offload, and resume through Host-side I/O management to actively reclaim resident memory from idle sandboxes during model waits; and uses on-demand image loading, memory sharing, and compression to reduce redundant resource use during branching exploration and rollback. Together, these mechanisms support secure, controlled, high-density agent execution.

pVisor's place in an agent system¶

pVisor integrates agent-oriented management into sandbox execution: it oversees file and network interactions, coordinates sandbox lifecycles, and optimizes image and memory resources on the Host. The VM executor example below shows pVisor as a module within the sandbox execution framework.

The sandbox runtime / VMM runs the VM and its devices. pVisor coordinates the runtime through lifecycle and resource-management integration points, while Host-side OverlayCore and OverlayNet manage guest file and network I/O. These module relationships require corresponding runtime integration points; support for automatic waiting management is described in the experiment record. The Agent or upper-level system owns decisions, result acceptance, reward computation, and cross-node scheduling.

Entry points and scope¶

Native Job executors install controls through host namespaces/Seatbelt, an OCI runtime or a VM; the runtime owns lifecycle, staging and records. Two environment-oriented entry points complement Jobs: the Docker-style CLI manages per-container VMs, and the daemon provides local VM lifecycle, command and file interfaces for tested OpenSandbox/E2B protocol subsets.

Job stage/apply, checkpoints and Gateway capture have separate contracts and cannot be invoked with sandbox IDs. Choose an interface and platform using the CLI and platform matrix. External orchestrators own cross-node placement, business retries and workflows.

Use cases¶

Local agent workflows

To limit an agent's impact on your workspace and review and accept file changes after execution, start with your first run and work through execution, review, and apply.

Agent execution infrastructure

To manage multiple execution environments for inference, evaluation, or post-training and reduce resource use during model waits and branching exploration, start with the infrastructure overview to choose an integration interface and runtime configuration.

Today, and after¶

Supervision and deployment scale are independent dimensions: multiple Jobs can run concurrently and SDKs can manage several sandboxes. This alone does not establish exemption from review, batch merging or distributed scheduling.

Native Job review, independent-workspace concurrency examples and CI integration are available today; see parallel agents and CI. The daemon SDK interfaces manage sandbox lifecycles and process/file operations; they do not inherit the Job file-merge workflow.

RL rollouts can reuse recording, forking and tool-prefix replay. Training-framework integration and end-to-end throughput require separate acceptance.