1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
//! `arcbox-computer-runtime` — guest-side sandbox orchestration.
//!
//! # Scope
//!
//! This crate runs **inside** the Linux guest VM, managing nested microVMs
//! for workload isolation (sandboxes) through a `VmDriver`
//! (`arcbox_vm_driver`) — the reference driver is `arcbox-fc-driver`,
//! Firecracker. `arcbox-agent` consumes the orchestration surface. Node image
//! builders can use [`RootfsBuilder`] independently.
//!
//! The **host-side** VMM that boots the guest is [`arcbox-vmm`], which sits on
//! top of `arcbox-hypervisor` (Virtualization.framework on macOS, KVM on
//! Linux). These two crates serve fundamentally different layers and should
//! not be confused:
//!
//! | Crate | Runs on | Purpose | Backend |
//! |-------|---------|---------|---------|
//! | `arcbox-vmm` | host | boot + manage the guest VM | Virtualization.framework / KVM |
//! | `arcbox-computer-runtime` | guest | nested sandbox microVMs | a `VmDriver` (Firecracker via `arcbox-fc-driver`) |
//!
//! The `vm-agent` binary that becomes PID 1 *inside* each sandbox is a
//! separate crate, `arcbox-vm-agent`, and the wire vocabulary the two
//! sides share (boot parameters, exec and file frames) is
//! `arcbox-vm-proto`. Both this manager and the agent link the proto crate;
//! neither links the other, so the crate graph — not a convention — keeps
//! the agent (cross-compiled to static musl and staged into every sandbox
//! rootfs) free of the manager and its dependencies. `boot_proto` and
//! `file_proto` remain reachable through this crate as re-exports.
//!
//! # Public API
//!
//! - [`ComputerManager`] — top-level sandbox orchestrator
//! - [`NodeEnvironment`] — the four environment-specific components a
//! composer supplies, all required: the VM driver, the guest network,
//! the guest-agent factory, and the copy-on-write rootfs manager
//! - [`agent`] — the guest-agent port: how the runtime reaches the agent
//! inside a Computer (exec, files, clock, readiness), with the
//! `arcbox-vm-proto` vsock client as its one implementation
//! - [`RootfsBuilder`] — OCI/overlay2 → ext4 with `/sbin/vm-agent` injected,
//! and the default busybox image; the composer supplies [`RootfsPaths`]
//! - [`ComputerState`] — a computer's public lifecycle state
//! - [`RuntimeConfig`] / [`ComputerSpec`] — configuration types
//!
//! This crate names no VMM and no network implementation. Sandboxes reach
//! both only through `arcbox-vm-driver`'s ports, and the composer supplies
//! the implementations as a [`NodeEnvironment`]; a consumer that needs an
//! adapter's own vocabulary depends on that adapter itself.
//!
//! Snapshot lineage — the checkpoint catalog, the copy-on-write rootfs
//! manager, and the template catalog — lives in `arcbox-snapshot` in the
//! engine layer. The `crate::{snapshot, snapshot_cow, template_catalog}`
//! paths are re-exports of it so existing imports keep resolving; name
//! `arcbox_snapshot` directly in new code.
/// Image sources for [`RootfsBuilder`]. Enable `remote-image` to use `RemoteRef`
/// and retain the resolved image's config and manifest digest before conversion.
pub use oci2rootfs;
/// Boot-parameter vocabulary shared with `vm-agent` (`arcbox_vm_proto::boot`).
pub use boot as boot_proto;
/// File-channel vocabulary shared with `vm-agent` (`arcbox_vm_proto::file`):
/// the stat/event DTOs and the size caps a caller validates against.
pub use file as file_proto;
// The snapshot lineage moved to the engine layer (arcbox-snapshot); these
// paths stay so `arcbox-agent` and this crate's own modules keep compiling.
pub use ;
pub use ;
pub use ;
pub use NodeEnvironment;
pub use ;
pub use ;
pub use pause_reason;
pub use ;
pub use ;
pub use ;