Cocoon

Lightweight MicroVM engine built on Cloud Hypervisor.

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
• 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; 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, root password, multi-NIC Netplan v2 network-config); cidata is automatically skipped on subsequent boots
• 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, resource inheritance with validation
• Snapshot export & import — cocoon snapshot export packages a snapshot into a portable .tar.gz archive (with sparse-aware pax headers); cocoon snapshot import restores it on another host or cluster
• 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
• Zero-daemon architecture — one Cloud 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

Requirements

• Linux with KVM (x86_64 or aarch64)
• Root access (sudo)
• Cloud Hypervisor v51.0+ (for Windows VMs, use our CH fork and firmware fork for full compatibility — see KNOWN_ISSUES.md)
• qemu-img (from qemu-utils, for cloud images)
• UEFI firmware (CLOUDHV.fd, for cloud images)
• CNI plugins (bridge, host-local, loopback)
• Go 1.25+ (build only)

Installation

GitHub Releases

Download pre-built binaries from GitHub Releases:

# Linux amd64
curl -fsSL -o cocoon.tar.gz https://github.com/cocoonstack/cocoon/releases/download/v0.2.6/cocoon_0.2.6_Linux_x86_64.tar.gz
tar -xzf cocoon.tar.gz
install -m 0755 cocoon /usr/local/bin/

# Or use go install
go install github.com/cocoonstack/cocoon@latest

Build from source

git clone https://github.com/cocoonstack/cocoon.git
cd cocoon
make build

This produces a cocoon binary in the project root. Use make install to install into $GOPATH/bin.

Doctor

Cocoon ships a diagnostic script that checks your environment and can auto-install all dependencies:

# Get script
curl -fsSL -o cocoon-check https://raw.githubusercontent.com/cocoonstack/cocoon/refs/heads/master/doctor/check.sh
install -m 0755 cocoon-check /usr/local/bin/

# Check only — reports PASS/FAIL for each requirement
cocoon-check

# Check and fix — creates directories, sets sysctl, adds iptables rules
cocoon-check --fix

# Full setup — install cloud-hypervisor, firmware, and CNI plugins
cocoon-check --upgrade

The --upgrade flag downloads and installs:

• Cloud Hypervisor + ch-remote (static binaries)
• CLOUDHV.fd firmware (rust-hypervisor-firmware)
• CNI plugins (bridge, host-local, loopback, etc.)

Quick Start

# Set up the environment (first time)
sudo cocoon-check --upgrade

# Pull an OCI VM image
cocoon image pull ghcr.io/cocoonstack/cocoon/ubuntu:24.04

# Or pull a cloud image from URL
cocoon image pull https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-amd64.img

# Create and start a VM
cocoon vm run --name my-vm --cpu 2 --memory 1G ghcr.io/cocoonstack/cocoon/ubuntu:24.04

# Attach interactive console
cocoon vm console my-vm

# List running VMs
cocoon vm list

# Stop and delete
cocoon vm stop my-vm
cocoon vm rm my-vm

CLI Commands

cocoon
├── image
│   ├── pull IMAGE [IMAGE...]      Pull OCI image(s) or cloud image URL(s)
│   ├── list (alias: ls)           List locally stored images
│   ├── rm ID [ID...]              Delete locally stored image(s)
│   └── inspect IMAGE              Show detailed image info (JSON)
├── vm
│   ├── create [flags] IMAGE       Create a VM from an image
│   ├── run [flags] IMAGE          Create and start a VM
│   ├── clone [flags] SNAPSHOT     Clone a new VM from a snapshot
│   ├── start VM [VM...]           Start created/stopped VM(s)
│   ├── stop VM [VM...]            Stop running VM(s)
│   ├── list (alias: ls)           List VMs with status
│   ├── inspect VM                 Show detailed VM info (JSON)
│   ├── console [flags] VM         Attach interactive console
│   ├── rm [flags] VM [VM...]      Delete VM(s) (--force to stop first)
│   ├── restore [flags] VM SNAP   Restore a running VM to a snapshot
│   ├── status [VM...]             Watch VM status in real time
│   └── debug [flags] IMAGE        Generate CH launch command (dry run)
├── snapshot
│   ├── save [flags] VM            Create a snapshot from a running VM
│   ├── list (alias: ls)           List all snapshots
│   ├── inspect SNAPSHOT           Show detailed snapshot info (JSON)
│   ├── rm SNAPSHOT [SNAPSHOT...]  Delete snapshot(s)
│   ├── export [flags] SNAPSHOT    Export snapshot to portable archive
│   └── import [flags] FILE        Import snapshot from portable archive
├── gc                             Remove unreferenced blobs and VM dirs
├── version                        Show version, revision, and build time
└── completion [bash|zsh|fish|powershell]

Global Flags

| Flag | Env Variable | Default | Description | | ----------------- | ------------------------------ | ------------------ | -------------------------------------- | | --config | | | Config file path | | --root-dir | COCOON_ROOT_DIR | /var/lib/cocoon | Root directory for persistent data | | --run-dir | COCOON_RUN_DIR | /var/lib/cocoon/run | Runtime directory for sockets and PIDs | | --log-dir | COCOON_LOG_DIR | /var/log/cocoon | Log directory for VM and process logs | | --log-level | COCOON_LOG_LEVEL | info | Log level: debug, info, warn, error | | --cni-conf-dir | COCOON_CNI_CONF_DIR | /etc/cni/net.d | CNI plugin config directory | | --cni-bin-dir | COCOON_CNI_BIN_DIR | /opt/cni/bin | CNI plugin binary directory | | --root-password | COCOON_DEFAULT_ROOT_PASSWORD | | Default root password for cloudimg VMs | | --dns | COCOON_DNS | 8.8.8.8,1.1.1.1 | DNS servers for VMs (comma separated) |

VM Flags

Applies to cocoon vm create, cocoon vm run, and cocoon vm debug:

| Flag | Default | Description | | ----------- | ---------------- | --------------------------------------------- | | --name | cocoon-<image> | VM name | | --cpu | 2 | Boot CPUs | | --memory | 1G | Memory size (e.g., 512M, 2G) | | --storage | 10G | COW disk size (e.g., 10G, 20G) | | --nics | 1 | Number of network interfaces (0 = no network) | | --network | empty (default) | CNI conflist name (empty = first conflist) | | --windows | false | Windows guest (UEFI boot, kvm_hyperv=on, no cidata) |

Clone Flags

Applies to cocoon vm clone:

| Flag | Default | Description | | ----------- | ------------------------ | ------------------------------------------------------- | | --name | cocoon-clone-<id> | VM name | | --cpu | 0 (inherit) | Boot CPUs (must be >= snapshot value) | | --memory | empty (inherit) | Memory size (must be >= snapshot value) | | `--