Installation¶

Once pvisor is installed, you can run Agent CLIs, scripts, and automation inside a policy boundary and get checkable execution records. The Python package, CLI, and core Rust crate are all named pvisor; other crates use pvisor-* and environment variables use PVISOR_*.

When upgrading, update deployed PVISOR_* settings as well. Local state defaults to .pvisor and user caches to pvisor/; existing data is not migrated automatically.

1. Install the tools¶

pip install pvisor

Check the command:

pvisor --version

The wheel installs a Python version marker and native CLI scripts directly in the current Python environment's bin directory; no Python launcher is involved. If your project has other Python dependencies, use a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install pvisor

Published wheels target Linux x86_64 and macOS arm64. Check release artifacts or build from source for other architectures.

2. Check platform prerequisites¶

Wheel installation supports macOS and Linux and requires Python 3.10 or newer; the installed native CLI does not use a Python launcher. Ordinary host Jobs write directly to the workspace; only --safe or --stage uses filesystem staging. Install macFUSE before running a staged host Job on macOS:

brew install --cask macfuse

macOS uses macFUSE's FSKit backend by default. Install macFUSE 5.4.0 or newer (older FSKit versions can corrupt small writes into zeroes), then enable it in System Settings → General → Login Items & Extensions → File System Extensions. This path loads no kernel extension and needs neither Recovery mode nor reduced boot security. Mounts use /Volumes/pvisor-*; data stays in the Job stage. If FSKit is unavailable, execution fails instead of switching to the kernel backend or direct writes. libkrun VM execution does not need macFUSE.

3. Install from source when needed¶

Use the nightly wheel for the latest main build:

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

For local development, install the Python package from a checkout:

git clone https://github.com/DeepLink-org/pvisor.git
cd pvisor
pip install -e .

Or build the CLI from source:

just install-cli

To test a specific native build, invoke its path directly (for example target/debug/pvisor) or put its directory first on PATH. The old launcher's PVISOR_BIN override is not used by installed native scripts. Editable Python installation is not a native CLI build; use just build or just install-cli.

Install the single-node daemon separately¶

For an OpenSandbox-compatible lifecycle API on one Linux host, follow daemon installation and startup. pvisor-daemon is a separate executable, included only in current Linux x86_64 wheels (stable or nightly) and also available through a local source build. macOS wheels do not include it, and no artifact supplies a ready-to-use sandbox image. Its partial OpenSandbox 1.1.0 profile has VM-only NativeRuntime embedding pVisor on Linux x86_64/KVM with delegated cgroup v2; the executable is integrated with native runtime construction and synchronous internal VM dispatch before Tokio.

A working sandbox needs a trusted local manifest/rootfs and genuine execd/egress through guest CID 3 vsock bridges. Bootstrap and image recipe are not supplied or end-to-end validated; starting the API does not establish SDK conformance or density. Stage/apply and checkpoint APIs are not implemented, and node sharing is not automatically acquired. Controller/Worker and the Cluster SDK are retired; external schedulers own cross-node orchestration.

4. Enable VM or OCI execution when needed¶

The default local workflow needs neither Docker nor Podman. To run an OCI image with the VM executor:

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

Without an explicit rootfs or image, Linux VM uses host / through virtio-fs and OverlayFS without pulling an image. macOS requires a Linux rootfs or image. --image-store DIR changes the content-addressed cache, --mount SOURCE[:TARGET]:ACCESS exposes host paths, and --rootfs DIR selects a prepared rootfs. Linux uses KVM; Apple Silicon uses HVF. The guest supervisor is a static musl Rust ELF built with Rust's linker; macOS does not require a C cross compiler. See development for build prerequisites.

Treat these as separate platform steps: first complete a staged host workflow, then compare executor evidence in Run Bundles.