Run agents and review their changes before choosing what to keep.

pVisor runs Agent CLIs, scripts and automation with execution policies, copy-on-write workspace staging and execution records. Use your usual command, inspect the results, then accept selected file changes or discard the stage. The basic workflow requires no Agent SDK.

Jobs are the main workflow for reviewing changes before accepting them. The project aims to reduce supervision per task and let each machine support more sandboxes. VM resource sharing and idle memory reclamation are under active development, with support that varies by platform.

Install the native command from a Python wheel:

pip install pvisor-sandbox pvisor --version

Wheels are published for Linux x86_64 and Apple Silicon macOS. Staged host execution on macOS requires macFUSE 5.4.0 or newer with its FSKit extension enabled. VMs use KVM on Linux and Hypervisor.framework on Apple Silicon. On macOS, they need a Linux image or rootfs. See the installation guide for prerequisites.

You can also install the same command from the rolling nightly build without a Rust toolchain:

curl -fsSL https://raw.githubusercontent.com/DeepLink-org/pvisor/main/scripts/install-nightly.sh | bash

Stable and nightly GitHub Releases include native archives and SHA-256 checksums. Install with Homebrew from the project tap:

brew tap DeepLink-org/formula https://github.com/DeepLink-org/Formula.git brew install DeepLink-org/formula/pvisor

The stable workflow generates a Homebrew formula and can update the tap after its one-time setup.

Platform requirements and executor setup are covered in the installation guide.

Run an installed Agent CLI from your project directory:

pvisor spawn --safe -- claude pvisor review last pvisor apply last --path src

Or discard the remaining staged changes:

pvisor drop last

Replace claude with your Agent CLI or script. --safe requests the safety preset and keeps workspace changes in Job storage for review. Admission can refuse an executor that cannot satisfy the preset. last selects the latest Job in the default store; use the printed Job ID when managing several Jobs. With --stage PATH, you choose a stage explicitly and address it by its path.

Ordinary host Jobs without staging write directly to the workspace. Staging covers the configured filesystem view; HOME, rootfs and explicit mounts have separate lifetimes. See staging and storage.

pvisor spawn --executor vm --rootfs image=ubuntu:24.04 -- /bin/echo hello

The examples cover filesystem isolation, selective apply, network policy, model request capture and interactive review.

Capability What it does

Policy admission Resolves the executor and requested capabilities before dispatch, and records the available controls and observations.

Workspace staging Keeps writes in an overlay for inspection before you apply them to the target workspace.

Selective apply Applies selected paths, checks recorded preimages for conflicts, and tracks progress in a recovery ledger.

Execution records Produces a Run record and Run Bundle with results, filesystem changes, boundary observations and artifact references.

Network and model control OverlayNet applies network policy; optional Gateway support adds model protocol handling and request/response capture.

Checkpoint and fork Supports logical filesystem checkpoints and forks; execution snapshots are separate, restricted VM capabilities.

Execution is bounded, recoverable and checkable within the documented scopes. Inspect the Run Bundle's evidence and warnings to see which controls were installed; requesting a policy does not prove enforcement. Logical checkpoints do not capture process memory, and replay does not roll back an external service.

A Job can run as a host process, through the native OCI container executor, or in a Linux VM. Each executor has different isolation boundaries, controls and prerequisites.

pVisor trusts the host kernel, its supervisors, and the host account's management code and configuration. The project does not claim a hardened boundary between mutually hostile tenants sharing that account.

The following limits apply across executors:

See capabilities and evidence, staging semantics and the security documentation before relying on a boundary.

The repository also provides these entry points, each with its own contract:

The container CLI does not implement the Docker Engine API. The daemon's sandbox API does not expose native Job stage/apply or checkpoint/fork semantics. SDK support is limited to the partial profiles described above. External orchestrators handle cross-node placement, workflow scheduling and retries.

Use the container command profile, daemon contract and shim guide for supported operations and limitations.

pVisor includes a shared compressed image pool, optional RAM sharing, VM pause/offload controls and experimental guest-idle/model-wait integration. Support depends on the platform, RAM backing and execution profile. Some features require opt-in, and availability varies across frontends.

The runtime feature workload-aware-memory-offloading currently enables only vCPU wait observation. It does not automatically reclaim memory. Shared memory pools and Apple Silicon shared kernel baselines are separate opt-in mechanisms. See the runtime experiments and VM implementation for their contracts.

The project is a developer preview. Architecture reviews and targeted tests cover individual behaviors; they do not establish stable crash recovery, isolation between hostile tenants or full OCI/SDK compatibility. Assess platform integration, release-artifact validation and long-running fault tests for the revision and configuration you use. Memory sharing alone does not establish sandbox density or net memory savings. Consult the benchmarks for measured workloads and conditions.

The workspace has 13 crates, grouped by the responsibilities they own:

mise run doctor -- dev mise run build -- release # Supported executables for this host mise run test -- pvisor pvisor-cli # Runtime and frontend tests through nextest mise run test # Workspace Rust tests, then Python suites

Run checks for the affected packages when making focused changes. mise run build -- PROFILE COMPONENT supports debug, release and performance profiles and all, product, daemon, shim and shim-vm components. Builds prepare the customized guest firmware from fw/; published wheels do not require a local kernel build toolchain. See the engineering guide for dependencies, platform setup and validation.

Install mise 2026.8.5 or newer, then run mise trust, mise install --locked, and mise run setup. The checked-in mise.toml and mise.lock pin a reproducible default toolchain. CI and wheel builds use mise 2026.10.18. You can select compatible local tools in the gitignored mise.local.toml; see local tool overrides. uv.lock fixes Python development dependencies in .venv. Use mise tasks ls to list tasks and mise run test to validate. The timed peer TCP recovery test reserves all nextest execution slots while it runs; other tests keep their normal parallelism. See .config/nextest.toml. See contributing for the development loop and platform prerequisites.

Task implementations that need more than a short command live in scripts/tasks/. Their names and shared environment are declared in mise.toml. CI installs tool subsets for Python, semspec, documentation and release checks. Only full setup prepares guest targets. The optional Podman Go contracts use their pinned setup-go environment; install native libraries and virtualization prerequisites with the host package manager.

The customized libkrunfw sources, guest kernel configurations, patches and bundle tests live in fw/. CLI, daemon and single-wheel builds use this source-built firmware by default, with verified kernel downloads and build caches keyed by their inputs. Use mise run fw -- build to build the firmware independently and mise run fw -- test for bundle/ABI regression tests. The directory README covers toolchain requirements, cache settings and corresponding-source export. Published wheels install without a kernel build toolchain.

First run: the run-review-apply workflow

Why pVisor: goals, use cases and the trust ladder

CLI reference: commands and configuration

Architecture: component boundaries and execution flow

Experimental features: stages and validation gates

中文文档

Contributions: CONTRIBUTING.md. Security reports: SECURITY.md.

Apache License 2.0. See NOTICE for third-party attributions and separately licensed bundled components.