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

arcbox_computer_runtime/
lib.rs
