arcbox_computer_runtime/
lib.rs

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

arcbox_computer_runtime/
lib.rs
