Networking & Storage

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

gvproxy (Default)
libslirp (Alternative)

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

Type	Description	Use Case
virtiofs	Host directory mount	Sharing files with Box
QCOW2 disk	Copy-on-write disk image	Persistent 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.

Getting Started

Tutorials

Guides

SDK Reference

Architecture

Resources

Development

Network Backends

Backend Trait

Available Backends

Network Configuration

Image Management

Components

Image Pull Flow

Caching Strategy

Rootfs Preparation

Volume Management

Supported Volume Types

virtiofs

QCOW2 Disk Images

​Network Backends

​Backend Trait

​Available Backends

​Network Configuration

​Image Management

​Components

​Image Pull Flow

​Caching Strategy

​Rootfs Preparation

​Volume Management

​Supported Volume Types

​virtiofs

​QCOW2 Disk Images

Network Backends

Backend Trait

Available Backends

Network Configuration

Image Management

Components

Image Pull Flow

Caching Strategy

Rootfs Preparation

Volume Management

Supported Volume Types

virtiofs

QCOW2 Disk Images