Crate arcbox_computer_runtime 

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.

Re-exports

pub use agent::ExecInputMsg;

pub use agent::ExitStatus;

pub use agent::OutputChunk;

pub use agent::PortWait;

pub use config::ComputerConfig;

pub use config::DefaultVmConfig;

pub use config::GrpcConfig;

pub use config::NetworkConfig;

pub use config::RuntimeConfig;

pub use environment::NodeEnvironment;

pub use error::ComputerError;

pub use error::Result;

pub use rootfs::ROOTFS_CAPACITY_GRANULARITY;

pub use rootfs::RootfsBuilder;

pub use rootfs::RootfsPaths;

pub use rootfs::RootfsSource;

pub use rootfs::RootfsSpec;

pub use rootfs::VM_AGENT_PATH;

pub use sandbox::pause_reason;

pub use sandbox::CheckpointInfo;

pub use sandbox::CheckpointSummary;

pub use sandbox::ComputerEvent;

pub use sandbox::ComputerId;

pub use sandbox::ComputerInfo;

pub use sandbox::ComputerManager;

pub use sandbox::ComputerMountSpec;

pub use sandbox::ComputerNetworkIdentity;

pub use sandbox::ComputerNetworkInfo;

pub use sandbox::ComputerNetworkSpec;

pub use sandbox::ComputerSpec;

pub use sandbox::ComputerState;

pub use sandbox::ComputerSummary;

pub use sandbox::IdleAction;

pub use sandbox::LifecycleUpdate;

pub use sandbox::RestoreComputerSpec;

pub use sandbox::TemplateWarmRef;

pub use sandbox::ExecutionChannel;

pub use sandbox::ExecutionOutput;

pub use sandbox::ExecutionSnapshot;

pub use sandbox::ExecutionSpec;

pub use sandbox::StdinState;

pub use oci2rootfs;

Modules

agent

The guest-agent port: how the runtime reaches the agent inside a Computer.

boot_proto

Boot-parameter vocabulary shared with vm-agent (arcbox_vm_proto::boot). Boot protocol types shared between the host-side sandbox orchestrator and the guest-side vm-agent.

config

Runtime configuration types.

environment

Environment-specific components a composer supplies to the sandbox stack.

error

file_proto

File-channel vocabulary shared with vm-agent (arcbox_vm_proto::file): the stat/event DTOs and the size caps a caller validates against. File channel: the guest vsock port the agent serves file I/O on.

rootfs

Build bootable ext4 rootfs images for sandboxes.

sandbox

ComputerManager — orchestrates sandbox microVM lifecycle.

snapshot

snapshot_cow

Block-level copy-on-write for sandbox rootfs via dm-snapshot.

template_catalog

On-disk template catalog (CORE-107).

Structs

SnapshotCatalog

Manages the on-disk snapshot catalog for all VMs.

SnapshotInfo

Info returned to callers / gRPC layer.

StartCommand

The command vocabulary the guest agent starts processes from, shared with vm-agent through arcbox-vm-proto. Parameters forwarded to the guest agent as the session-start frame.