配置文件参考¶

把一次已经跑通的命令保存为 TOML，就能在本机、CI 和批量任务里复用同一套运行设置。先从下面的本地示例开始：它把输出留在 Stage，方便检查后再决定是否写回项目。

需要查命令行参数时，使用 CLI 参考；需要限制具体文件或网络目标时，使用策略字段参考。

当前可用的配置入口¶

--config 读取 TOML RunConfig；--spec 读取已解析的 JSON RunSpec，两者不是同一种文件。配置必须显式传入，不会自动读取项目里的 run.toml。工作区 policy.toml 则会自动加载，见策略字段。

下面的配置在宿主执行一个不需要网络的任务，捕获标准输出，并把改动保留在项目外：

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 策略只约束经过代理的流量；这个例子不等价于强制离线。需要普通出口不可绕过地被阻止时，加上 --overlaynet-deny-all。暂存与文件 sandbox 也相互独立。

实验性特性配置¶

在显式加载的 Run 配置中，用 [features] 下的布尔值选择特性：

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

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

features.workload-aware-memory-offloading 默认 false，启用 EXP-001 M0 原生 VM 观测。要求 Linux x86_64/KVM 或 Apple Silicon macOS/HVF 的 VM executor；自动 offload 尚未实现，HVF 运行验收尚未完成。未知特性键和非布尔值会导致加载失败。

--feature workload-aware-memory-offloading 在配置合并后启用特性，包括配置值为 false 的情况。省略则保留配置值。设置显式传递到原生 runner，并保留在存储的 Run 配置中。pvisor feature 不加载该文件，只列出注册默认值和本次 CLI 启用值。见特性命令。

Daemon 配置¶

pvisor-daemon serve 使用命令行设置，不读取这里的原生 RunConfig TOML 或已解析 RunSpec。OPEN_SANDBOX_API_KEY 使用至少 32 字节的受保护秘密。见 daemon 启动与 daemon 与缓存入口。

旧 [controller]、[[workers]]、Worker profile 和 Cluster task JSON 不是 daemon 输入。pvisor-cache 保持独立；node 运行时协议没有 daemon acquire/release 适配器。NativeRuntime 仅支持 VM；checkpoint/fork、stage/apply、全局 DAG 与分布式 lease API 未实现。

serve 使用必需的 --images-dir 与 --cgroup-root 构造 NativeRuntime。Cargo 链接 pvisor/pvisor-core，同步内部 VM 派发先于参数解析或 Tokio。隐藏 supervisor 命令已实现。Images/cgroup 路径会 canonicalize；相对 state 按启动工作目录解析，运行时状态会 canonicalize。部署使用短绝对路径，重启时保持不变。

所有运行时路径使用绝对路径，daemon 重启时保持不变。逐 sandbox 的 control.sock 必须短于 104 字节，vsock Unix socket 也有路径长度限制。/run/user/1000/pvd 是短状态路径示例，不保证跨注销／重启持久化。VM 不能跨宿主重启存活。

字段导航（当前实现）¶

类型与默认值来自 crates/pvisor/src/config.rs。标为内部解析或 serde(skip) 的字段不是配置接口。

覆盖规则与常见错误¶

• 显式 CLI 标量覆盖配置值；命令替换 run.command。
• 重复列表选项通常替换整份配置列表；--mount 替换整份挂载列表，--access 追加规则，--clear-access 才清空默认与配置规则。
• --safe 位于配置与显式 CLI 之间，并清空配置的 run.pass_env；之后显式的 --pass-env 生效。
• 未知字段被拒绝；filesystem = "sandbox" 不能写成 [filesystem] mode = "sandbox"。
• 含路径的配置没有“以配置文件目录为根”的通用承诺；从预期工作区启动，跨环境使用绝对路径。

[vm].memory_pool 是实验性 macOS / Apple Silicon 共享冷页池的 socket 路径，默认未设置；CLI 对应 --vm-memory-pool SOCKET，Rust SDK 对应 VmSettings.memory_pool。Linux 有意拒绝外部池；有界实例本地存储使用 cold_ram_compression。见首版内存共享。

常用分组的具体字段¶

Run 与资源额度¶

[run] 的 command 是字符串数组，不经 shell 自动展开。需要管道或重定向时显式使用 /bin/sh -c。executor 默认 host，stdio 默认 inherit，policy 默认 observe，timeout_ms 默认未设置。

[run.resource_limits] 接受以下可选整数；未设置表示不在配置中请求该额度。

