Technical Architecture

How kcore is built. Go control plane, NixOS host, gRPC APIs, multi-node topology.

Overview

kcore is a virtualization platform with a distributed architecture. A central controller manages cluster state while node agents run on each physical machine, managing VMs through libvirt. All communication is via gRPC with mTLS.

The host OS is NixOS — fully declarative and immutable at runtime. The control plane is written in Go. There is no PHP, no Perl, no legacy web framework. The API is the product.

System Topology

Controller

Go binary

SQLite state store

gRPC server (port 9090)

Scheduling, API, cluster state

gRPC + mTLS

Node Agent

Go binary

libvirtd

gRPC server (port 9091)

VM lifecycle, storage

Node Agent

Go binary

libvirtd

gRPC server (port 9091)

VM lifecycle, storage

Node Agent

Go binary

libvirtd

gRPC server (port 9091)

VM lifecycle, storage

Control Plane

The controller is a single Go binary that manages cluster state. It exposes a gRPC API that the CLI, Terraform provider, MCP server, and any other tooling consumes.

Language: Go
State store: SQLite (embedded, no external database dependency)
API protocol: gRPC with Protocol Buffers
Authentication: mTLS (mutual TLS) with auto-generated certificates
Deployment: Runs on your workstation or a dedicated management node

controller

// API surface (simplified)

service KcoreService {
  rpc ListVMs(ListVMsRequest)
      returns (ListVMsResponse);

  rpc CreateVM(CreateVMRequest)
      returns (VM);

  rpc DeleteVM(DeleteVMRequest)
      returns (Empty);

  rpc ListNodes(Empty)
      returns (ListNodesResponse);

  rpc GetNodeStatus(NodeRequest)
      returns (NodeStatus);
}

NixOS Host

Each compute node runs NixOS. The entire system configuration is defined in Nix — packages, services, network, storage. The system is immutable at runtime. Changes require a rebuild that produces a new bootable generation.

Base OS: NixOS (declarative Linux distribution)
Updates: Atomic. New generation on every change. Instant rollback via boot menu.
Virtualization: libvirtd + QEMU/KVM, managed by systemd
Installation: Boot from USB ISO, run install-to-disk, reboot
Reproducibility: Same Nix flake produces identical systems across all nodes

nix

# Node configuration (simplified)
{
  services.kcore-agent = {
    enable = true;
    controllerAddr = "10.0.0.1:9090";
  };

  virtualisation.libvirtd = {
    enable = true;
    qemu.runAsRoot = true;
  };

  networking = {
    bridges.br0.interfaces =
      [ "enp3s0" ];
    useDHCP = true;
  };

  fileSystems."/var/lib/kcore" = {
    device = "/dev/vg0/kcore";
    fsType = "ext4";
  };
}

gRPC API Design

The API is the primary interface to kcore. Everything the CLI can do, the API can do. Everything a Terraform provider needs, the API provides. AI agents interact through the same API — no special endpoints, no separate "agent mode."

Protocol: gRPC over HTTP/2
Schema: Protocol Buffers v3 — typed, versioned, backwards-compatible
Streaming: Server-side streaming for logs, events, long-running operations
Client generation: Generate clients in Go, Python, Rust, TypeScript from the proto definitions
Agent-friendly: Structured requests and responses. No HTML to parse, no CLI output to regex.

grpcurl

$ grpcurl -d '{}' \
    localhost:9090 \
    kcore.v1.KcoreService/ListVMs

{
  "vms": [
    {
      "name": "web-01",
      "status": "RUNNING",
      "node": "node-01",
      "memory_mb": 4096,
      "vcpu": 4,
      "storage_gb": 50
    }
  ]
}

Storage Architecture

Use the storage backend that fits your hardware and use case.

Local Directory

Store VM disk images as files on a local filesystem. Simple, fast, no dependencies. Good for single-node setups and home labs.

Available

LVM

Logical Volume Manager for flexible disk allocation. Thin provisioning, snapshots. Recommended for multi-VM hosts.

Available

ZFS

Copy-on-write filesystem with built-in snapshots, compression, and checksumming. Ideal for data integrity and advanced storage needs.

Planned

API Consumers

The same API serves every interface. No special cases.

kctl CLI

Primary operator tool. Create, manage, and inspect VMs and nodes. Thin wrapper around the gRPC API.

Available

Terraform Provider

Manage kcore resources as infrastructure as code. Integrates with existing Terraform workflows.

In Progress

MCP Server

Model Context Protocol server for AI agent integration. Agents query and manage infrastructure through structured tools.

In Progress

Web Dashboard

Read-only cluster visibility. The dashboard consumes the API — it does not have special access.

Planned

Want to Dig Deeper?

Read the documentation for setup guides, API reference, and CLI usage. Or reach out if you want to discuss the architecture.

Read the Docs Contact Us