Allox OS 是一个用户或信任域专属的 Agent runtime。当前后端使用 Kata；本仓库构建 Guest Kernel、Rootfs 和可信服务，并在该运行时内管理多个 Agent 和 Session。 Kata runtime 可替换，Agent/Session 语义由 Allox OS 定义。
当前 Kata backend 提供 Guest Kernel 级的宿主机隔离；Allox OS 提供运行时内的 进程归属、workspace 隔离、checkpoint、rollback 与观测能力。两层共同组成 Agent 的可信执行环境。
Allox OS 的运行时边界包含 Guest Kernel、Rootfs、可信服务和 workspace 数据层。
Host
└── Allox OS # 用户/信任域级强隔离边界
├── Kata runtime # 当前可替换的 VM runtime 实现
├── Guest Kernel + Rootfs # 本仓库构建的运行时
├── workspace daemon / init # 可信控制服务
├── cgroup / namespace / audit
└── Btrfs workspace store
└── agents/
└── <agent_id>/
└── workspace/ # 一级 Agent Workspace
├── shared/ # Agent 共享文件
└── sessions/
└── <session_id>/ # 二级 Session Workspace
├── current/ # 当前可写执行状态
└── checkpoints/ # 只读 COW snapshots
核心层次：
| 层次 | 生命周期 | 负责内容 |
|---|---|---|
| Allox OS | 用户或信任域级 | Guest Kernel、VM 内进程、网络、系统 /tmp、设备与根文件系统 |
| Agent Workspace（一级） | Agent 生命周期 | Agent 共享文件、身份配置及其 Session Workspace 集合 |
| Session Workspace（二级） | Session 生命周期 | current、checkpoint DAG、执行租约和受追踪运行记录 |
| Turn | 单次 Agent 交互 | 可选的 turn-end 自动 checkpoint |
详细设计见 架构总览 和 Workspace 模型。
- 只回退指定
agent_id + session_id的 Btrfs workspace。 - 可选在回退前通过 Session cgroup 终止其全部已追踪进程及后代；默认关闭。
- 保留其他 Agent、其他 Session 和 Allox OS 运行时本身。
- checkpoint 索引、审计事件与事务日志保存在 rollback 范围外。
- 当前 Kata backend 管理 CPU、RAM、Guest Kernel、设备和根文件系统。
- VM 级
/tmp、系统服务和 VM 内进程由 VM 生命周期管理。 - VM 级快照/恢复由 Allox OS 的宿主机 backend 负责；它与 Session Workspace rollback 是两种独立操作。
在 tracked 执行路径中，Session 的 HOME 指向 current/，Bubblewrap 提供私有
/tmp，并在正常退出时把其中的普通文件同步到 current/.allox-tmp/。Unix socket、
FIFO 和设备节点不进入 checkpoint。迁移期 legacy/managed 路径只把 TMPDIR 指向
.allox-tmp/；该路径显式写入的系统 /tmp 仍属于 VM 级状态。
Session 通过 ALLOX_AGENT_WORKSPACE 定位一级 workspace，通过
ALLOX_AGENT_SHARED 访问其中的 shared/；HOME 和工作目录指向当前二级
Session Workspace。
当前 tracked 执行路径中，allox-workspace-daemon 为每个
agent_id/session_id 建立独立 cgroup，
并通过 Bubblewrap 为每次执行建立 PID/mount namespace、最小文件视图和私有 /tmp；
Agent 启动前会丢弃全部 Linux capabilities。Session 的所有子进程继承该 cgroup
归属；受信控制面可据此追溯进程来源，并在 rollback 前以 cgroup 为单位终止它们。
user namespace 与对象级出站策略仍是后续工作。
Session Workspace 绑定到进程的工作目录和 HOME；私有 /tmp 只属于本次
Bubblewrap 执行。普通临时文件可同步回 Session Workspace，Unix socket 等内核
运行态则在执行结束或进程树被终止时消失；回退不依赖全局 /tmp 的软链接状态。
Core 提供默认关闭的 process-tracker API 与 Session cgroup 边界。
allox-process-tree 独立发行包提供 ebpf provider，通过原生 collector 在内核 sched
tracepoint 上传播 Agent/Session run 归属并记录 fork、exec、exit。未安装该插件时，
Core wheel 中不包含 eBPF adapter、bootstrap、内核配置或 collector 源码。
这是显式启用的 OS 服务接口。启用参数、Bubblewrap 边界、构建方法、API 和限制见 进程追踪说明。
安装 allox-session-share 并启用 --share-tools 后，Bubblewrap 内可调用
python3 /run/allox/share.py。双方 Session 分别执行 enable，即可通过
read agent-b/session-1 report.txt 等命令转发访问，不需要共享密钥。
默认关闭、默认只读；开启后允许所有其他已开启 share 的 Session 访问自己的共享范围。
可用 enable --scope output --permission write 设置范围和权限，disable 立即停止
接受新请求。目标回退与文件访问互斥，写入要求目标没有活跃执行。
完整步骤和限制见 Session 文件共享。
安装 allox-session-network 并启用 --session-network isolated 或 proxy 后，
每个 Session 持有一个跨
process.start 复用的 network namespace。isolated 只有私有 loopback；proxy
额外暴露固定的 http://127.0.0.1:3128，通过 Bubblewrap 外的 AF_UNIX broker
访问网络。同时可用 python3 /run/allox/network.py connect <host> <port>
进行通用 TCP 字节转发，包括作为 SSH/Git over SSH 的 ProxyCommand。沙箱
没有 veth 或默认路由，不能绕过 broker 直连；策略、socket 与
出站审计均位于 Session Workspace 之外。默认仍为 disabled，关闭时不改变原执行路径。
设计、RPC、capability 要求和当前限制见
Session 网络隔离。
安装 allox-system-effects 并显式配置 Observer 后，每次受管理执行会在 Agent 真正开始前
建立一个冻结的 Session cgroup 边界，启动独立的 privileged deployment-observe，完成 S0
采集后才放行 Agent。v2 在整个进程树退出且 cgroup 已空、冻结后采集 B；v3 也先证明
整个进程树已退出并把同一空 cgroup 冻结，再依次采集 B、执行 rollback、采集 C。两种模式
都会关闭证据集并强制运行对应的独立 verifier；任何启动、运行中或收尾故障都会 fence
Session，不会把未验证证据标成成功。
Observer 记录 syscall/对象/进程历史；可选 scope 文件开启文件系统、BPF Program/Map/Link、 sysctl、mount、网络配置、内核模块和残留进程的 S0/S1 确认。它和单独的 eBPF process-tree provider 二选一，以免重复加载生命周期 hook。安装、内核要求、启动命令与证据目录见 中文教程 （English）。
未指定 recovery 时，集成保持 Observer protocol v2 的 A→B 直接执行观测。显式在
process.start.params.recovery 中请求恢复时，插件改用 protocol v3：采集 A，运行 Agent
并采集 B，由固定且 hash-pinned 的 allox-system-effects-recover 恢复 Session Workspace，
再采集 C 并由独立 recovery verifier 校验 A→B、B→C 和 A→C。当前 DIRECT 适配仍不代表
Docker/Kata 已接入；证据为 INCOMPLETE/INCONCLUSIVE 时不会被提升为完整或一致。
{
"action": "process.start",
"params": {
"agent_id": "agent-a",
"session_id": "session-1",
"argv": ["/bin/sh", "-c", "printf changed > effect.txt"],
"recovery": {"scrub_runtime": true, "require_consistent": true}
}
}省略 checkpoint_id 时，Allox 会在放行 Agent 前自动创建并 pin baseline；显式值必须是
完整且存在的 checkpoint ID。require_consistent 默认 true，所以 verifier 通过但 A→C
不一致或无法确认时仍会 fence Session。这里的 Allox rollback 只恢复 Session Workspace，
不恢复 Agent shared、BPF、sysctl、mount、网络配置或内核模块；这些域的残留会进入 verdict，
不会被掩盖。完整 flags、证据清单与安全边界见上述插件教程。
四个功能分别发布为独立 Python wheel：
pip install allox-process-tree # 可省略
pip install allox-session-share # 可省略
pip install allox-session-network # 可省略
pip install allox-system-effects # 可省略wheel 负责分发代码和 entry point 元数据。Core 仅加载显式启用的插件，校验 Plugin API v1，并合并命令前缀、环境变量、Bubblewrap 挂载、RPC 路由和运行元数据。资源按 加载顺序的逆序释放。安装和启用相互独立，详见 可选插件。
本仓库的 Python 发行包是 allox-os，内容限定为 Guest 侧 workspace/runtime 服务。
当前 Guest 内的控制入口是 allox-workspace-daemon，通过 /v1/rpc 提供
Agent/Session、checkpoint、rollback 和进程追踪接口。
allox-workspace-daemon \
--root /var/lib/allox/workspaces \
--listen 127.0.0.1:8092以下请求直接使用当前 RPC 协议：
curl -sS http://127.0.0.1:8092/v1/rpc \
-H 'Content-Type: application/json' \
-d '{"action":"agent.create","params":{"agent_id":"agent-a"}}'
curl -sS http://127.0.0.1:8092/v1/rpc \
-H 'Content-Type: application/json' \
-d '{"action":"session.create","params":{"agent_id":"agent-a","session_id":"session-1"}}'
curl -sS http://127.0.0.1:8092/v1/rpc \
-H 'Content-Type: application/json' \
-d '{"action":"checkpoint.create","params":{"agent_id":"agent-a","session_id":"session-1","checkpoint_id":"clean"}}'
curl -sS http://127.0.0.1:8092/v1/rpc \
-H 'Content-Type: application/json' \
-d '{"action":"session.rollback","params":{"agent_id":"agent-a","session_id":"session-1","checkpoint_id":"clean"}}'进程追踪显式启用后，单次 session.rollback 可传入 "kill_processes": true；
也可用 daemon 参数 --kill-session-processes-on-rollback 设置默认策略。开启后，
Allox OS 先终止目标 Session 的受追踪进程树，再恢复其 Btrfs workspace；其他
Agent、Session 和 Kata VM 不受影响。Kata VM 级恢复会由 VM 生命周期自然重置
全部 Guest 进程，不依赖此 Session 钩子。
allox-os/
├── kernel/ # Allox Guest Kernel 的配置与补丁
├── plugins/ # 独立安装的进程树、文件共享、网络、系统效果插件
├── src/allox/ # Guest daemon、workspace/runtime Core 与 Plugin API v1
├── deploy/ # 当前 Kata runtime 的宿主机部署配置
├── docs/
│ ├── architecture/ # 当前架构与状态语义
│ └── development/ # 当前开发设计选择
└── tests/ # 单元与集成测试
可选的 Agent 观测与 profiling 插件 提供调用轨迹、
工具内部耗时、模型指标、进程资源关联和跨运行语义汇总；通过 --monitor-root 显式启用。
当前为首个实现切片，未宣称覆盖全部系统事件或自动接入所有 Agent 框架。
Agent framework 可通过 Allox OS 的 guest 接口发布 Session/Turn 生命周期事件。 启用后，Allox OS daemon 在 Session 建立时创建基线 checkpoint，并在每个成功结束的 turn 后创建 checkpoint；该策略必须可按 Agent 或 Session 关闭。
uv sync --locked --group dev
uv run pytest -q
uv run ruff check src tests
uv run pyrightPyright 使用 Python 3.10、Linux 平台和 standard 模式，检查 Core 及三个插件的
Python 源码；开发机无需安装或启用插件。PR 和 main 分支推送会自动运行类型检查。
Apache-2.0。