额度能否落实取决于执行器。运行后核对 resources 中的 requested、effective、mechanisms 与 limitations；CPU 时间与任务 wall-time 超时分别设置。

文件与网络¶

[overlayfs] 的 mount 与 access 使用表数组。mount 提供 source、可选 target 与必需的 access；access 规则提供 path 与 level。等级取 deny、ask、read、warn、stage、write，使用方法见文件策略。

[overlaynet] 的 mode 取 auto、off、proxy，policy 取 public、deny、allowlist。allow 是目标字符串数组，rules、deny、limits 是结构化表数组。默认列表为空；端口、协议与地址规则见策略字段。

Container 与 VM¶

container.platform 取 linux-amd64 或 linux-arm64，是可选的原生宿主架构断言。匹配值会被接受；跨架构值会被拒绝，即使设置了预制 container.rootfs。host 和 VM 配置会拒绝已配置的平台。它不启用模拟执行，也不自动发现／下载程序。container.pvisor_binary 默认使用当前程序；显式 Linux 二进制和 rootfs 须兼容原生架构及 guest ABI。见容器准备。container.network 取 host、bridge 或 none，但 CNI 支持尚未实现，当前会拒绝 bridge。

VM 控制与内存覆盖¶

所有控制/内存字段都有 CLI 对应项，见选项表。 --vm-ram-compression、--vm-cold-ram-compression 和 --vm-ram-dedup 接受裸标志（true）或 =true / =false。省略时保留 TOML 值； 显式 =false 关闭配置的 true。只有 true 布尔选项推断 VM 执行， 显式 control/backing/pool/node 路径也在省略 --executor 时选择 VM。 依赖 TOML 内存设置时应设置 [run].executor = "vm"；仅有 [vm] 表 不会选择 executor。配置 control_socket 也会通过 CLI 选择 VM，但 不会覆盖显式非 VM executor；此组合被拒绝。

启用去重并使用固定控制路径的 live VM：

