CRUN-VM(1)

💖 CRUN-VM 💖

okay bestie, welcome to the crun-vm(1) manual — General Commands Manual edition, and yes she's a whole icon. this is the page for crun-vm: an OCI Runtime that runs VM images. no cap. let's get into it 🫶

---

✨ NAME ✨

crun-vm — an OCI Runtime that runs VM images 🦋

---

✨ SYNOPSIS ✨

podman|docker create|run --runtime crun-vm [engine_opts...] image_ref
[""] [crun_vm_opts...]
podman|docker exec [engine_opts...] [crun_vm_opts...] cmd_and_args...|""

---

✨ DESCRIPTION ✨

so crun-vm is an OCI Runtime that lets Podman, Docker, and Kubernetes run QEMU-compatible Virtual Machine (VM) images. like, actual VMs. living inside your container workflow. it's giving main character energy fr fr 💅

this man page enumerates all the crun-vm specific options you can use with Podman/Docker engine commands like podman create and docker run, and it also shows you how to slot them in next to the standard engine options. for extra guides, go visit https://github.com/containers/crun-vm — iykyk ✨

---

🌸 QUICK START 🌸

launch a VM from a "containerdisk" (that's a disk image packaged in a container, bestie):

$ podman run --runtime crun-vm -it quay.io/containerdisks/fedora:40

launch a VM from a disk image under my-image-dir/:

$ podman run --runtime crun-vm -it --rootfs my-image-dir/

launch a VM from a bootable container (https://containers.github.io/bootable/):

$ podman run --runtime crun-vm -it quay.io/crun-vm/example-fedora-bootc:40

set the password for a VM's default user:

$ podman run --runtime crun-vm -it quay.io/containerdisks/fedora:40 \
    --password pass  # for user "fedora"

exec (ssh) into a VM:

$ podman exec -it --latest -- --as fedora

obsessed. moving on 💖

---

🎀 CREATE/RUN USAGE 🎀

podman|docker create|run --runtime crun-vm [engine_opts...] image_ref
[""] [crun_vm_opts...]

standard engine options go in engine_opts. periodt.

image_ref identifies a container image of one of the following kinds:

1. a "containerdisk", i.e., a container image with a sole VM image file residing under / or /disk/, such as quay.io/containerdisks/fedora:40;
2. the Podman-specific --rootfs option pointing at a directory containing a sole VM image file;
3. a bootc bootable container, such as quay.io/crun-vm/example-fedora-bootc:40 (see https://containers.github.io/bootable/ for more information).

the crun-vm specific options go in crun_vm_opts — that's the spot where the command to execute in the container would usually be specified. and like, that whole notion just doesn't apply to VMs the way it does to regular containers, so no command should be specified here. HOWEVER 🚨 if you're using Docker and the container you specified defines no default entrypoint, you have to also pass in an empty "" argument to satisfy Docker's syntax. she's picky like that 💀

---

💅 CREATE/RUN OPTIONS 💅

all the crun-vm specific options that may be passed to podman|docker create|run commands are listed right here, bestie. every single one.

🌈 these options configure the VM's environment 🌈

• --blockdev source=src_path,target=tgt_path,format=fmt_name — expose the file or block device src_path at path tgt_path in the VM. src_path and tgt_path must be absolute paths. fmt_name specifies the QEMU-compatible image format of src_path, such as raw or qcow2. when format=raw, the same effect can be achieved with the standard -m/--mount/-v/--volume Podman/Docker options. iconic ✨
• --persistent — when using podman|docker create|run with the standard --rootfs option, this flag causes writes made by the VM to its disk to be persisted in the user's image file. make sure that the image is never simultaneously used by another process or VM, otherwise data corruption may occur 😭
• --bootc-disk-size disk_size[KMGT] — set the disk size of the VM image generated from a bootc bootable container. the default is twice the size of the container image.
• --emulated — emulate the VM in software rather than using KVM for hardware-assisted virtualization. it's not currently possible to use this flag when the container image is a bootc bootable container. noted 📝

🦋 these options control the VM's first-boot customization 🦋

• --password plaintext — set the password of the VM image's default user. only works when the VM supports cloud-init.
• --cloud-init config_dir — expose the given cloud-init configuration to the VM. config_dir must be an absolute path.
• --ignition config_file — expose the given Ignition configuration to the VM. config_dir must be an absolute path.
• --random-ssh-key-pair — by default, when using podman-exec, the host user's ssh key pair (if any) is used to ssh into the VM. this is useful when the VM isn't easily customizable at first boot but already authorizes the user's public key. otherwise, or if this flag is specified, a new random key pair is always used. 🔑

🧚 these options are mostly helpful when debugging crun-vm itself 🧚

• --merge-libvirt-xml xml_path — merge the given XML file into the libvirt domain XML generated by crun-vm, prior to using it to launch the VM. xml_path must be an absolute path.
• --print-libvirt-xml — print the libvirt domain XML that would be used to launch the VM, and exit without launching the VM.
• --print-config-json — print the OCI Runtime config.json file with crun-vm's modifications that was passed to crun(1), and exit without launching the VM.

---

🌟 EXEC USAGE 🌟

podman|docker exec [engine_opts...] [--] [crun_vm_opts...]
cmd_and_args...|""

standard engine arguments and options go in engine_opts.

the crun-vm specific options go in crun_vm_opts — i.e., as a prefix to the command to be executed. to launch a login shell, pass "" as the command. cute, right? 🐚

when using Podman's --latest flag instead of providing a container name or ID, you may need pass in -- to delimit standard options from crun-vm specific options. yes, you may need to pass in it. we said what we said 💀

---

⭐ EXEC OPTIONS ⭐

options that may be used with podman|docker exec as a prefix to the actual command to run, if any:

• --as user_name — the user to ssh into the VM as. defaults to root.
• --timeout max_secs — the timeout, in seconds, to apply to a podman|docker run command. defaults to the value of the CRUN_VM_EXEC_TIMEOUT environment variable if set, or 0 otherwise, which means no timeout. ⏰

and these options are mostly helpful when debugging crun-vm itself:

• --container — exec into the container where the VM hypervisor is running, instead of ssh'ing into the actual VM. incompatible with --as. pick one, bestie 🙈

---

💜 ENVIRONMENT 💜

• CRUN_VM_EXEC_TIMEOUT — the timeout, in seconds, to apply to a podman|docker exec command. defaults to 0, which means no timeout. is overridden by --timeout.

---

ok that's the whole page, no notes, you ate this 🫶 go launch a VM, you got this fr fr 💖

and a lil sign-off from the source: this page came out with the manual name crun-vm, page 1, and it's dated July 2025. slay 💅✨🌈