arcbox-vm 0.6.8

Guest-side sandbox orchestration over nested Firecracker microVMs; ships the in-sandbox vm-agent init.
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

//! `arcbox-vm` — guest-side Firecracker sandbox orchestration.
//!
//! # Scope
//!
//! This crate runs **inside** the Linux guest VM, managing nested Firecracker
//! microVMs for workload isolation (sandboxes).  It is consumed exclusively by
//! `arcbox-agent`.
//!
//! 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-vm` | guest | nested sandbox microVMs | Firecracker (`fc-sdk`) |
//!
//! It also ships the `vm-agent` binary, which becomes PID 1 *inside* each
//! sandbox. That binary imports only this crate's protocol leaves
//! (`boot_proto`, `file_io::proto`, `file_watch`, `vsock` constants,
//! `listen_table`, `user_spec`) — never the manager. Keep it that way:
//! it is cross-compiled to musl and staged into every sandbox rootfs.
//!
//! # Public API
//!
//! - [`SandboxManager`] — top-level sandbox orchestrator
//! - [`SandboxInstance`] / [`SandboxState`] — per-sandbox runtime state
//! - [`NetworkManager`] — TAP lifecycle & IP allocation
//! - [`VmmConfig`] / [`SandboxSpec`] — configuration types
//!
//! 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.

pub mod boot_proto;
pub mod config;
pub mod error;
pub mod file_io;
pub mod file_watch;
pub mod listen_table;
pub mod network;
pub mod sandbox;
pub mod spawn;
pub mod user_spec;
pub mod vsock;

// 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 arcbox_snapshot::{snapshot, snapshot_cow, template_catalog};

pub use config::{
    DefaultVmConfig, FirecrackerConfig, GrpcConfig, NetworkConfig, SandboxDatapath, VmmConfig,
};
pub use error::{Result, VmmError};
pub use network::{ExposeTarget, NetworkAllocation, NetworkManager};
pub use sandbox::pause_reason;
pub use sandbox::{
    CheckpointInfo, CheckpointSummary, IdleAction, LifecycleUpdate, RestoreSandboxSpec,
    SandboxEvent, SandboxId, SandboxInfo, SandboxManager, SandboxMountSpec, SandboxNetworkIdentity,
    SandboxNetworkInfo, SandboxNetworkSpec, SandboxSpec, SandboxState, SandboxSummary,
    TemplateWarmRef,
};
pub use sandbox::{
    ExecutionChannel, ExecutionOutput, ExecutionSnapshot, ExecutionSpec, StdinState,
};
pub use snapshot::{SnapshotCatalog, SnapshotInfo};
pub use vsock::{ExecInputMsg, ExitStatus, OutputChunk, PortWait, StartCommand};