Configuration files¶

Save a working command as TOML to reuse its settings locally, in CI, and in batch jobs. Start with the local example below: it keeps output in a Stage so you can inspect it before writing changes back to the project.

Use the CLI reference for command-line options and the policy reference for file and network rules.

Configuration entry points available today¶

--config reads TOML RunConfig; --spec reads resolved JSON RunSpec. They are different formats. Run files are explicit inputs; a project run.toml is not auto-loaded. Workspace policy.toml is automatic; see policy fields.

This host task writes a staged result outside the project and captures stdio:

filesystem = "sandbox"

[run]
executor = "host"
command = ["/bin/sh", "-c", "printf 'ready\n' > result.txt"]
timeout_ms = 30000
stdio = "capture"

[overlayfs]
stage = "../stage-config-001"
max_size = 67108864

[overlaynet]
mode = "proxy"
policy = "deny"

pvisor run --config run.toml
pvisor status --review ../stage-config-001
pvisor inspect ../stage-config-001 -- cat result.txt

Proxy deny applies to traffic reaching the proxy; this example does not establish mandatory offline execution. Add --overlaynet-deny-all to block ordinary egress through a mandatory boundary. Staging and filesystem sandboxing are independent.

Experimental feature settings¶

Use boolean values under [features] in an explicitly loaded Run configuration:

[run]
executor = "vm"
command = ["/bin/sleep", "10"]

[features]
workload-aware-memory-offloading = true

features.workload-aware-memory-offloading defaults to false and enables EXP-001 M0 native VM observation. It requires a VM executor on Linux x86_64/KVM or Apple Silicon macOS/HVF; automatic offload is not implemented and HVF runtime validation remains outstanding. Unknown feature keys and non-boolean values reject loading.

--feature workload-aware-memory-offloading enables the feature after configuration merging, including when the configured value is false. Omission preserves the configured value. Feature settings are passed explicitly to the native runner and retained with the saved Run configuration. pvisor feature lists registry defaults and current CLI enables without loading this file. See feature commands.

Daemon configuration¶

pvisor-daemon serve accepts command-line settings, not this native RunConfig TOML or resolved RunSpec. Set OPEN_SANDBOX_API_KEY to a protected secret of at least 32 bytes. See daemon startup and daemon and cache entry points.

Old [controller], [[workers]], Worker profiles and Cluster task JSON are not daemon inputs. pvisor-cache remains independent; node runtime protocols have no daemon acquire/release adapter. NativeRuntime is VM-only; checkpoint/fork, stage/apply, global DAG and distributed lease APIs are absent.

serve constructs NativeRuntime with the required --images-dir and --cgroup-root options. Cargo links pvisor/pvisor-core, and synchronous internal VM dispatch runs before argument parsing or Tokio. The hidden supervisor command is implemented. Images/cgroup paths are canonicalized; relative state resolves against the startup working directory and runtime state is canonicalized. Use short absolute paths in deployments and keep them unchanged on restart.

Keep all runtime paths absolute and unchanged on daemon restart. Per-sandbox control.sock must be shorter than 104 bytes; vsock Unix sockets also have path limits. /run/user/1000/pvd is a short state example, not a promise of persistence across logout/reboot. VMs cannot survive host reboot.

Field navigation (current implementation)¶

Definitions come from crates/pvisor/src/config.rs. Internally resolved and serde(skip) fields are not configuration interfaces.

Overrides and common mistakes¶

• Explicit CLI scalars replace config values; the command replaces run.command.
• Repeated list options generally replace the configured list. --mount replaces the entire mount list; --access appends; --clear-access clears preset/config rules.
• --safe presets sit between config and explicit CLI and clear configured pass_env; explicit --pass-env then applies.
• Unknown fields reject loading. Use filesystem = "sandbox", not [filesystem] mode = "sandbox".
• There is no general config-directory-relative path guarantee. Start from the intended workspace and use absolute paths across environments.

[vm].memory_pool is the socket path of the experimental macOS / Apple Silicon shared cold-page pool, unset by default. CLI uses --vm-memory-pool SOCKET; Rust SDK uses VmSettings.memory_pool. Linux deliberately rejects external pools; use cold_ram_compression for bounded instance-local storage. See first-version memory sharing.

Fields in commonly used groups¶

Run and resource limits¶

[run].command is a string array without automatic shell expansion. For pipes or redirection, explicitly use /bin/sh -c. Defaults are executor = "host", stdio = "inherit", policy = "observe", and no timeout_ms.

[run.resource_limits] accepts the following optional integers. Omitting a field requests no limit for that dimension in the configuration.

Enforcement depends on the executor. Check requested, effective, mechanisms, and limitations under resources after execution. CPU time and wall-time timeout are separate settings.

Files and networking¶

[overlayfs].mount and access are arrays of tables. Mount entries have source, optional target, and required access; access rules have path and level. Levels are deny, ask, read, warn, stage, and write. See File policies for usage.

[overlaynet].mode accepts auto, off, or proxy; policy accepts public, deny, or allowlist. allow is an array of destination strings; rules, deny, and limits are structured table arrays. Lists default to empty. See Policy fields for port, transport, and address rules.

Container and VM¶

container.platform accepts linux-amd64 or linux-arm64 as an optional native host architecture assertion. Matching values are accepted; cross-architecture values are rejected even with a prepared container.rootfs. Host and VM configurations reject a configured platform. It does not enable emulation or executable auto-discovery/download. container.pvisor_binary defaults to the running executable; an explicit Linux binary and rootfs must be compatible with the native architecture and guest ABI. See container setup. container.network accepts host, bridge, or none, but bridge is currently rejected without implemented CNI support.

VM control and memory overrides¶

All control/memory fields have CLI equivalents; see the option table. --vm-ram-compression, --vm-cold-ram-compression and --vm-ram-dedup accept bare flags (true) or =true / =false. Omitted flags preserve TOML values; explicit =false disables a configured true. Only true boolean options infer VM execution, while explicit control/backing/pool/node paths also select VM when --executor is omitted. Set [run].executor = "vm" when relying on TOML memory settings; a [vm] table alone is not an executor selection. A configured control_socket also selects VM through the CLI, but never overrides an explicit non-VM executor, which is rejected for this setting.

For a live VM with dedup enabled and a fixed control path:

[run]
executor = "vm"
command = ["/bin/sleep", "600"]

[vm]
control_socket = "/tmp/pvisor-host-1000/ctrl.sock"
ram_compression = false
cold_ram_compression = false
ram_dedup = true

install -d -m 0700 /tmp/pvisor-host-1000
pvisor run --config vm-control.toml
pvisor run --config vm-control.toml --vm-ram-dedup=false

Save the TOML as vm-control.toml; run the commands sequentially, after the previous Attempt has ended and released its socket. This Linux example assumes effective UID 1000; substitute your effective UID and canonical /tmp (usually /private/tmp on macOS). vm.control_socket is an optional host-only creation path, unset by default. The Host Job service creates a private vm-<UUID>.sock directly under /tmp/pvisor-host-<effective-UID> when omitted; a custom CLI path must also be directly under that canonical root. Arbitrary private parents accepted by the embedded API are not accepted by the CLI worker. The root must be non-symlink, owned by the effective UID and exactly 0700; the socket is 0600, same-UID only, and existing paths are never overwritten. Host authority is excluded from guest access, including host-rootfs VMs.

CLI stderr prints --vm-socket, --vm-job-id and --vm-attempt-id for normal live VM commands: status, suspend JOB --vm-pause / --vm-offload (optional --vm-ram-file PATH), and resume JOB --vm-load. These command-local addressing/action options must follow the supported command; they are rejected before the command or on other commands. They are not [vm] configuration fields and do not change persisted-Job defaults. ctrl is not a compatibility alias for live VM control. --vm-load continues the same live Attempt, not a persistent snapshot restart or eager RAM prefaulting; non-VM controls are explicitly unsupported.

--vm-node-socket SOCKET overrides vm.node_socket; --vm-snapshot-filesystem-pool DIR overrides vm.snapshot_filesystem_pool. Omitted path flags preserve config. The snapshot pool must be host-owned, outside VM-writable roots and snapshot stores, and on the Job's volume; its Linux x86_64 no-network profile is not general VM snapshot support. The local cold pager's single option enables both reclaim and compression, not independent toggles. It conflicts with backing/FUSE compression, dedup, external pools, snapshot capture/restore, snapshot filesystem pools and whole-VM offload. Dedup conflicts with both compression modes and external pools. Linux external pools remain unsupported. Conflicts apply to the merged config, not just CLI flags.

