A3S Box

A3S Box is a lightweight MicroVM runtime that provides container-like UX with VM-level isolation. Built on libkrun, it boots full Linux VMs in under 200ms with a Docker-compatible CLI, Kubernetes CRI integration, and AMD SEV-SNP confidential computing support.

Architecture

┌──────────────────────────────────────────────────────┐
│                Host (a3s-box CLI)                     │
│  ┌────────────────────────────────────────────────┐  │
│  │              CLI (52 commands)                  │  │
│  │  run, create, exec, logs, ps, network...       │  │
│  └───────────────────┬────────────────────────────┘  │
│                      │                                │
│  ┌───────────────────▼────────────────────────────┐  │
│  │         State (~/.a3s/)                         │  │
│  │  boxes.json · images/ · volumes/               │  │
│  └───────────────────┬────────────────────────────┘  │
│                      │                                │
│  ┌───────────────────▼────────────────────────────┐  │
│  │         Runtime Engine                          │  │
│  │  VmManager · OCI · WarmPool · TEE · Network    │  │
│  │  gRPC Clients (Exec, PTY, Attestation)         │  │
│  └───────────────────┬────────────────────────────┘  │
│                      │ vsock                          │
└──────────────────────┼───────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────┐
│              Guest VM (aarch64-linux)                  │
│  ┌────────────────────────────────────────────────┐  │
│  │         guest-init (PID 1)                      │  │
│  │  Exec server (:4089) · PTY server (:4090)      │  │
│  │  Attestation server (:4091)                     │  │
│  └───────────────────┬────────────────────────────┘  │
│                      │                                │
│  ┌───────────────────▼────────────────────────────┐  │
│  │         User Container (namespaces)             │  │
│  │  /a3s/workspace/ · /a3s/skills/ · /run/secrets │  │
│  └────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────┘

Crate Structure

A3S Box is composed of 7 crates, each with a focused responsibility:

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) with dedicated ports:

Key Features

• Sub-200ms cold start via libkrun (Apple HVF / Linux KVM)
• Docker-compatible CLI with 52 commands (run, exec, logs, ps, build, snapshot, compose, etc.)
• OCI image support — pull, push, build, cache, tag, inspect; manifest digest exposed on every pulled image
• Dockerfile build — all 17 instructions, ADD <url> HTTP download, ONBUILD trigger inheritance, multi-stage, multi-platform
• Image signing — cosign key-based and keyless (OIDC + Rekor) verification on pull
• Warm pool — pre-booted VM pool for instant allocation with configurable idle TTL
• Three network modes — TSI (default, zero-config), Bridge (passt, inter-container DNS), None (air-gapped)
• AMD SEV-SNP — hardware memory encryption, remote attestation, RA-TLS, re-attestation, rollback protection
• Sealed storage — AES-256-GCM data sealed to TEE measurement and/or chip identity
• Secret injection — secrets delivered over RA-TLS, written to /run/secrets/ (mode 0400)
• Kubernetes CRI — full CRI v1 implementation, RuntimeClass, Helm chart, streaming exec/attach/port-forward
• Compose orchestration — multi-service compose.yaml with health-aware boot ordering
• Snapshots — create, restore, list, and remove point-in-time VM state snapshots
• Resource controls — CPU pinning, cgroup v2 cpu/memory quotas, PID limits, ulimits
• Namespace isolation — mount, PID, IPC, UTS, user, cgroup namespaces within each VM
• Security — seccomp BPF with arch validation, capability dropping (bounding + ambient), AppArmor/SELinux labels (stored)
• Volume management — named volumes, bind mounts, tmpfs, read-only mounts
• Logging — JSON file driver with gzip-compressed rotation, syslog driver (UDP/TCP)
• Embedded SDK — Rust, Python, and TypeScript SDKs; exec, exec_stream, upload/download, port forwarding, workspaces
• Observability — 19 Prometheus metrics, OpenTelemetry tracing spans, persistent audit log