cocoon

Lightweight MicroVM engine with dual hypervisor backends: Cloud Hypervisor (default) and Firecracker. One hypervisor process per VM, no daemon; Docker-like CLI; snapshots that clone into new identities in tens of milliseconds.

cocoon CLI ──► images: OCI (EROFS layers, direct boot) | cloudimg (qcow2, UEFI)
           ──► vm: create/run/console/exec ── CH or FC, COW disk, CNI/bridge NIC
           ──► snapshot: save/clone/restore/hibernate ── export/import across hosts

Guides

Installation — requirements, releases, the doctor script, quick start, shell completion, building from source
CLI reference — the full command tree and every flag
Images — pulling OCI and cloud images, importing local files, the official image catalog
VM lifecycle — states, shutdown behavior, cloud-init first boot, data disks, performance tuning, live status
Networking — CNI with TC redirect, bridge mode, multi-NIC, NIC hot-resize
Snapshots, clone & restore — capture, clone, restore, hibernate, export/import, cross-node moves
Runtime device attach — vhost-user-fs shares, VFIO PCI passthrough, external disk hot-attach
Windows guests — the --windows path and the patched CH/firmware forks it needs
Firecracker backend — what --fc trades for ~125ms boots and <5 MiB overhead
Garbage collection — cross-module GC and snapshot LRU eviction
OS images — the official Ubuntu/Android/Windows images and the build harness
Known issues — limitations, workarounds, upstream tracking

Features

OCI VM images — pull OCI images with kernel + rootfs layers, content-addressed blob cache with SHA-256 deduplication
Cloud image support — pull from HTTP/HTTPS URLs (e.g. Ubuntu cloud images), automatic qcow2 conversion
Image import — import local qcow2 or tar files (also from stdin or gzip-wrapped streams), auto-detected by magic bytes
UEFI boot — CLOUDHV.fd firmware by default; direct kernel boot for OCI images (auto-detected)
COW overlays — copy-on-write disks backed by shared base images (raw for OCI, qcow2 for cloud images)
CNI networking — automatic NIC creation via CNI plugins, multi-NIC support, per-VM IP allocation
Multi-queue virtio-net — TAP devices created with per-vCPU queue pairs; configurable ring depth (--queue-size, default 512); TSO/UFO/csum offload enabled by default
TC redirect I/O path — veth ↔ TAP wired via ingress qdisc + mirred redirect (no bridge in the data path)
DNS configuration — custom DNS servers injected into VMs via kernel cmdline (OCI) or cloud-init network-config (cloudimg)
Cloud-init metadata — automatic NoCloud cidata FAT12 disk for cloudimg VMs (hostname, configurable user/password via --user/--password, multi-NIC Netplan v2 network-config); cidata is automatically skipped on subsequent boots
User data disks — --data-disk attaches additional virtio-blk disks per VM, with optional ext4 mkfs at create time, cloud-init mounts: auto-mount on cloudimg+CH (via /dev/disk/by-id/virtio-<name>), per-disk DirectIO override, and 1:1 inheritance through snapshot/clone/restore; vm clone --data-disk adds fresh disks to a clone and vm disk attach/detach hot-plugs existing raw files on a running VM (both CH only)
Hugepages — automatic detection of host hugepage configuration; VM memory backed by hugepages when available
Memory balloon — 25% of memory returned via virtio-balloon (deflate-on-OOM, free-page reporting) when memory >= 256 MiB
Graceful shutdown — ACPI power-button for UEFI VMs with configurable timeout, fallback to SIGTERM → SIGKILL
Interactive console — cocoon vm console with bidirectional PTY relay, SSH-style escape sequences (~. disconnect, ~? help), configurable escape character, SIGWINCH propagation
Snapshot & clone — cocoon snapshot save captures a running VM’s full state (memory, disks, config); cocoon vm clone restores it as a new VM with fresh network and identity; all resources (CPU, memory, storage, NIC count) inherit verbatim from the snapshot
Snapshot export & import — cocoon snapshot export packages a snapshot into a portable .tar archive (.tar.gz with --gzip, sparse-aware pax headers); cocoon snapshot import restores it on another host or cluster; supports piping via stdout/stdin for direct host-to-host transfer; --to-dir writes a directory form (with snapshot.json envelope) for NFS / rsync-friendly handoff
Clone / restore from a directory — cocoon vm clone --from-dir DIR and cocoon vm restore --from-dir DIR consume any directory containing a snapshot.json envelope without first registering the snapshot in the local DB; the dir is treated as read-only so multi-VM golden-image use cases work without copying
Live status monitoring — cocoon vm status watches VM state changes in real time via fsnotify, with refresh mode (top-like) and event-stream mode (append-only, for scripting and vk-cocoon integration)
Docker-like CLI — create, run, start, stop, list, inspect, console, rm, debug, clone, status
Structured logging — configurable log level (--log-level), log rotation (max size / age / backups)
Debug command — cocoon vm debug generates a copy-pasteable cloud-hypervisor command for manual debugging
Firecracker backend — --fc flag selects Firecracker for OCI images: ~125ms boot, <5 MiB overhead, minimal attack surface (no UEFI, no qcow2, no Windows)
Zero-daemon architecture — one hypervisor process per VM, no long-running daemon
Garbage collection — modular lock-safe GC with cross-module snapshot resolution; protects blobs referenced by running VMs and snapshots
Doctor script — pre-flight environment check and one-command dependency installation

Repository

Source and issue tracker: github.com/cocoonstack/cocoon. Related projects: sandbox (MicroVM sandboxes for AI agents built on cocoon), cocoon-agent (in-guest vsock agent), windows (Windows image build automation).

This site is open source. Improve this page.