[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

将 TOML 保存为 vm-control.toml；前一个 Attempt 结束并释放 socket 后再 依次执行命令。该 Linux 示例假设有效 UID 为 1000；替换为自己的有效 UID 和规范化 /tmp（macOS 通常是 /private/tmp）。vm.control_socket 是可选的仅宿主创建路径，默认未设置。省略时，Host Job 服务直接在 /tmp/pvisor-host-<有效 UID> 下创建私有 vm-<UUID>.sock；自定义 CLI 路径也必须直接位于该规范根目录下。嵌入 API 接受的其他私有父目录不适用于 CLI worker。根目录必须不是符号链接、属于有效 UID，且权限恰为 0700； socket 权限为 0600，仅限同 UID，已有路径绝不覆盖。宿主权限被排除在 guest 访问范围之外，包括 host-rootfs VM。

CLI stderr 打印 --vm-socket、--vm-job-id 和 --vm-attempt-id，供 普通 live VM 命令 使用：status、 suspend JOB --vm-pause / --vm-offload（可选 --vm-ram-file PATH）， 以及 resume JOB --vm-load。这些子命令局部寻址／动作选项必须放在支持的命令之后； 前置于命令或用于其他命令时被拒绝。它们不是 [vm] 配置字段， 不改变持久 Job 的默认行为。ctrl 不是 live VM 控制的兼容别名。 --vm-load 继续同一个 live Attempt，不是持久快照重启，也不主动预触 全部 RAM 页；非 VM 控制明确不受支持。

--vm-node-socket SOCKET 覆盖 vm.node_socket； --vm-snapshot-filesystem-pool DIR 覆盖 vm.snapshot_filesystem_pool。 省略路径标志保留配置。快照池必须由宿主管理，位于 VM 可写根及快照 store 之外，并与 Job 位于同一卷；其 Linux x86_64 无网络 profile 不代表通用 VM 快照支持。本地冷 pager 的单一选项同时启用回收与压缩，不是独立开关。 它与 backing/FUSE 压缩、去重、外部池、快照捕获/恢复、快照文件系统池及 整 VM offload 互斥。去重与两种压缩模式及外部池互斥。Linux 外部池仍不受 支持。冲突针对合并后的配置，不只是 CLI 标志。

VM 的内存以 MiB 为单位，CPU 是正整数。ram_backing 保存 RAM 文件；ram_compression 启用相应的压缩 backing。macOS 的压缩 backing 与共享池有额外 FUSE 条件，见内存共享概念验证。

[vm].cold_ram_compression = true（VmSettings.cold_ram_compression）在使用 VM executor 时启用实验性的 Linux x86_64 实例本地 live 压缩； --vm-cold-ram-compression 还会选择该 executor。默认值为 false，采用 私有匿名 RAM，没有 live backing 文件，不需要 FUSE 或外部服务，区别于 ram_compression。必须具备 userfaultfd syscall 或 /dev/userfaultfd 的 内核缺页权限；编译支持不代表权限，缺少权限时启动失败，不回退或修改 全局 sysctl。准入拒绝 ram_backing、ram_compression、ram_dedup、 snapshot_filesystem_pool、快照捕获/恢复及整 VM offload；Linux 还拒绝 memory_pool 及 PVISOR_EXPERIMENTAL_MEMORY_POOL。ACL 命令、映射/构建 限制、有界预算及经过校验的 refault 见 实例内压缩。这是持续 进行且无需 guest 参与的驱逐/refault 探测，不是普通 pause 或读访问热度 检测器，不承诺生产密度。

[vm].ram_dedup = true 在使用 VM executor 时请求尽力而为的宿主 RAM 去重建议；--vm-ram-dedup 还会选择该 executor。它与 memory_pool、ram_compression、cold_ram_compression 及 PVISOR_EXPERIMENTAL_MEMORY_POOL 互斥。Linux 建议面向普通私有匿名 RAM 与恢复的私有 COW 映射；live MAP_SHARED RAM 被跳过，不转换映射。macOS 对其他条件合格的映射报告不支持。runner 将安装报告写入 stderr，建议失败仍继续运行；accepted_bytes 不是已合并字节、节省，也不证明扫描已启用。不修改全局 KSM 参数或增设服务。启用前先核对去重边界与共享风险。

[vm].snapshot_filesystem_pool 为首次启动及从快照恢复的 VM capture 启用不可变 lower 引用，也覆盖不同 VM 的首次 capture。首次 seal 后，控制连接持有已验证的 owner；后续 capture 验证完整原 lower 并复用已封存的 pool 树，不扩大 runner 的访问范围。原生调用方应使用宿主管理的绝对路径，与 Job store 位于同一卷，并处于所有 VM 可写根和快照 store 之外。首次缓存未命中时，每个不可变摘要创建一棵 pool 树；并发未命中按摘要串行，命中不产生临时 lower 副本。此选项启用的原生 v5 快照以独立持有的 64 KiB 压缩块保留私有文件内容，复用未变化的内容；恢复时重建私有可写 inode，并保留完整元数据及硬链接关系。运行中的块 owner 在父快照退役和 GC 后仍然有效。封存先按解码后的内容标识查找 pool 块，命中时完整校验并直接复用，仅未命中才压缩；完整 RAM 压缩封存也使用这一路径。原生 capture 直接编码经过宿主认证的冻结私有目录，不产生中间私有数据树；导入、恢复和暂停任务的文件导出均不打开记录中的原始私有路径。完整数据校验仍保留；延迟和密度收益需要实测。此配置不支持网络、共享内存池、普通与 live 冷 RAM 压缩及显式 RAM backing。备份须保留 pool 与相关 Job store，或导出完整快照。

捕获与记录¶

[gateway] 默认 mode = "off"，捕获模式为 capture。默认 admin_listen = "127.0.0.1:9876"、level = "dialogue"、session_header = "x-pvisor-session-id"、debug = false、routes = []。可选 profile 当前为 zcode-bigmodel；zcode_builtin_config 指向该适配配置文件。路由与捕获级别按 Gateway 指南配置。

[record].destination 是可选路径。Gateway 的模型通信记录与 Trace Event journal 有不同数据职责，按记录概念保留所需产物。

完整配置字段表¶

每行列出一个可序列化字段、Rust 类型、TOML/SDK 原始默认值与用途。Option<T> 表示可选，TOML 中省略键即可，不写 null；Vec<T> 表示数组，结构体使用表。required 指创建数组条目时必须提供。表中的默认值在 CLI 预设与解析之前生效。

下方的 network_rule、bandwidth_limit、policy_layer、network_layer 是复用的条目结构，不是顶层 TOML 表名。网络规则放在 overlaynet.rules、overlaynet.deny 或某个作用域的 network 层中；带宽限制放在对应的 limits 数组。policies.session、policies.workspace、policies.user 均使用 policy_layer。

文档构建会对照 Rust serde 结构检查字段名与类型。默认值和 CLI 行为单独核查，字段覆盖检查不能替代行为验证。