{"id":45390354,"url":"https://github.com/qarax/qarax","last_synced_at":"2026-04-18T14:10:25.148Z","repository":{"id":40243460,"uuid":"269713136","full_name":"qarax/qarax","owner":"qarax","description":"soon","archived":false,"fork":false,"pushed_at":"2026-04-04T08:41:10.000Z","size":26742,"stargazers_count":12,"open_issues_count":1,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-04T10:38:11.057Z","etag":null,"topics":["axum","firecracker","hacktoberfest","rust","virtualization"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qarax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2020-06-05T17:03:54.000Z","updated_at":"2026-04-04T08:32:52.000Z","dependencies_parsed_at":"2023-12-17T12:27:19.046Z","dependency_job_id":"1d8756f1-e469-49d5-abe8-66fa66a8ed60","html_url":"https://github.com/qarax/qarax","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/qarax/qarax","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qarax%2Fqarax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qarax%2Fqarax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qarax%2Fqarax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qarax%2Fqarax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qarax","download_url":"https://codeload.github.com/qarax/qarax/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qarax%2Fqarax/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31971524,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["axum","firecracker","hacktoberfest","rust","virtualization"],"created_at":"2026-02-21T18:21:45.925Z","updated_at":"2026-04-18T14:10:25.131Z","avatar_url":"https://github.com/qarax.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# qarax\n\nqarax is a management platform for virtual machines running on Cloud Hypervisor.\n\n## Architecture\n\nqarax consists of two main components:\n\n- **[qarax](qarax/)** (control plane) -- Axum REST API server managing VM and host lifecycle, backed by PostgreSQL\n- **[qarax-node](qarax-node/)** (data plane) -- gRPC service running on hypervisor hosts, managing VM execution via Cloud Hypervisor\n\nSupporting crates:\n\n- **[cli](cli/)** -- Command-line client for the qarax API\n- **[qarax-init](qarax-init/)** -- Minimal PID 1 init process for OCI-booted VMs\n- **[common](common/)** -- Shared logging and telemetry helpers\n\nCommunication flow: control plane -\u003e gRPC (`proto/node.proto`) -\u003e qarax-node -\u003e Cloud Hypervisor API.\n\n## Building\n\n```bash\nmake build       # build all packages and generate OpenAPI spec\nmake test        # run tests (auto-starts Postgres via Docker)\nmake lint        # cargo clippy --workspace -- -D warnings\n```\n\n## Running locally\n\n```bash\nmake run-local           # compose mode: qarax + qarax-node + Postgres in Docker Compose\nmake run-local VM=1      # VM mode: run qarax-node inside a libvirt VM\nmake stop-local          # stop the stack\n```\n\nRequires Docker, Docker Compose, KVM (`/dev/kvm`), and a Rust toolchain.\n\nThe API serves Swagger UI at `http://localhost:8000/swagger-ui`.\n\nSee [docs/HOME_LAB.md](docs/HOME_LAB.md) for a verified cloud-image walkthrough,\nan explanation of compose mode vs VM mode, and the steps to turn the same CLI\nflow into a LAN-reachable home-lab deployment.\n\n## CLI quickstart\n\nSee the [CLI README](cli/) for full usage. Quick version:\n\n```bash\ncargo build -p cli --release\n\nqarax configure --server http://localhost:8000\nqarax host list\nqarax vm list\n```\n\n## Host provisioning\n\nqarax uses bootc (bootable containers) to deploy hypervisor hosts. The appliance image includes qarax-node, Cloud Hypervisor, and all dependencies.\n\n```bash\n# Register the host\nqarax host add --name node-01 --address 10.0.0.42 --user root\n\n# Build and push the appliance\nmake appliance-build\nmake appliance-push\n\n# Deploy and initialize\nqarax host deploy node-01 --image ghcr.io/yourorg/qarax-vmm-host:latest --ssh-key ~/.ssh/id_ed25519\nqarax host init node-01\n```\n\nSee the [qarax-node README](qarax-node/) for runtime dependencies and configuration.\n\n## VM boot configuration\n\nDefault boot artifacts are configured per environment in `configuration/` (`base.yaml`, `local.yaml`, `production.yaml`), selected by the `APP_ENVIRONMENT` env var (default: `local`):\n\n```yaml\nvm_defaults:\n  kernel: \"/var/lib/qarax/images/vmlinux\"\n  initramfs: \"/var/lib/qarax/images/initramfs.gz\"\n  cmdline: \"console=ttyS0 console=hvc0 root=/dev/vda1\"\n```\n\n## Demos\n\nWorking demo setups in `demos/`:\n\n| Demo | Description |\n|------|-------------|\n| `oci/` | OverlayBD lazy-pull disk workflow |\n| `boot-source/` | Direct kernel + initramfs boot |\n| `hooks/` | Lifecycle webhooks |\n| `etcd-cluster/` | 3-node etcd cluster on VMs |\n| `k8s-cluster/` | 3-node kubeadm Kubernetes cluster |\n| `gpu-passthrough/` | VFIO GPU passthrough |\n| `hyperconverged/` | Single-VM control plane + node |\n| `sandbox/` | Ephemeral auto-reaping VMs |\n| `sse-events/` | Server-Sent Events stream |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqarax%2Fqarax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqarax%2Fqarax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqarax%2Fqarax/lists"}