README
¶
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, VFIO PCI devices, and external raw disks (CH)
- Windows guests — UEFI + Hyper-V enlightenments via the cocoonstack CH/firmware forks
- Firecracker backend —
--fcfor ~125ms boots and <5 MiB per-VM overhead (OCI images only) - Daemon-optional architecture — one hypervisor process per VM, every command standalone;
cocoon daemonoptionally 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
# One-time environment setup (installs CH, firmware, CNI plugins)
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/ && 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
Full walkthroughs: Installation · CLI reference · Images · VM lifecycle · Networking · Snapshots & clone · Device attach · Windows · Firecracker · GC · Daemon · OS images · Known issues
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.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cliutil
Package cliutil holds dependency-free CLI helpers (flags, table/JSON output) shared by cocoon and downstream CLIs.
|
Package cliutil holds dependency-free CLI helpers (flags, table/JSON output) shared by cocoon and downstream CLIs. |
|
meta/convert
Package convert is the explicit offline engine cutover (design §6): a standalone fsync-first manifest is the only recovery authority, targets are fresh, sources retire aside, and every step is crash-rerunnable.
|
Package convert is the explicit offline engine cutover (design §6): a standalone fsync-first manifest is the only recovery authority, targets are fresh, sources retire aside, and every step is crash-rerunnable. |
|
storebench
command
storebench times meta-engine operations through the hypervisor backend: `update`/`get` are single-process loops at resident N (P0 paired gate and §9 anchors); `create` fans out worker PROCESSES doing reserve+finalize on one shared store — the concurrent VM-creation shape (§9).
|
storebench times meta-engine operations through the hypervisor backend: `update`/`get` are single-process loops at resident N (P0 paired gate and §9 anchors); `create` fans out worker PROCESSES doing reserve+finalize on one shared store — the concurrent VM-creation shape (§9). |
|
Package daemon is the optional resident supervisor: it adopts the CLI's VMM processes, observes exits, and converges metadata and host networking.
|
Package daemon is the optional resident supervisor: it adopts the CLI's VMM processes, observes exits, and converges metadata and host networking. |
|
extend
|
|
|
disk
Package disk is the runtime attach interface for extra virtio-blk disks backed by existing raw files.
|
Package disk is the runtime attach interface for extra virtio-blk disks backed by existing raw files. |
|
fs
Package fs is the runtime attach interface for vhost-user-fs devices (typically virtiofsd).
|
Package fs is the runtime attach interface for vhost-user-fs devices (typically virtiofsd). |
|
netresize
Package netresize is the runtime interface for resizing a VM's NIC count.
|
Package netresize is the runtime interface for resizing a VM's NIC count. |
|
vfio
Package vfio is the runtime attach interface for VFIO PCI passthrough (GPU, NIC, NVMe).
|
Package vfio is the runtime attach interface for VFIO PCI passthrough (GPU, NIC, NVMe). |
|
Package gc runs modular garbage collection: recovery precedes discovery, snapshots are loose, and every destructive decision is revalidated by the module under its own entity locks and tombstone leases.
|
Package gc runs modular garbage collection: recovery precedes discovery, snapshots are loose, and every destructive decision is revalidated by the module under its own entity locks and tombstone leases. |
|
lock
|
|
|
vmlock
Package vmlock resolves per-VM operation locks by vmID alone, so recordless consumers (orphan-netns GC, dead-source clone leases) derive the path without a record.
|
Package vmlock resolves per-VM operation locks by vmID alone, so recordless consumers (orphan-netns GC, dead-source clone leases) derive the path without a record. |
|
Package meta is the unified metadata layer: record-granularity transactions over per-deployment engines (sqlite default, json legacy).
|
Package meta is the unified metadata layer: record-granularity transactions over per-deployment engines (sqlite default, json legacy). |
|
contracttest
Package contracttest is the engine-agnostic meta contract suite: every engine must pass it unmodified.
|
Package contracttest is the engine-agnostic meta contract suite: every engine must pass it unmodified. |
|
json
Package json is the meta engine over today's per-namespace JSON files: same formats, same .prev crash story, same flocks (design §8).
|
Package json is the meta engine over today's per-namespace JSON files: same formats, same .prev crash story, same flocks (design §8). |
|
sqlite
Package sqlite is the meta scale engine: one WAL database, namespace = table group, generic (id, data) rows per root-declared table (§2-§4, v2.28).
|
Package sqlite is the meta scale engine: one WAL database, namespace = table group, generic (id, data) rows per root-declared table (§2-§4, v2.28). |
|
tombstone
Package tombstone is the §5 phase protocol: leased rolls back, deleting rolls forward, every mutation fenced by the holder's lease id.
|
Package tombstone is the §5 phase protocol: leased rolls back, deleting rolls forward, every mutation fenced by the holder's lease id. |
|
Package metering emits append-only VM/snapshot lifecycle endpoints; tenant attribution lives upstream.
|
Package metering emits append-only VM/snapshot lifecycle endpoints; tenant attribution lives upstream. |
|
capture
Package capture is a test-only metering recorder; Entries and Reset are testing helpers.
|
Package capture is a test-only metering recorder; Entries and Reset are testing helpers. |
|
metalog
Package metalog records metering entries in the meta store's log (§1 P3): one Relaxed append per entry — the file backend's no-fsync durability — with a Seq cursor committed atomically alongside each entry.
|
Package metalog records metering entries in the meta store's log (§1 P3): one Relaxed append per entry — the file backend's no-fsync durability — with a Seq cursor committed atomically alongside each entry. |
Click to show internal directories.
Click to hide internal directories.