zyvor-kairon

<div align="center">

# Kairon

[![CI](https://github.com/zyvorai/zyvor-kairon/actions/workflows/ci.yml/badge.svg)](https://github.com/zyvorai/zyvor-kairon/actions/workflows/ci.yml)
[![MCP](https://github.com/zyvorai/zyvor-kairon/actions/workflows/mcp.yml/badge.svg)](https://github.com/zyvorai/zyvor-kairon/actions/workflows/mcp.yml)
[![Release](https://img.shields.io/github/v/release/zyvorai/zyvor-kairon?display_name=tag&color=0071e3)](https://github.com/zyvorai/zyvor-kairon/releases/latest)
[![Go Report Card](https://goreportcard.com/badge/github.com/zyvorai/kairon)](https://goreportcard.com/report/github.com/zyvorai/kairon)
[![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/zyvorai/kairon?label=OpenSSF%20Scorecard)](https://scorecard.dev/viewer/?uri=github.com/zyvorai/kairon)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15141/badge)](https://www.bestpractices.dev/projects/15141)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-1d1d1f.svg)](LICENSE)
[![Go](https://img.shields.io/badge/Go-stdlib--only%20controller%20%C2%B7%20node-00ADD8?logo=go)](docs/DEPENDENCIES.md)

[![Book a demo](https://img.shields.io/badge/Book_a_demo-0071e3?style=for-the-badge)](https://zyvor.dev/schedule?utm_source=github&utm_medium=kairon&utm_campaign=readme_hero)
[![30-day PoC](https://img.shields.io/badge/30--day_PoC-000000?style=for-the-badge)](https://zyvor.dev/poc?utm_source=github&utm_medium=kairon&utm_campaign=readme_hero)
[![Quickstart](https://img.shields.io/badge/Quickstart_in_one_Helm_command-0a84ff?style=for-the-badge)](#quickstart)

![Kairon: real VMs on Kubernetes, no pods pretending](docs/social/kairon-hero-dark.jpg)

### VMs that don't pretend to be Pods.

**Real virtual machines, scheduled by Kubernetes, run straight on KVM.** No `virt-launcher` pod per VM, no libvirt in the hot path, no operator zoo. A `Machine` is desired state, `kairon-controller` places it, and `kairon-node` runs it on [FluxVM](https://github.com/zyvorai/zyvor-fluxvm) with QEMU, Cloud Hypervisor, Firecracker or FluxVM's own hypervisor.

**Zero pods per VM** · **Four hypervisors, one CRD** · **eBPF on every VM edge** · **No silent split-brain** · **AI agents built in (MCP)**

<img src="docs/ux/anim/hero.gif" alt="The Kairon dashboard: overview, machines, migrations, snapshots, nodes, network policies and the all-namespaces view" width="100%">

<sub>Dashboard tour captured against the local sample-data stack (<a href="docs/ux/README.md">how</a>), not a production cluster.</sub>

![Kairon: VMs that don't pretend to be Pods. Measured against KubeVirt v1.9.0: 14x lighter idle control plane, 7.4x faster to SSH for five VMs](docs/assets/readme-hero.jpg)

</div>

---

## What's new

**Experimental operations:** [Kairon Rehearsal](docs/guides/rehearsal.md) tests upgrades on isolated CSI copies. [Advanced operations](docs/guides/advanced-operations.md) adds health-gated configuration change plans, application recovery verification, traffic/RTT placement recommendations, and incident reproduction with fix verification. Includes runnable scenarios and failure-path tests. VM/CSI and host-isolation hardware qualification is still pending.

New since v0.6.0 (latest tag: v0.10.2; the rows down to incident bundles are new in v0.10.0):

| | |
|---|---|
| **Agent sessions (experimental)** | An `AgentSession` is a FluxVM agent session: a sandbox VM with a git workspace, a compiled egress/filesystem/process policy, budgets, checkpoints, live forks and an event ledger, scheduled and quota-counted like a Machine. Commands can wait for an admin's approval; chunked uploads, an interactive shell, credential grants the guest never sees, and the Mac guest's screen. `kaironctl session`, `session_*` MCP tools, both SDKs and a dashboard page. Mac nodes on FluxVM 0.4.8+. [Guide →](docs/guides/agent-sessions.md) |
| **Coming from virtctl** | `kaironctl` covers virtctl's verbs: console and VNC (with screenshots), restart/soft-reboot, exports and memory dumps, guest info, SSH keys and passwords, `expose`, `freeze`, `guestfs`, `cdrom`, `create clone`, `objectgraph`, `--dry-run -o yaml`, `wait`. [CLI →](docs/CLI.md) |
| **Self-test: is it all working?** | `kaironctl selftest` (or the dashboard's Self-test page) boots a tiny CirrOS VM and proves power, network, hotplug, snapshot-restore and more, with live coloured logs and a PASS / FAIL / SKIP table. `deploy-remote.sh --self-test` runs it right after a deploy. [Guide →](docs/guides/selftest.md) |
| **Deploy without building locally** | `deploy-remote.sh --remote-build` copies a small source tarball and compiles on the host, so a laptop needs no Go, no Node and no build cache. [Fastest path →](docs/getting-started.md#fastest-path) |
| **HTTPS by default** | The dashboard and the VNC console relay serve TLS out of the box (generated or bring-your-own certificate); plain HTTP is a named opt-out. [Dashboard guide →](docs/guides/kairon-ui-dashboard.md#https) |
| **Mac Fabric (experimental)** | Several Macs as one pool: each publishes its chip, macOS, Rosetta, nested virtualization and Thunderbolt Bridge; `spec.apple` places vz Machines by them, and a `MacNetwork` gives Machines on different Macs one private network over Thunderbolt. Run against simulated Macs so far. [Guide →](docs/guides/mac-fabric.md) |
| **Cross-cluster DR (experimental)** | A `MachineProtectionPlan` replicates a group of Machines to S3 and keeps their specs and restore points on a second cluster, with RPO and RTO objectives. `kaironctl dr failover` brings them up there in dependency order, `--planned` with nothing lost; `kaironctl dr test` restores copies into an isolated network while production runs, also on a schedule. Machines keep their VirtualNetwork addresses and DNS names follow the active site through external-dns. [Guide →](docs/guides/cross-cluster-dr.md) |
| **vGPU profiles and GPU health (experimental)** | `spec.devices[].profile` gives a Machine a slice of a GPU (NVIDIA vGPU or MIG-backed profile) instead of a whole one, scheduled by free instances and GPU memory, created when the Machine starts and returned when it stops; unhealthy GPUs are skipped. [Guide →](docs/guides/gpu-vgpu.md) |
| **Accelerator profiles (experimental)** | A cluster-scoped `MachineAcceleratorProfile` names an accelerator shape (count, vendor or vGPU profile, memory per device, one PCIe root for peer to peer, one NUMA node, an RDMA NIC next to the GPUs); Machines ask for it with `spec.accelerators`. The profile's status says how many more Machines fit on each node. [Guide →](docs/guides/accelerator-profiles.md) |
| **Node maintenance and DRS (experimental)** | `kaironctl node maintenance enter NODE` cordons a node, migrates its Machines away, and stops or hibernates the ones with nowhere to go; exit puts everything back. DRS (`-drs-mode recommend|automatic`) evens out reserved CPU and memory across nodes, or moves Machines off nodes whose measured CPU, memory or IO pressure (PSI) is high, and `kaironctl drs plan` previews it. [Guide →](docs/guides/node-maintenance-drs.md) |
| **Per-disk I/O QoS** | IOPS and bandwidth limits on a Machine's root and data disks (`io.throttle`), with bursts, enforced by QEMU and changed live on a running Machine. [Guide →](docs/guides/disk-qos.md) |
| **NVMe-oF storage (experimental)** | Kairon's CSI driver provisions `nvme-tcp` and `nvme-rdma` volumes through the kernel NVMe target with native multipath; raw Block volumes boot Machines in place and attach as data disks with per-disk QEMU I/O. [Guide →](docs/guides/machine-storage-nvmeof.md) |
| **Hibernate (experimental)** | `spec.powerState: Hibernated` saves RAM and device state to disk and frees the node; resume continues the same boot, on its own node or a compatible one with shared storage. [Guide →](docs/guides/machine-hibernate.md) |
| **Virtual networks (experimental)** | `VirtualNetwork`: isolated IPv4 networks routed in eBPF with a Geneve overlay, per-network gateway, egress SNAT and floating IPs. [Guide →](docs/guides/virtual-networks.md) |
| **Elastic memory (experimental)** | Run more Machine memory than the node has: guaranteed minimums, a virtio-balloon reclaim loop and a `KaironMemoryPressure` signal the scheduler respects. [Guide →](docs/guides/machine-elastic-memory.md) |
| **Topology-aware placement (experimental)** | NUMA, GPU, NIC and NVMe locality: the scheduler picks the node, exact CPUs, NUMA memory and PCI devices together. [Guide →](docs/guides/machine-topology.md) |
| **Incident bundles (experimental)** | `kaironctl diagnose machine --deep`: one redacted tar.gz with the Machine's cluster state plus QMP, cgroup, console, dataplane and pcap from its node, and an opt-in guest memory dump. [Guide →](docs/guides/machine-incident-bundle.md) |
| **Lifecycle, diagnostics and namespaces (v0.9)** | `kaironctl doctor`, `connectivity test`, `logs`, `events`, `sysdump`, `config`, `history`/`rollback`; `kaironctl upgrade` keeps your previous Helm values. The dashboard has a namespace selector, an all-namespaces Machines view and bulk Start/Stop. [Release notes →](RELEASE_NOTES.md) |
| **`v1` API and new dashboard** | `kairon.zyvor.dev/v1` is the storage version (`v1beta1`/`v1alpha1` served, deprecated). The dashboard is redesigned and gains Storage (Atlas), Pools & claims, Images and Backups pages; `kairon-ui` now listens on `:18082`. [Guide →](docs/guides/kairon-ui-dashboard.md) |
| **Native macOS node** | `kairon-node` registers an Apple silicon Mac as a Node and runs `backend: vz` Machines through FluxVM. Verified on an M4; multi-Mac clusters not yet. [Guide →](docs/macos.md) · [Mac cluster →](docs/macos-cluster.md) |
| **Developer ecosystem kit** | Python and TypeScript SDKs, digest-pinned recipes, disposable-VM GitHub Actions, Terraform composition. [Kit →](ecosystem/README.md) |
| **Fleet automation (experimental)** | Opt-in Redfish fencing, balancing, autoscaling, backup and recovery plans, template claims, usage CS