{"id":13474234,"url":"https://github.com/cloud-hypervisor/cloud-hypervisor","last_synced_at":"2026-02-22T23:18:40.211Z","repository":{"id":37271594,"uuid":"184341774","full_name":"cloud-hypervisor/cloud-hypervisor","owner":"cloud-hypervisor","description":"A Virtual Machine Monitor for modern Cloud workloads. Features include CPU, memory and device hotplug, support for running Windows and Linux guests, device offload with vhost-user and a minimal compact footprint. Written in Rust with a strong focus on security.","archived":false,"fork":false,"pushed_at":"2025-05-05T11:29:12.000Z","size":27046,"stargazers_count":4444,"open_issues_count":106,"forks_count":478,"subscribers_count":71,"default_branch":"main","last_synced_at":"2025-05-05T11:46:04.327Z","etag":null,"topics":["cloud-workloads","kvm","rust-vmm","virtualization"],"latest_commit_sha":null,"homepage":"https://www.cloudhypervisor.org","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/cloud-hypervisor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSES/Apache-2.0.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-04-30T22:49:03.000Z","updated_at":"2025-05-05T11:29:15.000Z","dependencies_parsed_at":"2023-02-12T22:00:43.434Z","dependency_job_id":"206abd61-cd55-41e3-bef2-24380ccef9e6","html_url":"https://github.com/cloud-hypervisor/cloud-hypervisor","commit_stats":null,"previous_names":[],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-hypervisor%2Fcloud-hypervisor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-hypervisor%2Fcloud-hypervisor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-hypervisor%2Fcloud-hypervisor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-hypervisor%2Fcloud-hypervisor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloud-hypervisor","download_url":"https://codeload.github.com/cloud-hypervisor/cloud-hypervisor/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254040547,"owners_count":22004564,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cloud-workloads","kvm","rust-vmm","virtualization"],"created_at":"2024-07-31T16:01:10.578Z","updated_at":"2026-02-20T02:14:21.878Z","avatar_url":"https://github.com/cloud-hypervisor.png","language":"Rust","readme":"- [1. What is Cloud Hypervisor?](#1-what-is-cloud-hypervisor)\n  - [Objectives](#objectives)\n    - [High Level](#high-level)\n    - [Architectures](#architectures)\n    - [Guest OS](#guest-os)\n- [2. Getting Started](#2-getting-started)\n  - [Host OS](#host-os)\n  - [Use Pre-built Binaries](#use-pre-built-binaries)\n  - [Packages](#packages)\n  - [Building from Source](#building-from-source)\n  - [Booting Linux](#booting-linux)\n    - [Firmware Booting](#firmware-booting)\n    - [Custom Kernel and Disk Image](#custom-kernel-and-disk-image)\n      - [Building your Kernel](#building-your-kernel)\n      - [Disk image](#disk-image)\n      - [Booting the guest VM](#booting-the-guest-vm)\n- [3. Status](#3-status)\n  - [Hot Plug](#hot-plug)\n  - [Device Model](#device-model)\n  - [Roadmap](#roadmap)\n- [4. Relationship with _Rust VMM_ Project](#4-relationship-with-rust-vmm-project)\n  - [Differences with Firecracker and crosvm](#differences-with-firecracker-and-crosvm)\n- [5. Community](#5-community)\n  - [Contribute](#contribute)\n  - [Slack](#slack)\n  - [Mailing list](#mailing-list)\n  - [Security issues](#security-issues)\n\n# 1. What is Cloud Hypervisor?\n\nCloud Hypervisor is an open source Virtual Machine Monitor (VMM) that runs on\ntop of the [KVM](https://www.kernel.org/doc/Documentation/virtual/kvm/api.txt)\nhypervisor and the Microsoft Hypervisor (MSHV).\n\nThe project focuses on running modern, _Cloud Workloads_, on specific, common,\nhardware architectures. In this case _Cloud Workloads_ refers to those that are\nrun by customers inside a Cloud Service Provider. This means modern operating\nsystems with most I/O handled by\nparavirtualised devices (e.g. _virtio_), no requirement for legacy devices, and\n64-bit CPUs.\n\nCloud Hypervisor is implemented in [Rust](https://www.rust-lang.org/) and is\nbased on the [Rust VMM](https://github.com/rust-vmm) crates.\n\n## Objectives\n\n### High Level\n\n- Runs on KVM or MSHV\n- Minimal emulation\n- Low latency\n- Low memory footprint\n- Low complexity\n- High performance\n- Small attack surface\n- 64-bit support only\n- CPU, memory, PCI hotplug\n- Machine to machine migration\n\n### Architectures\n\nCloud Hypervisor supports the `x86-64`, `AArch64` and `riscv64`\narchitectures, with functionality varying across these platforms. The\nfunctionality differences between `x86-64` and `AArch64` are documented\nin [#1125](https://github.com/cloud-hypervisor/cloud-hypervisor/issues/1125).\nThe `riscv64` architecture support is experimental and offers limited\nfunctionality. For more details and instructions, please refer to [riscv\ndocumentation](docs/riscv.md).\n\n### Guest OS\n\nCloud Hypervisor supports `64-bit Linux` and Windows 10/Windows Server 2019.\n\n# 2. Getting Started\n\nThe following sections describe how to build and run Cloud Hypervisor.\n\n## Prerequisites for AArch64\n\n- AArch64 servers (recommended) or development boards equipped with the GICv3\n  interrupt controller.\n\n## Host OS\n\nFor required KVM functionality and adequate performance the recommended host\nkernel version is 5.13. The majority of the CI currently tests with kernel\nversion 5.15.\n\n## Use Pre-built Binaries\n\nThe recommended approach to getting started with Cloud Hypervisor is by using a\npre-built binary. Binaries are available for the [latest\nrelease](https://github.com/cloud-hypervisor/cloud-hypervisor/releases/latest).\nUse `cloud-hypervisor-static` for `x86-64` or `cloud-hypervisor-static-aarch64`\nfor `AArch64` platform.\n\n## Packages\n\nFor convenience, packages are also available targeting some popular Linux\ndistributions. This is thanks to the [Open Build\nService](https://build.opensuse.org). The [OBS\nREADME](https://github.com/cloud-hypervisor/obs-packaging) explains how to\nenable the repository in a supported Linux distribution and install Cloud Hypervisor\nand accompanying packages. Please report any packaging issues in the\n[obs-packaging](https://github.com/cloud-hypervisor/obs-packaging) repository.\n\n## Building from Source\n\nPlease see the [instructions for building from source](docs/building.md) if you\ndo not wish to use the pre-built binaries.\n\n## Booting Linux\n\nCloud Hypervisor supports direct kernel boot (the x86-64 kernel requires the kernel\nbuilt with PVH support or a bzImage) or booting via a firmware (either [Rust Hypervisor\nFirmware](https://github.com/cloud-hypervisor/rust-hypervisor-firmware) or an\nedk2 UEFI firmware called `CLOUDHV` / `CLOUDHV_EFI`.)\n\nBinary builds of the firmware files are available for the latest release of\n[Rust Hypervisor\nFirmware](https://github.com/cloud-hypervisor/rust-hypervisor-firmware/releases/latest)\nand [our edk2\nrepository](https://github.com/cloud-hypervisor/edk2/releases/latest)\n\nThe choice of firmware depends on your guest OS choice; some experimentation\nmay be required.\n\n### Firmware Booting\n\nCloud Hypervisor supports booting disk images containing all needed components\nto run cloud workloads, a.k.a. cloud images.\n\nThe following sample commands will download an Ubuntu Cloud image, converting\nit into a format that Cloud Hypervisor can use and a firmware to boot the image\nwith.\n\n```shell\n$ wget https://cloud-images.ubuntu.com/focal/current/focal-server-cloudimg-amd64.img\n$ qemu-img convert -p -f qcow2 -O raw focal-server-cloudimg-amd64.img focal-server-cloudimg-amd64.raw\n$ wget https://github.com/cloud-hypervisor/rust-hypervisor-firmware/releases/download/0.4.2/hypervisor-fw\n```\n\nThe Ubuntu cloud images do not ship with a default password so it necessary to\nuse a `cloud-init` disk image to customise the image on the first boot. A basic\n`cloud-init` image is generated by this [script](scripts/create-cloud-init.sh).\nThis seeds the image with a default username/password of `cloud/cloud123`. It\nis only necessary to add this disk image on the first boot. Script also assigns\ndefault IP address using `test_data/cloud-init/ubuntu/local/network-config` details\nwith `--net \"mac=12:34:56:78:90:ab,tap=\"` option. Then the matching mac address\ninterface will be enabled as per `network-config` details.\n\n```shell\n$ sudo setcap cap_net_admin+ep ./cloud-hypervisor\n$ ./create-cloud-init.sh\n$ ./cloud-hypervisor \\\n\t--firmware ./hypervisor-fw \\\n\t--disk path=focal-server-cloudimg-amd64.raw path=/tmp/ubuntu-cloudinit.img \\\n\t--cpus boot=4 \\\n\t--memory size=1024M \\\n\t--net \"tap=,mac=,ip=,mask=\"\n```\n\nIf access to the firmware messages or interaction with the boot loader (e.g.\nGRUB) is required then it necessary to switch to the serial console instead of\n`virtio-console`.\n\n```shell\n$ ./cloud-hypervisor \\\n\t--kernel ./hypervisor-fw \\\n\t--disk path=focal-server-cloudimg-amd64.raw path=/tmp/ubuntu-cloudinit.img \\\n\t--cpus boot=4 \\\n\t--memory size=1024M \\\n\t--net \"tap=,mac=,ip=,mask=\" \\\n\t--serial tty \\\n\t--console off\n```\n\n## Booting: `--firmware` vs `--kernel`\n\nThe following scenarios are supported by Cloud Hypervisor to bootstrap a VM, i.e.,\nto load a payload/bootitem(s):\n\n- Provide firmware\n- Provide kernel \\[+ cmdline\\]\\ [+ initrd\\]\n\nPlease note that our Cloud Hypervisor firmware (`hypervisor-fw`) has a Xen PVH\nboot entry, therefore it can also be booted via the `--kernel` parameter, as \nseen in some examples.\n\n### Custom Kernel and Disk Image\n\n#### Building your Kernel\n\nCloud Hypervisor also supports direct kernel boot. For x86-64, a `vmlinux` ELF kernel (compiled with PVH support) or a regular bzImage are supported. In order to support development there is a custom branch; however provided the required options are enabled any recent kernel will suffice.\n\nTo build the kernel:\n\n```shell\n# Clone the Cloud Hypervisor Linux branch\n$ git clone --depth 1 https://github.com/cloud-hypervisor/linux.git -b ch-6.12.8 linux-cloud-hypervisor\n$ pushd linux-cloud-hypervisor\n$ make ch_defconfig\n# Do native build of the x86-64 kernel\n$ KCFLAGS=\"-Wa,-mx86-used-note=no\" make bzImage -j `nproc`\n# Do native build of the AArch64 kernel\n$ make -j `nproc`\n$ popd\n```\n\nFor x86-64, the `vmlinux` kernel image will then be located at\n`linux-cloud-hypervisor/arch/x86/boot/compressed/vmlinux.bin`.\nFor AArch64, the `Image` kernel image will then be located at\n`linux-cloud-hypervisor/arch/arm64/boot/Image`.\n\n#### Disk image\n\nFor the disk image the same Ubuntu image as before can be used. This contains\nan `ext4` root filesystem.\n\n```shell\n$ wget https://cloud-images.ubuntu.com/focal/current/focal-server-cloudimg-amd64.img # x86-64\n$ wget https://cloud-images.ubuntu.com/focal/current/focal-server-cloudimg-arm64.img # AArch64\n$ qemu-img convert -p -f qcow2 -O raw focal-server-cloudimg-amd64.img focal-server-cloudimg-amd64.raw # x86-64\n$ qemu-img convert -p -f qcow2 -O raw focal-server-cloudimg-arm64.img focal-server-cloudimg-arm64.raw # AArch64\n```\n\n#### Booting the guest VM\n\nThese sample commands boot the disk image using the custom kernel whilst also\nsupplying the desired kernel command line.\n\n- x86-64\n\n```shell\n$ sudo setcap cap_net_admin+ep ./cloud-hypervisor\n$ ./create-cloud-init.sh\n$ ./cloud-hypervisor \\\n\t--kernel ./linux-cloud-hypervisor/arch/x86/boot/compressed/vmlinux.bin \\\n\t--disk path=focal-server-cloudimg-amd64.raw path=/tmp/ubuntu-cloudinit.img \\\n\t--cmdline \"console=hvc0 root=/dev/vda1 rw\" \\\n\t--cpus boot=4 \\\n\t--memory size=1024M \\\n\t--net \"tap=,mac=,ip=,mask=\"\n```\n\n- AArch64\n\n```shell\n$ sudo setcap cap_net_admin+ep ./cloud-hypervisor\n$ ./create-cloud-init.sh\n$ ./cloud-hypervisor \\\n\t--kernel ./linux-cloud-hypervisor/arch/arm64/boot/Image \\\n\t--disk path=focal-server-cloudimg-arm64.raw path=/tmp/ubuntu-cloudinit.img \\\n\t--cmdline \"console=hvc0 root=/dev/vda1 rw\" \\\n\t--cpus boot=4 \\\n\t--memory size=1024M \\\n\t--net \"tap=,mac=,ip=,mask=\"\n```\n\nIf earlier kernel messages are required the serial console should be used instead of `virtio-console`.\n\n- x86-64\n\n```shell\n$ ./cloud-hypervisor \\\n\t--kernel ./linux-cloud-hypervisor/arch/x86/boot/compressed/vmlinux.bin \\\n\t--console off \\\n\t--serial tty \\\n\t--disk path=focal-server-cloudimg-amd64.raw \\\n\t--cmdline \"console=ttyS0 root=/dev/vda1 rw\" \\\n\t--cpus boot=4 \\\n\t--memory size=1024M \\\n\t--net \"tap=,mac=,ip=,mask=\"\n```\n\n- AArch64\n\n```shell\n$ ./cloud-hypervisor \\\n\t--kernel ./linux-cloud-hypervisor/arch/arm64/boot/Image \\\n\t--console off \\\n\t--serial tty \\\n\t--disk path=focal-server-cloudimg-arm64.raw \\\n\t--cmdline \"console=ttyAMA0 root=/dev/vda1 rw\" \\\n\t--cpus boot=4 \\\n\t--memory size=1024M \\\n\t--net \"tap=,mac=,ip=,mask=\"\n```\n\n# 3. Status\n\nCloud Hypervisor is under active development. The following stability\nguarantees are currently made:\n\n* The API (including command line options) will not be removed or changed in a\n  breaking way without a minimum of 2 major releases notice. Where possible\n  warnings will be given about the use of deprecated functionality and the\n  deprecations will be documented in the release notes.\n\n* Point releases will be made between individual releases where there are\n  substantial bug fixes or security issues that need to be fixed. These point\n  releases will only include bug fixes.\n\nCurrently the following items are **not** guaranteed across updates:\n\n* Snapshot/restore is not supported across different versions\n* Live migration is not supported across different versions\n* The following features are considered experimental and may change\n  substantially between releases: TDX, vfio-user, vDPA.\n\nFurther details can be found in the [release documentation](docs/releases.md).\n\nAs of 2023-01-03, the following cloud images are supported:\n\n- [Ubuntu Focal](https://cloud-images.ubuntu.com/focal/current/) (focal-server-cloudimg-{amd64,arm64}.img)\n- [Ubuntu Jammy](https://cloud-images.ubuntu.com/jammy/current/) (jammy-server-cloudimg-{amd64,arm64}.img)\n- [Ubuntu Noble](https://cloud-images.ubuntu.com/noble/current/) (noble-server-cloudimg-{amd64,arm64}.img)\n- [Fedora 36](https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/36/Cloud/) ([Fedora-Cloud-Base-36-1.5.x86_64.raw.xz](https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/36/Cloud/x86_64/images/) / [Fedora-Cloud-Base-36-1.5.aarch64.raw.xz](https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/36/Cloud/aarch64/images/))\n\nDirect kernel boot to userspace should work with a rootfs from most\ndistributions although you may need to enable exotic filesystem types in the\nreference kernel configuration (e.g. XFS or btrfs.)\n\n## Hot Plug\n\nCloud Hypervisor supports hotplug of CPUs, passthrough devices (VFIO),\n`virtio-{net,block,pmem,fs,vsock}` and memory resizing. This\n[document](docs/hotplug.md) details how to add devices to a running VM.\n\n## Device Model\n\nDetails of the device model can be found in this\n[documentation](docs/device_model.md).\n\n## Roadmap\n\nThe project roadmap is tracked through a [GitHub\nproject](https://github.com/orgs/cloud-hypervisor/projects/6).\n\n# 4. Relationship with _Rust VMM_ Project\n\nIn order to satisfy the design goal of having a high-performance,\nsecurity-focused hypervisor the decision was made to use the\n[Rust](https://www.rust-lang.org/) programming language. The language's strong\nfocus on memory and thread safety makes it an ideal candidate for implementing\nVMMs.\n\nInstead of implementing the VMM components from scratch, Cloud Hypervisor is\nimporting the [Rust VMM](https://github.com/rust-vmm) crates, and sharing code\nand architecture together with other VMMs like e.g. Amazon's\n[Firecracker](https://firecracker-microvm.github.io/) and Google's\n[crosvm](https://chromium.googlesource.com/chromiumos/platform/crosvm/).\n\nCloud Hypervisor embraces the _Rust VMM_ project's goals, which is to be able\nto share and re-use as many virtualization crates as possible.\n\n## Differences with Firecracker and crosvm\n\nA large part of the Cloud Hypervisor code is based on either the Firecracker or\nthe crosvm project's implementations. Both of these are VMMs written in Rust\nwith a focus on safety and security, like Cloud Hypervisor.\n\nThe goal of the Cloud Hypervisor project differs from the aforementioned\nprojects in that it aims to be a general purpose VMM for _Cloud Workloads_ and\nnot limited to container/serverless or client workloads.\n\nThe Cloud Hypervisor community thanks the communities of both the Firecracker\nand crosvm projects for their excellent work.\n\n# 5. Community\n\nThe Cloud Hypervisor project follows the governance, and community guidelines\ndescribed in the [Community](https://github.com/cloud-hypervisor/community)\nrepository.\n\n## Contribute\n\nThe project strongly believes in building a global, diverse and collaborative\ncommunity around the Cloud Hypervisor project. Anyone who is interested in\n[contributing](CONTRIBUTING.md) to the project is welcome to participate.\n\nContributing to a open source project like Cloud Hypervisor covers a lot more\nthan just sending code. Testing, documentation, pull request\nreviews, bug reports, feature requests, project improvement suggestions, etc,\nare all equal and welcome means of contribution. See the\n[CONTRIBUTING](CONTRIBUTING.md) document for more details.\n\n## Slack\n\nGet an [invite to our Slack channel](https://join.slack.com/t/cloud-hypervisor/shared_invite/enQtNjY3MTE3MDkwNDQ4LWQ1MTA1ZDVmODkwMWQ1MTRhYzk4ZGNlN2UwNTI3ZmFlODU0OTcwOWZjMTkwZDExYWE3YjFmNzgzY2FmNDAyMjI),\n [join us on Slack](https://cloud-hypervisor.slack.com/), and [participate in our community activities](https://cloud-hypervisor.slack.com/archives/C04R5DUQVBN).\n\n## Mailing list\n\nPlease report bugs using the [GitHub issue\ntracker](https://github.com/cloud-hypervisor/cloud-hypervisor/issues) but for\nbroader community discussions you may use our [mailing\nlist](https://lists.cloudhypervisor.org/g/dev/).\n\n## Security issues\n\nPlease contact the maintainers listed in the MAINTAINERS.md file with security issues.\n","funding_links":[],"categories":["Research Projects","Rust","Install from Source","others","Other Linear Topics","OpenCL Tools, Libraries and Frameworks","Open Source Virtualization","Fabrics","Projects","DevOps Tools","Virtualization","Tools","Interfaces"],"sub_categories":["AMD","Virtualization","viii. Linear Regression","Inactive projects","Security","Winetricks","Objective-C Tools, Libraries, and Frameworks"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-hypervisor%2Fcloud-hypervisor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloud-hypervisor%2Fcloud-hypervisor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-hypervisor%2Fcloud-hypervisor/lists"}