# Virtual Machines (KVM) **Page:** foundation/servers/virtual-machines [Download Raw Markdown](./foundation/servers/virtual-machines.md) --- # Virtual Machines (KVM) **Run full, hardware-accelerated virtual machines inside your container - your own kernel, your own operating system, on your own bare metal.** Hoody containers are fast and lightweight, but sometimes you need a *full* virtual machine: a different kernel, a different operating system, or a workload that expects real VM hardware. On rented and dedicated servers you can enable **KVM passthrough** and run QEMU/KVM virtual machines directly inside your container, using the host CPU's hardware virtualization extensions. KVM is a capability of **rented and dedicated (bare-metal) servers only**. It is **not** available on the free tier. It is **off by default** on every container - a capability you turn on, never something enabled behind your back. ## What you can do with it Boot a Linux distribution, a BSD, or other x86-64 OS images as a QEMU/KVM guest inside your container. Run workloads that expect a real VM - test kernels and kernel modules, or run VM-based CI. Need a kernel version or configuration the host does not provide? Boot your own inside a VM. KVM uses the CPU's VT-x / AMD-V extensions, so guests run at near-native CPU performance - not slow emulation. ## Enable KVM on a container 1. **Use a rented or dedicated server.** Free-tier containers cannot enable KVM. If you do not have one yet, [rent a server](/foundation/servers/rent/). 2. **Enable `kvm` for the container.** It is a simple true/false setting, off by default. The canonical name is `kvm`; `dev_kvm` is accepted as an alias. You can turn it on **at creation** - pass `kvm: true` in the create request (or `--kvm` on the CLI) - or **later, on a stopped container**, with the dedicated toggle endpoint: ```http PUT /api/v1/containers/{id}/kvm { "kvm": true } ``` The container **must be stopped** to change this setting - the toggle is rejected on a running container. (Creating with `kvm: true` handles this for you.) 3. **Start the container.** The `/dev/kvm` grant is applied when the container starts. 4. **Verify `/dev/kvm` is present inside the container:** ```bash ls -l /dev/kvm # crw-rw-rw- 1 root root 10, 232 ... - a character device, major:minor 10,232, mode 0666 ``` The node is world-readable/writable (mode `0666`), so you can run QEMU as a **non-root** user inside the container. To turn it back off, stop the container, set `kvm` to `false` (same endpoint), and start it again. The device is removed and the container returns to a standard, VM-free state. If you use a scoped API token instead of the dashboard, it needs the `containers.features.kvm` permission to enable KVM - without it the request is refused with a 403. The `full_access` and `dev_team` token templates include it. ## Copying a container with KVM When you [copy a container](/foundation/servers/), KVM is a **fresh decision for the copy** - the grant never transfers from the source. A copy of a KVM container starts **KVM-off** unless you ask for it, and a copy of an ordinary container can be granted KVM on the spot. This keeps the copy's capability tied to *its own* server, not the original's. To grant the copy `/dev/kvm`, pass `kvm: true` on the copy request (or `--kvm` on the CLI copy): ```http POST /api/v1/containers/{id}/copy { "target_project_id": "...", "kvm": true } ``` The same rules apply to the copy as to any other container: the **target** must be a rented or dedicated server (never the free tier, or the copy is refused with a 403), and a scoped token needs the `containers.features.kvm` permission. The copy's `/dev/kvm` is attached before it first starts, exactly as with a fresh container. ## Run your first VM With `/dev/kvm` available, any KVM-based tool works. A minimal check with QEMU (Debian/Ubuntu example): ```bash # install QEMU inside the container apt-get update && apt-get install -y qemu-system-x86 # boot a guest with KVM acceleration qemu-system-x86_64 -enable-kvm -m 2048 -cdrom your-os.iso ``` If `-enable-kvm` is accepted, you are running a hardware-accelerated virtual machine inside your container. A guest's resources come out of your container's own CPU, memory and disk limits. Give the container enough headroom for both itself and the VM you intend to run. ## Security Enabling KVM means **you** run a hypervisor (QEMU) inside **your** container, on **your** rented or dedicated hardware - no stranger's workload shares your machine, only people you invite. This is different from a shared, multi-tenant hypervisor. Hoody's platform still runs no shared hypervisor for you to escape; you are simply opting in to running your own virtual machines in your own isolated space. Because that isolation boundary matters, KVM is offered only on rented and dedicated servers, never on the shared free tier. For more on how Hoody isolates workloads, see [platform security](/concepts/security/). To get a server that supports KVM, see [renting servers](/foundation/servers/rent/).