VM memory is measured in MiB and CPU count is a positive integer. ram_backing retains a RAM file; ram_compression enables the corresponding compressed backing. Compressed backing and shared pools on macOS have additional FUSE requirements; see Memory-sharing proof of concept.

[vm].cold_ram_compression = true (VmSettings.cold_ram_compression) enables experimental Linux x86_64 instance-local live compression when using the VM executor; --vm-cold-ram-compression also selects that executor. It defaults to false and uses private anonymous RAM, without a live backing file, FUSE or an external service. It is distinct from ram_compression. Kernel-fault userfaultfd syscall or /dev/userfaultfd authority is required; compiled support is not permission and missing authority fails startup without fallback or global sysctl changes. Admission rejects ram_backing, ram_compression, ram_dedup, snapshot_filesystem_pool, snapshot capture/restore and whole-VM offload; Linux also rejects memory_pool and PVISOR_EXPERIMENTAL_MEMORY_POOL. See local compression for ACL commands, mapping/build restrictions, bounded budgets and validated refaults. This is ongoing guest-independent eviction/refault probing, not ordinary pause or a read-access heat detector, and does not promise production density.

[vm].ram_dedup = true requests best-effort host RAM dedup advice when using the VM executor; --vm-ram-dedup also selects that executor. It conflicts with memory_pool, ram_compression, cold_ram_compression and PVISOR_EXPERIMENTAL_MEMORY_POOL. Linux advice targets ordinary private anonymous RAM and restored private COW mappings; live MAP_SHARED RAM is skipped without conversion. macOS reports unsupported for otherwise eligible mappings. The runner reports installation to stderr and continues on advice failure; accepted_bytes is not merged bytes, savings or proof that scanning is enabled. No global KSM settings or services change. Review deduplication boundaries and sharing risks before opting in.

[vm].snapshot_filesystem_pool opts into immutable lower references during native capture of initial and restored VMs, including the first capture of different VMs. After the first seal, the live control connection retains verified owners; subsequent captures authenticate complete original lowers and reuse their sealed pool trees without broader runner access. Native callers should use an absolute host-owned path on the same volume as Job stores, outside all VM-writable roots and snapshot stores. The first miss creates one pool copy per immutable id; concurrent misses serialize per id and hits create no temporary lower copies. Opt-in native v5 snapshots retain private file contents as independently owned 64 KiB compressed frames, reusing unchanged content; restores rebuild private writable inodes with complete metadata and hard-link topology. Live frame owners survive parent retirement/GC. Sealing checks decoded-content identities before compression, fully verifies pool hits and encodes only misses; this also applies to full compressed RAM sealing. Native capture encodes authenticated frozen private roots directly, without an intermediate private-tree copy; import, restore and suspended artifact export never open their recorded original paths. Complete data validation remains; latency/density benefits require measurement. This profile excludes networking, shared memory pools, ordinary and live cold RAM compression, and explicit RAM backing. Retain the pool with its Job stores or export complete snapshots.

Capture and recording¶

[gateway] defaults to mode = "off"; capture uses capture. Other defaults are admin_listen = "127.0.0.1:9876", level = "dialogue", session_header = "x-pvisor-session-id", debug = false, routes = []. The optional profile currently accepts zcode-bigmodel; zcode_builtin_config points to that integration's configuration. Configure routes and capture levels using the Gateway guide.

[record].destination is an optional path. Gateway model-traffic records and Trace Event journals have different responsibilities; retain the artifacts you need as described in Jobs and storage.

Complete configuration field reference¶

Each row names a serialized field, its Rust type, its raw TOML/SDK default, and its purpose. Option<T> means optional; TOML omits the key instead of writing null. Vec<T> means an array; structs use tables. required applies when creating an array entry. Defaults shown here precede CLI presets and resolution.

network_rule, bandwidth_limit, policy_layer, and network_layer below are reusable entry shapes, not literal top-level TOML tables. Use network rules inside overlaynet.rules, overlaynet.deny, or a scoped network layer; limits inside their limits arrays. Each of policies.session, policies.workspace, and policies.user uses policy_layer.

Field names and types are checked against the Rust serde structures during the documentation build. Defaults and CLI behavior are reviewed separately; the coverage check does not replace that review.