PolicyVisor (pVisor)

Run a coding agent in a staged workspace, review its changes, and apply only the paths you keep.

运行 Agent，改动先进入暂存区，审查后再决定哪些写入工作区。

pVisor runs your existing Agent CLI, a script or an automation command. With
staging enabled the agent edits a copy-on-write view, so your working tree stays
unchanged until you apply a change. apply takes the paths you name and checks
the recorded preimage first, so it refuses a file that changed underneath it.
Every Job also writes a Run Bundle with the command, the effective policy, the
file changes, and which controls actually installed.

The basic workflow needs no Agent SDK and no model account.

Run one Job

pip install pvisor-sandbox
cd your-project

pvisor spawn --safe -- claude      # your Agent CLI, or any script
pvisor review last                 # read the staged changes
pvisor apply last --path src       # keep src/
pvisor drop last                   # discard whatever you left staged

Replace claude with your Agent CLI or script. --safe requests the safety preset
and refuses an executor that cannot provide isolation and staging. last resolves
the latest Job registered for the current workspace; add --diff to print a
unified diff beside the classified change list. With --stage PATH the Job
registers against that path, so review and apply take the path instead of last.
Use the printed Job ID when managing several Jobs.

--safe stages writes, which needs FUSE: macFUSE 5.4.0 or newer with its FSKit
extension on Apple Silicon macOS, /dev/fuse and user namespaces on Linux x86_64.
If that is not set up yet, run pvisor spawn -- claude: the Job is still
recorded, and writes go straight to your workspace. Wheels are published for
Linux x86_64 and Apple Silicon macOS; VMs use KVM on Linux and
Hypervisor.framework on macOS and need a Linux image or rootfs. See the
installation guide
for prerequisites.

Other install methods (no Rust toolchain needed):

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

# Homebrew (project tap)
brew tap DeepLink-org/formula https://github.com/DeepLink-org/Formula.git
brew install DeepLink-org/formula/pvisor

Stable and nightly GitHub Releases include native archives and SHA-256 checksums.
The stable workflow generates a Homebrew formula and can update the tap after its
one-time setup.

Job startup requires the executable and its ancestor directories to be owned by
you or root and not writable by others. If Homebrew's Cellar is group-writable,
the command stops with unsafe owner executable ancestor and names the
directory; the installation guide
covers that case, platform requirements and executor setup.

For a minimal VM Job with a Linux image:

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.

Measured results

The rows come from separate experiments with their own pinned configurations.
Values move with platform, workload and image; the pages linked from
benchmarks state the conditions
and the full tables, including results that do not favor pVisor.

Other capabilities

Execution is bounded, reversible 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.

Execution boundaries

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:

• Remote API calls, database writes and sent messages are outside apply/drop
  and remain in effect. Dropping a stage also leaves files that have already been
  applied in place.
• Apply does not provide a multi-file transaction against other writers. Stop
  concurrent editors and other apply processes while accepting a batch. Conflict
  detection and recovery records do not make arbitrary concurrent writes safe.
• Proxy records cover traffic through the proxy. Missing observations do not
  prove that an action never happened.
• Crash recovery is incomplete. Attempt completion publishes several durable
  records separately, so a host-process crash between them can require reconciliation.

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

Other ways to use pVisor

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.

VM density and current maturity

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.

Architecture and development

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

For local development:

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.

Development environment

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.

Guest firmware

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.

Documentation and community

• 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.
Questions and setups: Discussions.
Security reports: SECURITY.md.

License

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