cocoon

Installation

Requirements, install paths, the doctor script, and a first VM.

Requirements

• Linux with KVM (x86_64 or aarch64)
• Root access (sudo)
• Cloud Hypervisor v54 or newer. cocoon-check --upgrade installs the cocoonstack fork dev release build (upstream main plus diff snapshots and guest shadow-stack save/restore, built with the fw_cfg feature that aarch64 OCI boot needs), verified against the release checksums; v53.0 and older have no CopyOnWrite memory restore, so the default clone/restore mode (mmap) is rejected and cocoon-check reports it
• Firecracker v1.16.1 or newer (optional, for the --fc backend). cocoon-check --upgrade installs the cocoonstack fork dev release build (upstream main plus release CI), verified against the release checksums — the build the --pci hot-plug and NIC MTU paths are validated on. vm clone needs >= v1.16 for the vsock override, and v1.16.0 permanently breaks guest vsock after any restore, so v1.16.1 is the effective floor (see known issues)
• qemu-img (from qemu-utils, for cloud images)
• mkfs.erofs from erofs-utils >= 1.8 (for OCI images; 1.7.x tar mode silently corrupts layers — cocoon refuses to convert with older versions)
• UEFI firmware (CLOUDHV.fd, for cloud images and, on aarch64, OCI images; not needed with --fc); on x86_64 cocoon-check --upgrade installs the firmware fork dev build (EFI ResetSystem for ACPI power-button shutdown and the IA32_FEATURE_CONTROL/VMXON lock, both needed by Windows guests — see known issues); on aarch64 it installs the EDK2 CLOUDHV_EFI.fd build ch-97eeb7b09, which loads the OCI kernel over fw_cfg (see Images)
• CNI plugins (bridge, host-local, loopback)
• mkfs.ext4 (from e2fsprogs, for the per-VM COW disk)
• Go 1.27+ (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.7.1/cocoon_0.7.1_Linux_x86_64.tar.gz

# Linux arm64
curl -fsSL -o cocoon.tar.gz https://github.com/cocoonstack/cocoon/releases/download/v0.7.1/cocoon_0.7.1_Linux_arm64.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

Each release also ships an unstripped debug build, cocoon_<version>_Linux_<arch>_debug.tar.gz (binary cocoon.dbg), for symbolized stack traces.

Build from source

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

This produces a cocoon binary in the project root.

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/tags/v0.7.1/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, chmods /dev/kvm, generates a CNI conflist if none exists
cocoon-check --fix

# Generate the CNI bridge config on a different subnet (default 10.88.0.0/16)
cocoon-check --fix --subnet=10.90.0.0/16

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

The --upgrade flag downloads and installs:

• Cloud Hypervisor from the cocoonstack fork dev release (checksum-verified) and upstream ch-remote (static binaries)
• Firecracker from the cocoonstack fork dev release (checksum-verified)
• CLOUDHV.fd firmware: the cocoonstack firmware fork dev build on x86_64 (checksum-verified), EDK2 CLOUDHV_EFI.fd from cloud-hypervisor/edk2 on aarch64 (verified against the digest pinned in the script)
• CNI plugins (bridge, host-local, loopback, etc.)

Release tags and versions are overridable through CH_REF, CH_REMOTE_VERSION, FC_REF, FW_REF, EDK2_REF (with its EDK2_SHA256) and CNI_VERSION (see cocoon-check --help).

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

Shell Completion

# Bash
cocoon completion bash > /etc/bash_completion.d/cocoon

# Zsh
cocoon completion zsh > "${fpath[1]}/_cocoon"

# Fish
cocoon completion fish > ~/.config/fish/completions/cocoon.fish

Development

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

See make help for all available targets.

This site is open source. Improve this page.