A3S Box

A3S Box is a MicroVM runtime — run any OCI image in a hardware-isolated virtual machine. Built on libkrun, it provides ~200ms cold start, a Docker-compatible CLI, Kubernetes CRI integration, and optional AMD SEV-SNP confidential computing.

What is a MicroVM?

A MicroVM is a lightweight virtual machine optimized for short-lived workloads. Unlike containers (which share the host kernel), each MicroVM runs its own Linux kernel — providing stronger isolation while maintaining fast startup times.

A3S Box sits between containers and traditional VMs:

• Faster than VMs: ~200ms cold start vs seconds for full VMs
• Stronger than containers: Hardware isolation, separate kernel
• OCI compatible: Run any Docker/OCI image

Architecture

┌──────────────────────────────────────────────────────┐
│                Host (a3s-box CLI)                     │
│  ┌────────────────────────────────────────────────┐  │
│  │              CLI (52 commands)                  │  │
│  │  run, create, exec, logs, ps, network...       │  │
│  └───────────────────┬────────────────────────────┘  │
│                      │                                │
│  ┌───────────────────▼────────────────────────────┐  │
│  │         Runtime Engine                          │  │
│  │  VmManager · OCI · WarmPool · TEE · Network    │  │
│  └───────────────────┬────────────────────────────┘  │
│                      │ vsock                          │
└──────────────────────┼───────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────┐
│              Guest VM (aarch64-linux)                  │
│  ┌────────────────────────────────────────────────┐  │
│  │         guest-init (PID 1)                      │  │
│  │  Exec :4089 · PTY :4090 · Attest :4091         │  │
│  └───────────────────┬────────────────────────────┘  │
│                      │                                │
│  ┌───────────────────▼────────────────────────────┐  │
│  │         User Namespace                           │  │
│  │  /a3s/workspace/ · /run/secrets/               │  │
│  └────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────┘

Crate Structure

VM Lifecycle

Created ──→ Ready ──→ Busy ──→ Compacting ──→ Ready ──→ Stopped
 (create)   (boot)   (exec)   (context gc)    (done)    (kill)

Vsock Communication

Host and guest communicate over vsock (virtio socket):

Key Features

Runtime

• Sub-200ms cold start via libkrun (Apple HVF / Linux KVM / Windows WHPX)
• OCI image support — pull, push, build, cache, tag, inspect; manifest digest exposed
• Dockerfile build — all instructions, ADD <url>, ONBUILD triggers, multi-stage, multi-platform
• Image signing — cosign key-based and keyless verification on pull
• Warm pool — pre-booted VMs for instant allocation
• Snapshots — create, restore, list, remove point-in-time VM state

Network Modes

• TSI (default) — Transparent Socket Impersonation, zero-config
• Bridge — Real eth0 via virtio-net, inter-container DNS
• None — Air-gapped

Security

• Namespace isolation — mount, PID, IPC, UTS, user, cgroup within VM
• AMD SEV-SNP — hardware memory encryption, remote attestation, RA-TLS
• Sealed storage — AES-256-GCM sealed to TEE measurement and/or chip identity
• Secret injection — secrets delivered over RA-TLS to /run/secrets/
• Resource controls — CPU pinning, cgroup v2 quotas, PID limits, ulimits
• Capabilities — --cap-add/drop with bounding + ambient set clearing
• Seccomp — BPF filter with architecture validation

Observability

• 19 Prometheus metrics — VM boot, exec, image pull, cache, pool
• OpenTelemetry tracing — spans for VM lifecycle, exec, destroy
• Audit log — persistent JSON-lines with query filters

Kubernetes

• CRI v1 — RuntimeService + ImageService for kubelet
• Helm chart — DaemonSet + RuntimeClass deployment
• Streaming — exec, attach, port-forward over CRI

Platform Support

Next Steps

• Quick Start — Run your first MicroVM
• CLI Reference — All 52 commands
• Configuration — BoxConfig, resources, caching
• Networking — TSI, bridge, DNS
• TEE — AMD SEV-SNP, attestation, sealed storage
• Kubernetes CRI — RuntimeClass deployment