pVisor is a sandbox framework with two modes. Docker style sandbox runs each container in its own VM. Agent style stagebox is pVisor's original mode for coding agents: file changes stay staged until you review them and choose what to keep.
| Mode | Workflow | Boundary and results |
|---|---|---|
| Docker style sandbox | Use familiar image, run, exec, stop, and remove commands | One Linux VM per container; container lifecycle and file operations |
| Agent style stagebox | Let an agent experiment, review staged changes, and choose what to keep | Native Jobs with explicit staging and review/apply/drop; isolation depends on the selected executor |
Coding without sandbox approvals.
In Agent style stagebox mode, let the agent try changes in a staged workspace, then review the files and accept what you need. Approval-free operation still requires validation for each agent and configuration; the setup guide states the current evidence and limits.
With Python 3.10+:
python3 -m venv ~/.venvs/pvisor
source ~/.venvs/pvisor/bin/activate
python -m pip install pvisor-sandbox
pvisor --versionInstallation covers Homebrew, native packages, and the platform checks for each mode.
Prepare KVM on Linux x86_64 or Hypervisor.framework on Apple Silicon macOS, then run:
pvisor run --rm alpine:3.20 echo helloExpect hello. The command runs in a separate Linux VM and removes its container
after exit. First use downloads the image. Follow the
Docker walkthrough
to keep a sandbox running, execute another command, inspect it, and clean up.
This experimental command subset supports neither Docker Engine API nor Compose.
For the Host stagebox example, prepare FUSE and user namespaces on Linux x86_64, or macFUSE 5.4.0+ with FSKit on Apple Silicon macOS. Run these commands in a new demo directory:
mkdir pvisor-demo
cd pvisor-demo
pvisor spawn --safe --overlaynet-deny-all -- sh -c '
echo "Hello from pVisor" > hello.txt
echo "Temporary notes" > scratch.txt
'
pvisor review last --diff
pvisor apply last --path hello.txt
pvisor drop last
cat hello.txtExpect Hello from pVisor. The greeting is now in your project; the notes were discarded.
last selects the latest Job in this workspace. The
stagebox walkthrough
checks the original directory, staged view, and final file state at each step.
No model account or VM image is needed for this Host example.
The Claude Code tutorial walks through fixing failing tests in a small Python project. It includes the task prompt and credential setup, then shows how to check staged files, accept them, and retest in your project. You need Python, Claude Code, and model access.
Developer preview: "Coding without sandbox approvals" describes the intended Agent style stagebox experience. The agent guide lists the controlled-client tests already recorded and the cloud-model and approval behavior still awaiting validation. pVisor does not automatically disable agent or IDE approvals.
--safe fails if required controls cannot be installed. Ordinary Host Jobs write
through by default. File acceptance does not undo remote API calls, database
writes, charges, or previously applied files. See
security boundaries.
For system-tool experiments, pvisor stage runs host-installed tools in a Linux
VM and keeps rootfs changes for review. Apply defaults to the recorded project;
environment changes remain staged. Host files stay readable, and the live host
filesystem is not a snapshot. System writeback is a separate privileged operation,
not an OS upgrade transaction.
pvisor stage -it --stage ../pvisor-experiment
# Use the shell, then exit before reviewing.
pvisor review ../pvisor-experiment --diff
pvisor apply ../pvisor-experiment --path src --dry-run --diff
pvisor apply ../pvisor-experiment --path src
pvisor drop ../pvisor-experimentOnly discard remaining candidates after checking them. If all changes were accepted, skip drop. See stage setup and limits.
Container commands also support staged project binds on Linux:
mkdir project
pvisor run --name edit -v ./project:/workspace:stage alpine:3.20 \
sh -c 'echo "Hello from a VM" > /workspace/hello.txt'
pvisor review edit --diff
pvisor apply edit --path hello.txt --dry-run --diff
pvisor apply edit --path hello.txt
pvisor rm edit:stage is a pVisor extension; ordinary :ro and :rw mounts keep their existing
behavior. Only staged binds write results back to recorded host sources, not the
instance rootfs. Review after exit; multiple staged binds require --mount.
Staged binds cannot use --rm or mix with direct-writable mounts. Use drop for
remaining candidates when needed before removing the instance. See
mount selection and lifecycle.
pVisor also supplies execution environments for agentic inference, evaluation, and RL post-training. Resource sharing and idle-memory reclamation help manage machine capacity; execution records and staged changes help you review results. Capabilities depend on the interface, executor, and platform.
- Native Jobs: use
pvisor spawnwith Host, OCI, or VM execution and explicit staging for review/apply. - Embedded runtime: integrate the Rust runtime.
- Platform APIs: use the local daemon for partial OpenSandbox/E2B SDK profiles on Linux/KVM, or the containerd shim.
- Container workflows: the experimental Docker-style CLI runs one VM per container.
These interfaces have separate lifecycle and capability contracts. Daemon APIs do not expose native Job stage/apply semantics. Container staged binds have their own review/apply/drop contract. Start with the VM tool-execution tutorial for a caller-script example, or consult the integration matrix.
- Installation: prepare and verify your environment
- First run: try either mode from launch to cleanup
- Agent guides: command setup, credentials, and network access
- CLI reference: commands and configuration
- Benchmarks: measured workloads and conditions
- Architecture: execution mechanisms and ownership
See CONTRIBUTING.md to set up the toolchain and run targeted checks. Ask questions in Discussions and report vulnerabilities through SECURITY.md.
Apache-2.0. See NOTICE for bundled third-party components.