A modern, minimal virtualization platform for datacenters and home labs.
- Download the latest ISO and kctl from Releases
- Write the ISO to a USB stick and boot your machine from it
- From your laptop, install kcore to disk remotely:
kctl --insecure node disks --node <node-ip>:9091
kctl --insecure node install \
--node <node-ip>:9091 \
--os-disk /dev/sda \
--data-disk /dev/nvme0n1- After reboot, create VMs:
kctl create vm web-server --cpu 4 --memory 8G
kctl get vmsSee the Quick Start Guide for a full walkthrough.
- Quick Start Guide - Complete installation walkthrough from USB to running VMs
- Installation (Automator API) - Remote node install flow (disk discovery, install manifest, install command)
- Installation - Detailed install, certs, multi-node setup
- kctl CLI - User-friendly CLI for managing VMs and resources
- Commands Reference - All make commands with examples
- Architecture - System design, workflows, and component communication
- Building ISO Remote - Remote ISO building
- Terraform Provider - IaC for kcore VMs
- Building Node Agent - How to build node-agent
- Project Structure - Codebase organization
- Release Process - Build and publish release artifacts
kcore is a clustered KVM virtualization platform that provides:
- Simple VM Management - Create, manage, and delete VMs via API
- Automated Deployment - Boot from USB, run one command, reboot
- Controller + Agent Architecture - Controller orchestrates runtime + automator workflows across nodes
- Modern Stack - Go + gRPC + NixOS + KVM/libvirt
- Network Fabric - EVPN + VXLAN overlays for multi-node networking
- Controller - Deployed on a node, manages cluster state and scheduling
- Node Agent Runtime API - Runs on each compute node, manages local VMs/storage
- Node Agent Automator API - Handles host bootstrap operations (apply Nix, install workflows)
- kcore ISO - Bootable installer with everything included
- Nix with flakes enabled
- Go 1.22+
- Make
# Clone repository
git clone https://github.com/rtacconi/kcore.git
cd kcore
# Enter Nix dev shell
nix develop
# Generate protobuf code
make proto
# Build components
make controller
make node-agent-nix
make build-isomake help # Show all commands
make proto # Generate protobuf code
make controller # Build controller
make kctl # Build kctl CLI
make node-agent-nix # Build node-agent
make build-iso # Build kcore ISO
NODE_IP=x.x.x.x make create-vm # Create VM
NODE_IP=x.x.x.x make test-node # Test nodeSee Commands Reference for full list.
┌─────────────────────┐
│ Controller │ desired state, scheduling, reconciliation
│ (port 9090) │
└──────────┬──────────┘
│ gRPC (mTLS)
┌──────┴─────────────────────┐
│ │
┌───▼───────────────────┐ ┌─────▼───────────────────┐
│ Node Agent Runtime API│ │ Node Agent Automator API│
│ (VM/storage operations)│ │ (bootstrap/install ops) │
└───────────────────────┘ └─────────────────────────┘
▲ ▲
└──── state + system info ───┘
Controller <── CRDT state exchange (next phase) ──> Controller
- Controller receives desired-state requests and coordinates runtime + automator workflows
- Node Agent Runtime API manages local VMs via libvirtd
- Node Agent Automator API manages host-level provisioning and install operations
- Networking uses EVPN + VXLAN overlays
- Communication uses gRPC with mutual TLS authentication
See Architecture for detailed design and deployment model.
Fully Automated
- Boot from USB → Install remotely via Automator API → Auto-reboot
- All services start automatically
- Node auto-registers with controller
Hardware Auto-Detection
- DHCP on all interfaces
- Works with any NIC
- No manual configuration
Production Ready
- libvirtd + virtlogd managed by systemd
- Automatic service restarts
- Comprehensive logging
Developer Friendly
- Make-based build system
- Nix flake dev environment
- Scripts in separate files (not inline)
# Build ISO
make build-iso
# Write to USB
USB_DEVICE=/dev/disk4 make write-usb
# Boot node from USB, then install remotely via Automator API:
kctl --insecure node disks --node <node-ip>:9091
kctl --insecure node install \
--node <node-ip>:9091 \
--os-disk /dev/sda \
--data-disk /dev/nvme0n1 \
--join-controller <controller-ip># Create VM
kctl create vm web-server --cpu 4 --memory 8G --disk 100G
# List VMs
kctl get vms
# Get VM details
kctl describe vm web-server
# Delete VM
kctl delete vm web-server# Rebuild node-agent
make node-agent-nix
# Deploy to node
NODE_IP=192.168.40.146 make deploy-node
# Restart service
ssh root@192.168.40.146 systemctl restart kcore-node-agentkcore/
├── cmd/
│ ├── controller/ # Controller binary
│ └── node-agent/ # Node agent binary
├── pkg/
│ ├── config/ # Configuration parsing
│ ├── controller/ # Controller logic
│ └── sqlite/ # Database
├── node/
│ ├── libvirt/ # Libvirt integration
│ ├── storage/ # Storage drivers
│ └── server.go # gRPC server
├── api/ # Generated protobuf code
├── proto/ # Protobuf definitions
├── modules/ # NixOS modules
├── scripts/ # Automation scripts
├── docs/ # Documentation
└── examples/ # Example configs
See Project Structure for details.
Contributions welcome! Please:
- Read the documentation in
docs/ - Use Conventional Commits for commit messages
- Test changes on both macOS and Linux where applicable
[Add your license here]
- Repository: https://github.com/rtacconi/kcore
- Issues: https://github.com/rtacconi/kcore/issues
- Documentation: docs/
For help:
- Read Quick Start Guide
- See Commands Reference
- Review Architecture