cc

cc is an experimental microVM runtime for OCI-backed Linux workloads. It imports OCI, SIMG/SIF, and CVMFS-backed images, boots a managed Linux guest, mounts image environments through virtio-fs, and executes commands through a local HTTP/WebSocket daemon.

The runtime is workload-centric rather than hypervisor-centric: callers manage images, instances, execs, and shares without providing kernels, wiring boot devices, or running a privileged helper daemon.

This repository is published at github.com/tinyrange/cc.

Status

Supported host backends:

• linux/amd64 via KVM
• linux/arm64 via KVM
• darwin/arm64 via HVF
• windows/amd64 via Windows Hypervisor Platform

The stable amd64 backends (linux/amd64 and windows/amd64) support native amd64 images, one-shot command execution, persistent VMs, writable host shares, local SIMG containers, remote Neurodesk CVMFS containers, and attaching additional image environments inside a running VM. Known foreign-architecture images are rejected on amd64 hosts; arm64 guest emulation is not implemented there yet.

Runtime networking and snapshots are roadmap features. Snapshots are currently treated as a future performance optimization rather than an MVP 1 requirement.

Requirements

• Go 1.25 or newer, matching go.mod
• A supported host architecture
• Linux KVM hosts: /dev/kvm, regular-user permission to open it, and hardware virtualization enabled. Some distributions grant this automatically; others require one-time host configuration outside cc.
• Windows amd64 hosts: Windows Hypervisor Platform enabled and hardware virtualization available.
• Network access for kernel downloads, OCI pulls, or CVMFS-backed containers

Quick KVM check:

test -r /dev/kvm -a -w /dev/kvm && echo "KVM is accessible"

Build

git clone https://github.com/tinyrange/cc.git
cd cc
go build ./cmd/cc
go build ./cmd/ccvm

For a throwaway local build:

tmp="$(mktemp -d)"
go build -o "$tmp/cc" ./cmd/cc
go build -o "$tmp/ccvm" ./cmd/ccvm

CLI Usage

cc starts ccvm automatically when needed. If the binaries are not installed next to each other, pass the daemon path explicitly:

cc -ccvm ./ccvm doctor
cc -ccvm ./ccvm status

The daemon also exposes a capability summary at GET /capabilities, including the active host backend, VM support state, instance concurrency, supported share semantics, and roadmap feature slots for networking and snapshots.

VM boot waits default to 5 seconds. Set CCX3_VM_BOOT_TIMEOUT to a positive number of seconds when running on slower hosts or diagnosing long boots.

Long-running CLI operations use the daemon's streaming endpoints. Human progress for doctor, pull, and start is written to stderr when stderr is a terminal; stdout remains reserved for command output and JSON responses.

Run the small tracked Alpine bringup SIMG:

cc -ccvm ./ccvm pull alpine ./fixtures/alpine.simg
cc -ccvm ./ccvm run alpine -- sh -lc 'cat /etc/alpine-release'

Run directly from Neurodesk CVMFS:

cc -ccvm ./ccvm pull niimath-cvmfs \
  http://cvmfs.neurodesk.org/cvmfs/neurodesk.ardc.edu.au/containers/niimath_1.0.20250804_20251016

cc -ccvm ./ccvm run niimath-cvmfs -- niimath -help

Persistent VM flow:

cc -ccvm ./ccvm start niimath-cvmfs
cc -ccvm ./ccvm run niimath-cvmfs -- niimath -help
cc -ccvm ./ccvm stop

Named VM flow:

cc -ccvm ./ccvm vm start work-a alpine
cc -ccvm ./ccvm vm start work-b niimath-cvmfs
cc -ccvm ./ccvm vm list
cc -ccvm ./ccvm vm run work-a -- sh -lc 'cat /etc/alpine-release'
cc -ccvm ./ccvm vm status work-b
cc -ccvm ./ccvm vm stop work-a
cc -ccvm ./ccvm vm stop work-b

Port forwarding is available for named VMs with a HOST_PORT:GUEST_PORT mapping:

cc -ccvm ./ccvm vm forward work-a 8080:80

The simple start, stop, status, and run commands continue to operate on the default VM. The daemon also supports named instances through id fields on VM and exec requests and through GET /vm for listing. Reported max_instances is a daemon concurrency limit, not a guarantee that the host has enough free memory or CPU for that many guests.

Python Client

The Python package lives in pyneurodesk/ and is published as neurodesk. It can start or connect to the daemon, import Neurodesk containers from CVMFS, and expose container commands through Python or shell wrappers.

pip install neurodesk

Example:

import neurodesk as nd

nm = nd.container("niimath")
print(nm.run("niimath", "-help"))

See pyneurodesk/README.md for Python-specific usage.

Repository Layout

• cmd/cc: user-facing CLI
• cmd/ccvm: local HTTP/WebSocket daemon
• internal/hv: host virtualization support
• internal/vm: runtime backend orchestration
• internal/oci: OCI, SIMG/SIF, and CVMFS image import
• internal/cvmfs: minimal remote CVMFS catalog and file client
• pyneurodesk: Python client and shell integration
• PLAN.md: linux/amd64 support plan and milestone notes