KRAFT-RUN(1)

📦
version 0.12.16 · 2 versions
, in nixpkgs unstable

💅 kraft-run — run a unikernel, bestie

okay so real talk, this page lives in the KraftKit CLI manual (that's the manual-name flex, section 1 energy), and it's about one single command: kraft-run. buckle up 🎀

✨ NAME ✨

kraft-run — run a unikernel 🦋

🌸 SYNOPSIS 🌸

kraft run [FLAGS] PROJECT|PACKAGE|BINARY -- [APP ARGS]

literally the whole vibe in one line, no cap 💅

💜 DESCRIPTION 💜

Run a unikernel virtual machine. that's it, that's the tea 🫖✨

👑 OPTIONS 👑

okay this is the long part, but every single flag is here, i promise, i would never do you like that 🙈

  • -m, --arch="" — set the architecture, bestie. which CPU family are we blessing today 🧚
  • --as="" — force a specific runner. like, you're not asking, you're telling 💀
  • -d, --detach[=false] — run the unikernel in the background, main character energy, it doesn't need you watching 👑
  • -W, --disable-acceleration[=false] — disable acceleration of CPU (usually enables TCG). lowkey slower but sometimes you gotta 🐢
  • -e, --env=[] — set environment variables, in the format key[=value]. so like key alone works, key=value also works, we're flexible 💅
  • -h, --help[=false] — help for run. the classic "help me help you" moment 😭
  • --ip="" — assign the provided IP address, so it actually knows where it lives 🏡
  • -a, --kernel-arg=[] — set additional kernel arguments. little whispers to the kernel, iykyk 🤫
  • -K, --kraftfile="" — set an alternative path of the Kraftfile. for when your Kraftfile isn't where everyone expects it to be, we don't judge 🎀
  • --mac="" — assign the provided MAC address, so your instance has a whole identity ✨
  • -M, --memory="64Mi" — assign memory to the unikernel. units are K/Ki, M/Mi, G/Gi. the default is literally 64Mi, tiny icon 🍓
  • -n, --name="" — name of the instance. give it a name, it deserves one 💖
  • --network=[] — attach instance to the provided network, in the format <network>[:ip[/mask][:gw[:dns0[:dns1[:hostname[:domain]]]]]], e.g. kraft0:172.100.0.2. yes the format is that long. yes it's giving nested brackets. we love her anyway 💀
  • --no-start[=false] — do not start the machine. it exists, it's just ✨resting✨
  • --plat="auto" — set the platform virtual machine monitor driver. default is auto, let the machine decide, she's confident 🌈
  • -p, --port=[] — publish a machine's port(s) to the host, so the outside world can say hi 👋
  • --prefix="" — prefix each log line with the given string. aesthetic logging 🎀
  • --prefix-name[=false] — prefix each log line with the machine name. same energy but it does the naming for you 💅
  • --rm[=false] — automatically remove the unikernel when it shuts down. clean girl aesthetic, no leftovers 🧹
  • --rootfs="" — specify a path to use as root file system (can be volume or initramfs) 🗂️
  • --rootfs-type="cpio" — set the type of the format of the rootfs (cpio/erofs). default's cpio 🍓
  • -r, --runtime="" — set an alternative unikernel runtime 🦋
  • --symbolic[=false] — use the debuggable (symbolic) unikernel. for when you need to see everything 🔍
  • -t, --target="" — explicitly use the defined project target. multi-target projects, come get your girl 🎯
  • -v, --volume=[] — bind a volume to the instance 📦

🔥 EXAMPLES 🔥

this is the part where it all clicks, fr fr 💡

💫 the basics

Run a built target in the current working directory project:

$ kraft run

Run a specific target from a multi-target project at the provided project directory:

$ kraft run -t TARGET path/to/project

🧚 kernel binaries

Run a specific kernel binary:

$ kraft run --arch x86_64 --plat qemu path/to/kernel-x86_64-qemu

Run a specific kernel binary with 1000 megabytes of memory:

$ kraft run --arch x86_64 --plat qemu --memory 1G path/to/kernel-x86_64-qemu

Run a specific kernel binary with 1024 megabytes of memory:

$ kraft run --arch x86_64 --plat qemu --memory 1Gi path/to/kernel-x86_64-qemu
not me pointing out that 1G and 1Gi are different numbers of megabytes. iykyk 👀

🌈 OCI + networking

Run an OCI-compatible unikernel, mapping port 8080 on the host to port 80 in the unikernel:

$ kraft run -p 8080:80 unikraft.org/nginx:latest

Attach the unikernel to an existing network kraft0:

$ kraft run --network kraft0

🫶 binary compatibility

Run a Linux userspace binary in POSIX-/binary-compatibility mode:

$ kraft run a.out

🍓 rootfs things

Supply an initramfs CPIO archive file to the unikernel for its rootfs:

$ kraft run --rootfs ./initramfs.cpio

Supply a path which is dynamically serialized into an initramfs CPIO archive:

$ kraft run --rootfs ./path/to/rootfs

💅 volumes

Mount a bi-directional path from on the host to the unikernel mapped to /dir:

$ kraft run -v ./path/to/dir:/dir

Supply a read-only root file system at / via initramfs CPIO archive and mount a bi-directional volume at /dir:

$ kraft run --rootfs ./initramfs.cpio --volume ./path/to/dir:/dir

⭐ the full flex

Customize the default content directory of the official Unikraft NGINX OCI-compatible unikernel and map port 8080 to localhost:

$ kraft run -v ./path/to/html:/nginx/html -p 8080:80 unikraft.org/nginx:latest

🎀 SEE ALSO 🎀

kraft(1) — go say hi to the parent command, she misses you 💖

🦋 HISTORY 🦋

1-Jan-1980 — Auto generated by KraftKit. iconic date, no notes 💀✨

and that's the whole page!! 🫶 this lil doc came from the KraftKit Documentation, dated Jan 1980, and it's all sitting pretty in the KraftKit CLI(1) manual. go run some unikernels, bestie, you're gonna slay 💅👑✨

📦 where this page comes from