Skip to content

index.md

Latest commit

 

History

History
81 lines (72 loc) · 6.47 KB

index.md

File metadata and controls

81 lines (72 loc) · 6.47 KB
Raw

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).