A3S Box
A3S Box
Docker-like MicroVM runtime for Linux OCI workloads
A3S Box
A3S Box runs Linux OCI workloads inside libkrun MicroVMs. It gives you a Docker-like CLI and local image store while keeping the workload behind a VM boundary instead of only a namespace boundary.
The most important rule: read A3S Box as a runtime with explicit boundaries, not as a drop-in Docker or Kubernetes replacement.
Status at a Glance
| Area | Current state |
|---|---|
| CLI runtime | Primary product surface. macOS Apple Silicon/HVF and Linux/KVM-style hosts are the intended targets. |
| Images | Pull, load, save, tag, inspect, history, remove, local cache resolution, push, and cosign verification/signing paths exist. Registry-dependent paths need registry access to validate. |
| Dockerfile build | Truthful subset. RUN uses Linux chroot and requires root-capable Linux. macOS rejects RUN by default unless unsafe host execution is explicitly enabled. |
| Networking | TSI default networking, TCP published ports, user-defined bridge networks, and peer /etc/hosts discovery are implemented with platform-specific NAT limits. |
| Compose | Useful local subset; not full Docker Compose parity. |
| TEE | SEV-SNP-oriented attestation, RA-TLS, sealing, secret injection, and simulation mode. Hardware trust depends on capable hosts. TDX is not productized. |
| Kubernetes CRI | Reachable by crictl/kubelet/critest over its Unix socket. Core pod + container lifecycle and exec over the Kubernetes SPDY/3.1 remotecommand protocol work end to end (verified on a /dev/kvm host). Not yet working: attach and full critest conformance. Linux-only; Windows CRI is out of scope. |
| Windows | Native WHPX path through libkrun. It runs directly on Windows with Windows Hypervisor Platform enabled and does not require WSL. |
Mental Model
Host
a3s-box CLI
image store, box state, volume store, network store
VmManager
|
| shim process + libkrun
v
MicroVM
guest-init (PID 1)
exec server, PTY server, attestation server
user workload from OCI imageThe host prepares the rootfs and starts a shim. The shim configures libkrun. Inside the VM, guest-init starts control services and launches the workload command.
What Works Well Today
- Running standard Linux OCI images in foreground, detached, and interactive modes.
- Persisted
create/startflows with command, entrypoint, env, workdir, user, hostname, and hosts configuration. - Exec, PTY, CLI
attach, logs, wait, stats, inspect, pause/unpause, restart, and cleanup flows. - Image lifecycle: pull, load, save, tag, inspect, history, prune, remove, and selected push/signing workflows.
- Volumes,
cp,diff,export,commit, and configuration/filesystem snapshots. - TCP port publishing and bridge peer discovery on supported hosts.
- Compose subset for local multi-service development.
Product Boundaries
- No full Docker daemon API.
- No full Dockerfile/buildx parity; multi-platform indexes are not implemented.
- No live network hot-plug or hot-unplug; stop the box first.
- No enforced strict/custom network policy yet; unsupported policies are rejected.
- No macOS bridge outbound NAT; use default TSI mode for outbound internet on macOS.
- No production Windows CRI; Windows packaging uses the native WHPX path.
- No TDX product path yet.
Next Pages
- Quick Start starts a VM and shows the core loop.
- Images explains pull, build, cache, save/load, and signing boundaries.
- Networking explains TSI, bridge, ports, and NAT limits.
- TEE Security separates simulation from hardware trust.
- Kubernetes CRI documents the CRI surface: working lifecycle and
exec, and what is not yet conformant. - CLI Reference lists the command families and unsupported options.