FluxVM
Run real VMs with a real API.
Primary networking: native eBPF. VM edges require successful attachment by
default; nftables is an explicit compatibility mode. Before upgrading configs
that omit the dataplane mode, follow the eBPF upgrade guide.
One Rust control plane for Firecracker, Cloud Hypervisor, QEMU/KVM and the in-tree FluxVM hypervisor, plus Apple's Virtualization.framework (vz) on a Mac. No libvirtd. No XML. A REST API and a CLI that do the same thing on every backend, with a vsock guest agent instead of SSH.
4 Linux backends + vz on Mac, one API · No libvirtd, no XML · Native KVM, no QEMU · SDKs: Python, Go, TypeScript · Operator verified on real k3s
Quickstart · Mac cloud · Proof · Docs · API · Talk to Zyvor
Your own Mac cloud
FluxVM runs natively on Apple silicon. Its vz backend drives Apple's Virtualization.framework, the hypervisor behind macOS's own virtual machines. One Mac gets Linux VMs, macOS guests, agent sandboxes and container VMs over the same REST API, fluxctl and MCP server as Linux. A shelf of Mac minis and Mac Studios becomes one fleet: fluxvm-agent central places each vz request on the Mac that fits.
| Built for Mac people | |
|---|
| Apple silicon native | Daemon, API and a signed Swift runner per VM (fluxvm-vz-runner); no QEMU, no emulation |
| macOS guests | Install from an IPSW, prepare a template once, clone it with APFS in an instant for Xcode CI (two at a time per Mac, Apple's limit) |
| Rosetta | x86_64 Linux binaries and linux/amd64 container images run in arm64 guests |
| APFS clones and warm starts | Copy-on-write disks and snapshots; a saved VM restores in about 2 s instead of a 10 s boot |
| Shared folders | fluxctl run -v ~/src:/mnt/src: edit on macOS, build in Linux (virtiofs) |
| Keychain sign-in | fluxctl signin keeps a guest password in your login Keychain and types it; the API never returns it |
| launchd | fluxctl service install writes a LaunchAgent, so a headless Mac mini serves VMs after every reboot |
| Agents see the screen | Screenshots, keyboard and mouse for any vz guest, with no Screen Recording permission on the host |
| A throwaway computer per agent task | An offline sandbox (no network card) is ready in about 4.5 s and forks into four running copies in about 4 s; a local model stays reachable over one vsock port. Demo · Agent sessions · Agents page |
curl -fsSL https://raw.githubusercontent.com/zyvorai/zyvor-fluxvm/main/scripts/install.sh | bash # drives Homebrew, starts the service, checks healthz
# or by hand:
brew install zyvorai/tap/fluxvm # prebuilt, Apple silicon, macOS 14+
fluxctl run # a throwaway Debian 13 VM and a shell
fluxctl sandbox run alpine:3.22 --rm -- echo hi # a container in its own VM
The script only runs brew install zyvorai/tap/fluxvm and brew services start, optionally wires an MCP client (bash -s -- --client claude-code), and has --dry-run and --uninstall; read it first at scripts/install.sh. Step by step, with what was tested (daemon as a service, first VM, MCP client): Install on a Mac. From source instead: xcode-select --install && brew install hivex && cargo build -p fluxctl (builds and signs the vz runner).
FluxVM on Mac · Build a Mac cloud · Mac guide · Mac cloud guide · Tenancy, leases and roles · Run central · fluxctl fleet · SDKs and Terraform · Architecture
Measured on one Apple M4 with macOS 27.2. Multi-Mac fleets are not yet verified on real hardware; see Native macOS below for the full list.
What's new
From the CHANGELOG (0.4.x, current release 0.4.18) and recent commits:
| Feature | What it does |
|---|
| Docker and Kubernetes on a Mac | fluxctl docker up runs a real dockerd in one managed VM with its socket on the Mac (build, Compose, bind mounts, networks); fluxctl kube up runs k3s in FluxVM VMs (workers, kube load, offline installs, Cilium by default) and writes a kubeconfig. Studio's Platform → Kubernetes page shows each cluster's nodes and pods, coloured pod logs, a shell in a pod, a traffic graph and a checkpoint timeline (docker, kubernetes) |
| Time travel for a Kubernetes cluster on a Mac | A checkpoint is the whole running VM, saved in about a second: kube try -- kubectl apply then kube undo; kube supervise --auto-checkpoint and kube bisect -- TEST to find the checkpoint where it broke; kube golden, kube reset and kube matrix for clean test runs; kube chaos to kill a pod, stop k3s or fill the disk and restore; kube sleep, --idle-sleep, --sleep-on-battery, woken by the first kubectl or browser request. Single-node clusters (guide with diagrams) |
| Kubernetes on a Mac that feels local | Plain kubectl (the cluster is merged into ~/.kube/config); http://web.localhost and, after kube trust, https://web.localhost for every Service and every Traefik Ingress host; kube add postgres|redis|mysql|mongodb|rabbitmq|nats|mailpit|grafana|redpanda|qdrant|meilisearch|clickhouse|keycloak|seaweedfs|vault|jaeger|temporal with the usual ports and kube connect; kube forward SERVICE, a port-forward that survives pod restarts; kube db-backup / db-restore; kube dev (rebuild and restart on save) and (copy files into a pod on save); , and a notification when a pod crash-loops () |
Why FluxVM
| When this happens… | FluxVM gives you… |
|---|
| Your automation has to template libvirt XML and talk to libvirtd | A JSON VM spec and a full REST API (fluxctl serve), the same on every backend |
| Each hypervisor needs its own tooling | QEMU/KVM, Cloud Hypervisor, Firecracker and the in-tree FluxVM hypervisor behind one trait; "backend":"auto" picks for you |
| Running a command in a guest means SSH keys and a network path | fluxctl exec <id> -- … over vsock through the guest agent |
| AI agents and CI jobs need a throwaway machine with guard rails | Agent sandboxes: egress ACL on method, host and path, a file change-set, a rootless procbox tier, VM fork and ttl_seconds cleanup |
| You want Linux VMs without installing QEMU | A pure in-tree KVM engine: SMP verified at 2, 4 and 8 vCPUs, pause and snapshot across every vCPU |
| You want VMs in Kubernetes without KubeVirt | A DisposableVm CRD and a node-local operator, 9/9 checks on a real k3s cluster |
One API. Every hypervisor.
A JSON spec in, a running VM out. The same fluxctl verbs and the same REST API on every backend, with a vsock guest agent instead of SSH.
sudo fluxctl create --spec examples/qemu.json # boot a VM from a JSON spec
fluxctl list # every VM, every backend
fluxctl exec <id> -- hostname # run a command over vsock — no SSH
fluxctl pause <id> && fluxctl resume <id> # park it instead of rebuilding it
fluxctl delete <id> # or set ttl_seconds and walk away
FluxVM vs libvirt/virsh
FluxVM is the Zyvor host-local replacement for libvirt/virsh VM lifecycle and networking. It is not a drop-in for KubeVirt/OpenShift.
| libvirt/virsh | FluxVM |
|---|
virsh define + virsh start | fluxctl create |
virsh list / virsh suspend / virsh resume | fluxctl list / pause / resume |
virsh console | fluxctl serial (websocket over REST too) |
| XML domain definitions | A JSON VM spec (fluxctl create --spec vm.json) |
| No REST API | A full REST API (fluxctl serve) |
virsh -c qemu+ssh://host | fluxctl --server / fluxctl context (REST, bearer token) |
virsh event | fluxctl events -f (SSE: /v1/events/stream) |
| libvirtd manages networks | TAP/bridge/netns networking managed directly via netlink |
| Choose libvirt when | Your tooling is built on its XML, language bindings and ecosystem (virt-manager, virt-install), or you need hypervisors beyond FluxVM's four |
The full command mapping covers disks, snapshots, backups, clone and events.
eBPF: the VM network, rewritten inside the kernel
Every VM's packets are decided by a kernel-verified eBPF program on its own interface, using per-VM maps.
That's the default dataplane.
- Policy is a map write. Live changes take about 100-120 ms p50, cost the same for the first VM and the hundredth, and never open an allow-all window.
- Fewer hops. The direct datapath cuts the Pod path from 8 devices to 4: -31% latency and +60% small-packet rate in host-forwarding benchmarks.
- Connections survive live migration. Conntrack moves with the VM and is checked against the destination policy.
- See why packets died. Attributed drop reasons, flows, stats and on-demand pcaps over REST. It coexists with Cilium and never writes Cilium's maps.
The eBPF dataplane →
How it fits together
Quickstart
Needs a Linux host with KVM, a Rust toolchain, and a sibling guestkit checkout.
git clone https://github.com/zyvorai/zyvor-fluxvm.git && cd zyvor-fluxvm # needs a sibling guestkit checkout
sudo ./scripts/bootstrap-host.sh vmbr0 && ./scripts/preflight.sh
cargo build --release
sudo install -m 0755 target/release/fluxctl /usr/local/bin/fluxctl
sudo install -m 0644 config.example.toml /etc/fluxvm.toml
sudo fluxctl --config /etc/fluxvm.toml create --spec examples/qemu.json
Day-2 verbs, network modes and remote daemons: Getting started.
Use cases
Every one maps onto what is implemented today. All eleven and docs/use-cases.md.
- CI runners that isolate every job: a VM per job over vsock
exec, with ttl_seconds cleanup.
- AI-agent sandboxes with guard rails: a microVM or a rootless procbox, an egress ACL and a change-set.
- Linux VMs with no QEMU installed: the in-tree KVM engine and a golden template,
fluxctl vm-template create native-agent <name>.
- A golden-image pipeline: build once with
fluxctl build-image, reuse through CoW overlays and a signed catalog.
- Kubernetes-native VMs without KubeVirt and OCI workloads with a per-Pod guest kernel.
Documentation map
Contributing & community
- Contributing: build and test commands, PR expectations and repo layout, in CONTRIBUTING.md.
- Host hardening: TOTP step-up for exec, a signed exec allow-list and signed rule packs, in docs/host-hardening.md.
- Security: the current hardening bar and how to report a vulnerability, in SECURITY.md.
- Changelog: CHANGELOG.md.
Maturity
Proof, not promises. We only claim what has been run. Every line links to how it was verified.
- Kubernetes operator: 9/9 checks on a real k3s cluster, including self-healing and no leaked QEMU. Details
- Multi-host fleet: a central registry with load-aware placement across two physically separate hosts. Details
- Storage and networking: qcow2/raw, LVM thin, NBD and Ceph RBD (against a real Rook cluster); NAT, TAP+bridge, netns+DHCP and macvtap, SSH-verified end to end. Details
- Bridge-less direct datapath: measured −31% latency and +60% 64 B packet rate in the Pod case, on a veth stand-in with no real guest. Method and data
- Native KVM: 2, 4 and 8-vCPU guests boot, pause and snapshot across every vCPU, and a real
fluxctl create passes the agent and NoCloud gate. Details
- The boundaries, up front: multi-tenant controls are opt-in, not a public-cloud boundary, and boot numbers are a method, not a sizing SLA. Read them
| Status | Areas |
|---|
| GA | Network Fabric (TC/eBPF, the default dataplane; nftables via explicit mode = "legacy") · Secure Containers (containerd runtime-v2, not a Kata-equivalence claim) |
| Released (0.4.x) | MCP server, agent sessions (fluxctl agent), host_gpu Metal/MLX inference, sandbox GPUs (Linux VFIO), enforced Kairon VM edge, VM-edge capture, VM fork, VM import, quiesced backups, fleet console |
| Built, not yet run on real hosts | FluxMesh (overlay, DNS, relay, enrollment, public edge): unit tests only; see Proof & status |
| Not by design | KubeVirt compatibility |
Part of the Zyvor stack
FluxVM is complete and useful on its own. Certify with GuestKit → run and manage with FluxVM → convert/deploy with h2kvm.
| Product | Role next to FluxVM |
|---|
| Zyvor Fabric | Private cloud control plane on the same REST API — FluxVM runs the VMs, Fabric adds auth/RBAC, network policy and UX |
| GuestKit | Offline disk scoring/repair; FluxVM's VM import uses it to repair the boot disk |
| h2kvm | Hypervisor → KVM convert + import; hands a certified disk to FluxVM to run |
| Kairon | Posts the VM-edge spec FluxVM enforces in its TC dataplane |
→ zyvor.dev
Support
Free under Apache-2.0. If it helps you, you can donate any amount you like: https://rzp.io/rzp/utwdYh3. A donation is voluntary and supports development and maintenance. It is not a purchase: it buys no support, SLA, features, priority or license, and it is not tax-deductible (Zyvor AI Labs Private Limited is a company, not a charity). Zyvor Enterprise (supported releases, SLAs, a named contact and enterprise features) is separate: [email protected].
License and support
FluxVM is free and open source under the Apache License 2.0 — see NOTICE. Copyright 2026 Zyvor AI Labs. The entire repository is under this one license; there is no dual-licensing or separately-licensed core component.
Zyvor Enterprise adds what production teams ask for: supported releases, deployment and upgrade guidance, priority incident triage, a named technical contact and 24x7 critical intake. Plans and terms: docs/SUBSCRIPTION-MODEL.md · Pricing · [email protected].
Report vulnerabilities per SECURITY.md.
Put a real API in front of your VMs
Native macOS (Apple silicon)
The daemon, API and fluxctl build and run natively on macOS, with a vz backend on Apple's Virtualization.framework for ARM64 Linux guests and, from a prepared template, macOS guests. See docs/macos.md for what is verified and what is not.
The same REST API and fluxctl now run on a Mac mini at home, a Mac Studio for a team or a MacBook Pro on the road. Pair FluxVM with Velora (a private OpenAI-compatible LLM endpoint on MLX) and Kairon (every Mac as a Kubernetes Node) and a few Macs become a quiet, low-power, on-premise inference cluster with real Linux VMs alongside.
Verified on an Apple M4, macOS 27.2: Debian 13 through the API (create, SSH, pause, resume, stop, start, delete), plus port forwards, shared folders, named images, snapshots and warm starts, fluxctl run, stacks (fluxctl up), and agent sandboxes (a warm pool, offline and allow-listed network, speculate and changesets). Container sandboxes (an OCI image in its own VM, fluxctl sandbox run) pass scripts/oci-live-test.sh on the same hardware (exit codes, read-only root, exec, offline and allow-listed network, a private network, linux/amd64 under Rosetta, a warm-pool claim); published TCP and UDP ports pass scripts/oci-udp-ports-live-test.sh (a datagram and a TCP line echoed by the container, a clash refused, delete frees the port); volumes, restart policies, health checks, secret_env, stacks, --fleet placement and the dashboard are unit-tested only. scripts/vz-devices-live-test.sh also passes (extra disks, USB hot-plug, console ports, Linux display size). macOS guests install from an IPSW, boot and clone on the same hardware by hand (details). On macOS 27, the custom Virtio device's control channel (ping, echo, stats, capabilities) works on a Debian 13 guest, host-capabilities reports the M4, and fleet placement for vz (the node heartbeat carries its Apple capabilities and fluxvm-agent central scores nodes with apple_placement) was checked on loopback with one real node plus fake nodes. Not yet verified: multi-Mac clusters on real hardware, Thunderbolt RDMA, macOS guests through the API, the shared vmnet broker and physical USB passthrough (both blocked on the test Mac by signing). Sizing, the cluster design (after GK Servis's Mac Studio case study) and the roadmap: docs/macos-cluster.md.
