vmexec-run(1)

✨ NAME ✨

okay so bestie, you're on the vmexec-run(1) page in the General Commands Manual, and it's literally about one thing: run a command in a new virtual machine 💅✨

🦋 SYNOPSIS 🦋

vmexec run [-d|--detach] [--rm] [--vmid] [--disable-kvm] [-m|--memory]
[-e|--env] [-w|--workdir] [-v|--volume] [--pmem] [-p|--publish]
[-s|--ssh-timeout] [-i|--interactive] [-t|--tty] [--show-vm-window]
[--pull] [-h|--help] <IMAGE_SOURCE> [ARGS]

🌸 DESCRIPTION 🌸

Run a command in a new virtual machine. that's the whole vibe, no cap 🫶

🎀 OPTIONS 🎀

• -d, --detach — run the virtual machine in the background and print the virtual machine ID 👑
• --rm — remove the virtual machine runtime data after exit 🧹
• --vmid <VMID> — virtual machine identifier. If you don't provide one, a random identifier will be generated ✨
• --disable-kvm — run the virtual machine with TCG instead of KVM. This is mostly useful in environments where KVM is not available. it's gonna be a lot slower, but it might be acceptable in some contexts 😭
• -m, --memory <MEMORY> — memory limit for the virtual machine in GBs. Must be an integer of at least 1. If not provided, all available host memory is used. this mimics the behavior of a normal process outside a virtual machine 💖
• -e, --env <ENV> — set environment variables for the process inside the virtual machine. Can be provided multiple times. Expected format: KEY=VALUE 🌈
• -w, --workdir <WORKDIR> — working directory inside the virtual machine. The default working directory for running binaries within a virtual machine is dependent on the image. most commonly, it'll be /root 🏠
• -v, --volume <VOLUMES> — bind mount a volume into the virtual machine. The source may be a directory or a single file. Can be provided multiple times. Expected format: source:dest[:ro] ro can optionally be provided to mark the mount as read-only. Example: $PWD/src:/mnt:ro 🔥
• --pmem <PMEMS> — mount a virtio-pmem device file into the virtual machine. You might want to do this to bypass the guest page cache. This is important if you're overprovisioning your host (i.e. giving VMs more combined memory than the host actually has) and have a write-heavy workload. For more info, see: https://www.qemu.org/docs/master/system/devices/virtio-pmem.html Can be provided multiple times. Specified as an absolute path inside the VM where the device will be mounted as an ext4 filesystem, and the maximum size in gigabytes. On the host, this will show up as a file inside the VM's state dir. Expected format: dest:<size> Example: /var/lib:20 💾
• -p, --publish <PUBLISHED_PORTS> — publish a port on the virtual machine to the host. Can be provided multiple times. Expected format: [[hostip:][hostport]:]vmport hostip is optional and if not provided, the port will be bound on all host IPs. hostport is optional and if not provided, the same value of vmport will be used for the host port. Currently only IPv4 is supported for hostip 🌐
• -s, --ssh-timeout <SSH_TIMEOUT> [default: 20] — SSH connection timeout. Try for this long (in seconds) to connect to the virtual machine's SSH server ⏳
• -i, --interactive <INTERACTIVE> [default: auto] — make STDIN available to the virtual machine's process. If 'auto', this will try to read from stdin if it is available, and do nothing when stdin is not available. If 'always', this will try to read from stdin and abort when stdin is not available. Possible values:
  • always — forward stdin and fail if it can't be opened
  • never — don't forward stdin
  • auto — forward stdin if it can be opened, otherwise carry on without it 🫶
• -t, --tty <TTY> [default: auto] — allocate a pseudo-TTY for the virtual machine. If 'auto', this will be enabled in case vmexec is run from an interactive terminal. Possible values:
  • always — allocate a pseudo-TTY
  • never — don't allocate a pseudo-TTY
  • auto — allocate a pseudo-TTY if stdout is a terminal 🖥️
• --show-vm-window — show a QEMU window with the virtual machine running in it. This is mostly useful for debugging boot failures 👀
• --pull <PULL> [default: missing] — when to pull a new image. Possible values:
  • missing — use the newest local image and only download one if there is none
  • never — use the newest local image and fail if there is none
  • newer — check for a newer image and download it if there is one 🎁
• -h, --help — Print help (see a summary with '-h') ✨
• <IMAGE_SOURCE> — either an operating system (e.g. archlinux) or a path to an image. Possible OS types: archlinux 🐧
• [ARGS] — Arguments to run in the virtual machine 🚀

💖 cute sign-off: source/version run, manual vmexec-run(1), and the date wasn't printed in the original footer—so I'm not inventing one, bestie ✨💅