Volant Plugin Builder
Fledge is the plugin builder, the toolkit for creating the boot artifacts referenced in Volant plugins. It helps to streamline the process of building either an initramfs with your own payload(preferably a static binary), or a rootfs from a Docker image, which also supports injecting your own payload.
The recipe for building your artifact is defined in a fledge.toml file.
There are two kinds of configuration files for Volant plugins: manifest.json and fledge.toml
This guide is focused on the 'fledge.toml' configuration file, as this repository is focused on the stage of building the artifact. If you are looking for the 'manifest.json' configuration file, meaning if you do not intend to build the artifact yourself and only want to install a pre-made plugin, please refer to initramfs-plugin-example(caddy) or oci-plugin-example(nginx)
Let's get started on building the artifact.
# Install
curl -LO https://github.com/volantvm/fledge/releases/latest/download/fledge-linux-amd64
chmod +x fledge-linux-amd64 && sudo mv fledge-linux-amd64 /usr/local/bin/fledgecat > fledge.toml <<'EOF'
version = "1"
strategy = "oci_rootfs"
[agent]
source_strategy = "release"
version = "latest"
[source]
image = "nginx:alpine"
[filesystem]
type = "ext4"
size_buffer_mb = 100
preallocate = false
EOF
sudo fledge build
# → outputs nginx-rootfs.img + nginx.manifest.jsoncat > fledge.toml <<'EOF'
version = "1"
strategy = "oci_rootfs"
[agent]
source_strategy = "release"
version = "latest"
[source]
dockerfile = "./Dockerfile"
context = "." # optional; defaults to Dockerfile's directory
target = "" # optional multi-stage target
build_args = { FOO = "bar" }
[filesystem]
type = "ext4"
size_buffer_mb = 100
preallocate = false
EOF
sudo fledge buildNotes:
source.imageorsource.dockerfilemay be provided (mutually exclusive)build_argsare passed through todocker build- Ephemeral images/tags created during the build are cleaned up automatically
volar plugins install --manifest nginx.manifest.json
volar vms create web --plugin nginxBoots a real VM—networked, isolated, live in seconds.
Fledge now uses an embedded BuildKit solver by default (no external buildkitd). This path is Linux-only and runs build steps inside Cloud Hypervisor microVMs.
Environment variables:
CLOUDHYPERVISOR— path to thecloud-hypervisorbinary (default:cloud-hypervisorin PATH)FLEDGE_KERNEL_BZIMAGE— path to bzImage (default:/var/lib/volant/kernel/bzImage)FLEDGE_KERNEL_VMLINUX— path to vmlinux (used if bzImage not provided; default:/var/lib/volant/kernel/vmlinux)
Switching modes:
- Embedded (default): no env required
- External daemon: set
FLEDGE_BUILDKIT_MODE=daemonand point to your buildkitd viaFLEDGE_BUILDKIT_ADDRif needed
Note: On non-Linux platforms, the embedded path is not available; use the external daemon mode instead.
| Strategy | When to Use | Output | Typical Size |
|---|---|---|---|
| OCI Rootfs | Existing Docker/OCI images | .img + manifest |
50 MB–2 GB |
| Initramfs | Custom apps / stateless services | .cpio.gz + manifest |
5–50 MB |
version = "1"
strategy = "initramfs"
[agent]
source_strategy = "release"
version = "latest"
[source]
# Busybox is optional; defaults to a pinned musl static busybox if omitted
# busybox_url = "https://busybox.net/downloads/binaries/1.35.0-x86_64-linux-musl/busybox"
# busybox_sha256 = "6e123e7f3202a8c1e9b1f94d8941580a25135382b99e8d3e34fb858bba311348"
[mappings]
"./myapp" = "/usr/bin/myapp"sudo fledge build
volar plugins install --manifest myapp.manifest.json
volar vms create demo --plugin myappversion = "1"
strategy = "initramfs"
[agent]
source_strategy = "release"
version = "latest"
[source]
dockerfile = "./Dockerfile"
context = "."
# optional: busybox_url / busybox_sha256 (defaults applied if omitted)
[mappings]
"./myapp" = "/usr/bin/myapp"Notes:
- If
busybox_urlis omitted, a pinned musl-static BusyBox is injected by default - The built image filesystem is overlaid into the initramfs before adding Kestrel/init (Mode 1)
| Section | Example | Purpose |
|---|---|---|
| Top-level | version = "1", strategy = "oci_rootfs" |
Required metadata |
[agent] |
source_strategy = "release", version = "latest" |
Kestrel agent source. Required for oci_rootfs. Used for initramfs default mode (omit [init]). Not allowed with [init] path=... or [init] none=true. |
[source] |
image = "nginx:alpine" or dockerfile = "./Dockerfile" (+ context, target, build_args) for image input; busybox_url/busybox_sha256 optional for initramfs (defaults applied) |
Build input |
[filesystem] |
type = "ext4", size_buffer_mb = 100 |
Required for oci_rootfs |
[init] |
path = "/usr/local/bin/my-init" or none = true |
Initramfs only; choose custom init or no wrapper |
[mappings] |
"local" = "/dest" |
Optional file/directory mappings |
Note on agent requirements:
- OCI Rootfs:
[agent]is required. - Initramfs default (no
[init]): Kestrel is used;[agent]can be specified explicitly or defaulted tosource_strategy = "release",version = "latest". - Initramfs with
[init] path=...or[init] none=true: Do not include[agent](Kestrel is not used).
Fledge supports three init modes for initramfs. See docs/init-modes.md for complete details.
The Ladder of Laziness:
- Default (no
[init]section) — Batteries-included: C init + Kestrel agent (90% of users) - Custom (
[init] path = "..."— C init + your custom init script - No wrapper (
[init] none = true) — Your binary is PID 1 (maximum performance)
Examples:
- Static binaries for initramfs (
CGO_ENABLED=0) - Verify checksums on downloads
- Keep it small (< 100 ms boots)
- Use OCI for heavy dependencies
| Issue | Fix |
|---|---|
must run as root |
sudo fledge build |
Missing skopeo |
sudo apt install skopeo |
| Slow builds | Smaller base images / preallocate=true |
| Loop device errors | sudo modprobe loop then retry |
Business Source License 1.1
- Free for plugin development and evaluation
- Commercial use requires a license
- Converts to Apache 2.0 on Oct 4 2029
See LICENSE for details.
© 2025 HYPR PTE. LTD.