Download Latest Version
v0.5.3 source code.zip (1.6 MB)
Get an email when there's a new version of forkd
| Name | Modified | Size | Downloads / Week |
|---|---|---|---|
| Parent folder | |||
| forkd-v0.5.1-x86_64-linux.tar.gz | 2026-06-05 | 7.0 MB | |
| SHA256SUMS | 2026-06-05 | 99 Bytes | |
| README.md | 2026-06-05 | 3.9 kB | |
| v0.5.1 -- guest kernel rebuild closes #218 + #225 source code.tar.gz | 2026-06-05 | 1.3 MB | |
| v0.5.1 -- guest kernel rebuild closes #218 + #225 source code.zip | 2026-06-05 | 1.4 MB | |
| Totals: 5 Items | 9.7 MB | 0 | |
v0.5.1 is a bug-fix release that finally makes pip install (and anything else that hits OpenSSL) work inside forkd guests.
The bug
Pre-v0.5.1 forkd shipped a Linux 4.14.174 guest kernel built 2021-07-14. That kernel lacked every entropy modernization since:
| Feature | Available since | 4.14.174 |
|---|---|---|
CONFIG_HW_RANDOM_VIRTIO (virtio-rng driver) |
— | not built in |
CONFIG_RANDOM_TRUST_CPU (RDRAND credit-init) |
— | not set |
random.trust_cpu= cmdline option |
Linux 4.19 | silently ignored |
CONFIG_VMGENID (FC-fork CRNG reseed) |
Linux 5.20 | absent |
Net effect: getrandom(2) blocked forever after FC restore, since the CRNG never marked itself initialized. Any guest workload that touched OpenSSL — pip install, urllib.request HTTPS, requests — hung indefinitely. Tracked in #218 (symptom) + #225 (root cause).
The fix
Swap to Firecracker's CI-blessed Linux 6.1.141 vmlinux. SHA-256 pinned: b36a4a1b10f33b9cfdcde3d1a787d9c090556a3edb211cd06d1f3f9a6c7e8724. End-to-end verified on the dev box on 2026-06-05:
| before | after | |
|---|---|---|
uname -r |
4.14.174 | 6.1.141 |
/dev/hwrng |
absent | crw, virtio-rng |
getrandom(GRND_NONBLOCK) |
EAGAIN | 16 bytes, errno=0 |
ssl.create_default_context() |
∞ | 0.01 s |
urllib.urlopen("https://pypi.org/…") |
∞ | 200, 0.25 s |
pip install numpy==2.0.2 |
exit 1, empty output | 21 s, exit 0 |
| VMGENID after restore | n/a | dmesg: random: crng reseeded due to virtual machine fork ✓ |
Two new helper scripts
scripts/install-guest-kernel.sh— downloads the FC CI vmlinux into/var/lib/forkd/kernels/vmlinux. SHA-256 pinned. Default path — recommended for almost everyone:sh sudo ./scripts/install-guest-kernel.shscripts/build-guest-kernel.sh— clones Linux 6.1 LTS, applies FC's reference microvm config (auto-asserts the entropy options), builds vmlinux from source. ~10 min on a 20-core box. For users who want to audit / tune the kernel config or target a non-x86_64 architecture.
forkd doctor's "kernel image" check now suggests these scripts when no vmlinux is found.
Migration
Existing snapshot vmstates from 4.14 restore fine on 6.1 — they just don't gain the new entropy device until they're re-baked. Run forkd from-image <image> --tag <tag> for each snapshot you care about to pick up CRNG init + /dev/hwrng + VMGENID.
Diff vs v0.5.0
- #224 — wire virtio-rng +
random.trust_cpu=on(forward-prep) - #226 — replace 4.14 guest vmlinux with Linux 6.1.141 (the actual fix)
- #227 — workspace version bump + CHANGELOG header
What this unlocks
The v0.5 chain story can now be demoed for real:
:::sh
forkd snapshot-diff --from py-base --tag py-numpy --exec "pip install numpy"
forkd snapshot-diff --from py-numpy --tag py-pandas --exec "pip install pandas"
forkd snapshot-diff --from py-pandas --tag py-sklearn --exec "pip install scikit-learn"
forkd fork --tag py-sklearn -n 1 # walks the chain transparently
Previously this hung at "Collecting numpy" forever. v0.5.1 runs to completion.
What's Changed
- feat(vmm): forward-prep for [#218] — virtio-rng + random.trust_cpu=on by @WaylandYang in https://github.com/deeplethe/forkd/pull/224
- fix(kernel): swap 4.14 guest vmlinux → Linux 6.1.141 — closes [#218] + [#225] by @WaylandYang in https://github.com/deeplethe/forkd/pull/226
- release: v0.5.1 — guest kernel rebuild + pip-install demo unblocked by @WaylandYang in https://github.com/deeplethe/forkd/pull/227
Full Changelog: https://github.com/deeplethe/forkd/compare/v0.5.0...v0.5.1