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: with staging enabled, 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 Sessions 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.
The experimental command subset includes image-based
pvisor compose;
it does not implement the Docker Engine API or the full Compose specification.
For the supported Unix command profile, alias docker=pvisor uses the same
Session runtime: root inspect reports metadata, kill signals the current
execution, and export writes a stopped container rootfs tar. Unknown commands
fail rather than executing a host workload. Native tasks use explicit spawn
or pvisor [SESSION_OPTIONS] -- COMMAND; options-only --config / --spec
invocations remain supported. inspect --files selects a task filesystem view.
A shell alias does not redirect SDK Docker sockets or subprocess executable lookup.
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 Session 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: approval-free stagebox operation still needs validation for cloud models and approval behavior. The agent guide lists the recorded controlled-client tests. pVisor does not automatically disable agent or IDE approvals.
--safe fails if required controls cannot be installed. Ordinary Host Sessions 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 Sessions: use
pvisor spawnwith Host, OCI, or VM execution and explicit staging for review/apply. - Agent plugins: Pi, DSH and Codex task adapters use native
spawn → review → apply/drop; built-in Agent tools remain separate. - 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 Session 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.
- pVisor 0.4.0 release notes
- 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.
