Cocoon

Lightweight MicroVM engine with dual hypervisor backends: Cloud Hypervisor (default) and Firecracker.

Documentation: cocoonstack.github.io/cocoon (source in docs/).

Highlights

• OCI VM images — pull container-registry images with kernel + rootfs layers, content-addressed EROFS blob cache; cloud images from HTTP(S) URLs with automatic qcow2 conversion; local file/stdin import
• Docker-like CLI — create, run, start, stop, list, inspect, console, exec, rm, clone, status
• Snapshot & clone — capture a running VM (memory, disks, config) and clone it into new VMs with fresh network identity; clones restore memory copy-on-write by default (page cache shared across sibling clones) and hold shared source leases so parallel clone bursts survive concurrent source removal; restore and atomic hibernate in place; portable export/import between hosts
• CNI networking — multi-queue virtio-net TAPs wired via TC redirect (no bridge in the data path), multi-NIC, bridge mode, NIC hot-resize
• Data disks & runtime attach — extra virtio-blk disks at create/clone time; hot-plug vhost-user-fs shares and VFIO PCI devices (CH); external raw disks and NIC resize on CH or Firecracker --pci VMs; a private copy of a snapshot's COW disk on CH
• Windows guests — UEFI + Hyper-V enlightenments via the cocoonstack CH/firmware forks
• Firecracker backend — --fc for ~125ms boots and <5 MiB per-VM overhead (OCI images only)
• Daemon-optional architecture — one hypervisor process per VM, every command standalone; cocoon daemon optionally adopts running VMs to converge crashes as they happen; modular lock-safe GC with snapshot LRU eviction
• Switchable metadata engine — sqlite by default (fresh roots bootstrap themselves; flat performance at high VM counts), legacy json roots keep working as-is; crash-resumable offline conversion both ways (cocoon meta convert)

Quick Start

# Install the binary (Linux amd64; arm64: cocoon_0.7.2_Linux_arm64.tar.gz)
curl -fsSL -o cocoon.tar.gz https://github.com/cocoonstack/cocoon/releases/download/v0.7.2/cocoon_0.7.2_Linux_x86_64.tar.gz
tar -xzf cocoon.tar.gz && install -m 0755 cocoon /usr/local/bin/

# One-time environment setup (installs CH, firmware, CNI plugins)
curl -fsSL -o cocoon-check https://raw.githubusercontent.com/cocoonstack/cocoon/refs/tags/v0.7.2/doctor/check.sh
install -m 0755 cocoon-check /usr/local/bin/ && sudo cocoon-check --upgrade

# Pull an image and run a VM
cocoon image pull ghcr.io/cocoonstack/cocoon/ubuntu:24.04
cocoon vm run --name my-vm --cpu 2 --memory 1G ghcr.io/cocoonstack/cocoon/ubuntu:24.04

# Interact
cocoon vm console my-vm
cocoon vm exec my-vm -- uname -a

# Snapshot and clone
cocoon snapshot save --name base my-vm
cocoon vm clone base --name fresh

# Clean up
cocoon vm rm --force my-vm fresh

Development

make build    # Build cocoon binary (CGO_ENABLED=0)
make test     # Run tests with race detector and coverage
make lint     # Run golangci-lint (GOOS=linux + darwin)
make fmt      # Format code with gofumpt + goimports
make all      # Full pipeline: deps + fmt + lint + test + build

License

This project is licensed under the MIT License. See LICENSE.