qarax is a management platform for virtual machines running on Cloud Hypervisor and Firecracker.

qarax consists of two main components:

• qarax (control plane) -- Axum REST API server managing VM and host lifecycle, backed by PostgreSQL
• qarax-node (data plane) -- gRPC service running on hypervisor hosts, managing VM execution via Cloud Hypervisor and Firecracker

Supporting crates:

• cli -- Command-line client for the qarax API
• qarax-init -- Minimal PID 1 init process for OCI-booted VMs
• common -- Shared logging and telemetry helpers

Communication flow: control plane -> gRPC (proto/node.proto) -> qarax-node -> selected hypervisor backend.

make build       # build all packages and generate OpenAPI spec
make test        # run tests (auto-starts Postgres via Docker)
make lint        # cargo clippy --workspace -- -D warnings
make ci-checks   # run the same Dagger validation path as GitHub CI Checks

make run-local           # compose mode: qarax + qarax-node + Postgres in Docker Compose
make run-local VM=1      # VM mode: run qarax-node inside a libvirt VM
make stop-local          # stop the stack

Requires Docker, Docker Compose, KVM (/dev/kvm), and a Rust toolchain.

The API serves Swagger UI at http://localhost:8000/swagger-ui.

See docs/HOME_LAB.md for a verified cloud-image walkthrough, an explanation of compose mode vs VM mode, and the steps to turn the same CLI flow into a LAN-reachable home-lab deployment.

See docs/NETWORK_ISOLATION.md for VPC-style subnet grouping, cross-host VXLAN-backed private routing, VM security groups, and the intended CLI workflow.

See docs/PLACEMENT_POLICIES.md for host reservation classes, placement labels, VM placement policies, scheduler ordering, and CLI/API examples.

See the CLI README for full usage. Quick version:

cargo build -p cli --release

qarax configure --server http://localhost:8000
qarax host list
qarax vm list

qarax uses bootc (bootable containers) to deploy hypervisor hosts. The appliance image includes qarax-node, Cloud Hypervisor, Firecracker, and all dependencies.

# Register the host
qarax host add --name node-01 --address 10.0.0.42 --user root

# Build and push the appliance
make appliance-build
make appliance-push

# Deploy and initialize
qarax host deploy node-01 --image ghcr.io/yourorg/qarax-vmm-host:latest --ssh-key ~/.ssh/id_ed25519
qarax host init node-01

See the qarax-node README for runtime dependencies and configuration.

Default boot artifacts are configured per environment in configuration/ (base.yaml, local.yaml, production.yaml), selected by the APP_ENVIRONMENT env var (default: local):

vm_defaults:
  kernel: "/var/lib/qarax/images/vmlinux"
  initramfs: "/var/lib/qarax/images/initramfs.gz"
  cmdline: "console=ttyS0 console=hvc0 root=/dev/vda1"

Working demo setups in demos/: