Skip to main content

​
Network Backends

BoxLite supports pluggable network backends for Box connectivity. Location: boxlite/src/net/

​
Backend Trait

pub trait NetworkBackend: Send + Sync {
    fn start(&mut self) -> BoxliteResult<NetworkConfig>;
    fn stop(&mut self) -> BoxliteResult<()>;
    fn metrics(&self) -> NetworkMetrics;
}

​
Available Backends

User-mode networking based on gVisor’s network stack.
Box                    gvproxy                  Internet
┌──────┐              ┌───────┐              ┌──────────┐
│ eth0 │◄────vsock───▶│       │◄────TCP/UDP─▶│          │
└──────┘              │ NAT   │              │ External │
                      │ DHCP  │              │ Services │
                      │ DNS   │              └──────────┘
                      └───────┘
Features:
  • Full outbound internet access
  • Port forwarding (TCP/UDP)
  • Built-in DHCP and DNS
  • Network metrics (bytes sent/received)

​
Network Configuration

Boxes receive network configuration via DHCP:
  • IP address from virtual subnet
  • Default gateway
  • DNS servers (configurable, defaults to host resolvers)

​
Image Management

BoxLite uses OCI-compatible container images with intelligent caching. Location: boxlite/src/images/

​
Components

ImageManager
├── ImageStore         # OCI blob storage and retrieval
├── ImageStorage       # Layer extraction and caching
└── Archive handlers   # TAR archive processing

​
Image Pull Flow

Registry (Docker Hub, GHCR, ECR, etc.)
           │
           ▼
┌─────────────────────┐
│   OCI Client        │  Pull manifest and layers
└─────────────────────┘
           │
           ▼
┌─────────────────────┐
│   ImageStore        │  Store blobs in ~/.boxlite/images/blobs/
└─────────────────────┘
           │
           ▼
┌─────────────────────┐
│   Layer Extraction  │  Extract to cached layer directories
└─────────────────────┘
           │
           ▼
┌─────────────────────┐
│   Rootfs Assembly   │  Combine layers for Box rootfs
└─────────────────────┘

​
Caching Strategy

  • Blob-level caching: Image layers stored by digest, shared across images
  • Layer deduplication: Common base layers (e.g., debian:slim) extracted once
  • Copy-on-write: Boxes share base layers, only modifications are per-Box

​
Rootfs Preparation

Location: boxlite/src/rootfs/ The rootfs builder assembles a container filesystem from OCI image layers: 
Image Layers          Rootfs Builder              Box Rootfs
┌─────────┐          ┌─────────────┐          ┌─────────────┐
│ Layer 1 │────┐     │             │          │ /bin        │
├─────────┤    │     │  Extract &  │          │ /etc        │
│ Layer 2 │────┼────▶│   Overlay   │─────────▶│ /usr        │
├─────────┤    │     │             │          │ /var        │
│ Layer N │────┘     └─────────────┘          │ ...         │
└─────────┘                                   └─────────────┘
Key operations:
  • Layer extraction and overlay mounting
  • DNS configuration injection
  • Copy-on-write snapshot creation

​
Volume Management

Location: boxlite/src/volumes/

​
Supported Volume Types

TypeDescriptionUse Case
virtiofsHost directory mountSharing files with Box
QCOW2 diskCopy-on-write disk imagePersistent storage

​
virtiofs

virtiofs provides high-performance host directory mounting into the guest VM. Files written inside the Box are immediately visible on the host, and vice versa.
virtiofs requires the guest kernel to support the FUSE-based virtio-fs driver, which is included in BoxLite’s default guest kernel.

​
QCOW2 Disk Images

QCOW2 (QEMU Copy-On-Write v2) disk images provide persistent block storage for Boxes. Features:
  • Thin provisioning: Disk space is allocated on write, not upfront
  • Snapshot support: Point-in-time snapshots of disk state
  • Shared base images: Multiple Boxes can share a common base image with independent writes
QCOW2 volumes persist across Box restarts. Use them for database storage, build caches, or any data that must survive Box lifecycle events.