microvm-runtime 0.4.0-alpha.1

Firecracker microVM driver for decentralized Tangle operators — pure-Rust primitive, no service, no auth, no business logic.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

[package]
name = "microvm-runtime"
version = "0.4.0-alpha.1"
edition = "2024"
rust-version = "1.91"
description = "Firecracker microVM driver for decentralized Tangle operators — pure-Rust primitive, no service, no auth, no business logic."
license = "Unlicense"
repository = "https://github.com/tangle-network/microvm-runtime"
homepage = "https://github.com/tangle-network/microvm-runtime"
documentation = "https://docs.rs/microvm-runtime"
readme = "README.md"
keywords = ["firecracker", "microvm", "vmm", "tangle", "sandbox"]
categories = ["virtualization", "os::linux-apis"]

[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"
thiserror = "2"
# Used by the `firecracker` feature for:
# - jailer: `fs` (mknod) and `user` (chown).
# - uffd:   `socket` (recvmsg + SCM_RIGHTS) and `uio` (IoSliceMut for cmsg recv).
nix = { version = "0.30", default-features = false, features = ["fs", "user", "socket", "uio"], optional = true }
# Streaming SHA-256 for the rootfs catalog + snapshot integrity helpers.
# `sha2` is the de-facto Rust SHA-2 crate (also the RustCrypto reference impl);
# selecting it specifically (over `ring`/`openssl`) keeps the supply-chain
# surface to a single pure-Rust crate with no C dependencies, no FFI, and a
# stable 0.10 line that has not had a security advisory in years.
sha2 = { version = "0.10", default-features = false, optional = true }
# `base64` is used by the `guest_metadata` module to encode raw secret bytes
# onto the newline-delimited JSON wire format that talks to the in-guest
# daemon. The crate is the de-facto pure-Rust base64 implementation; gated
# on `firecracker` so the no-feature default build pulls nothing extra.
base64 = { version = "0.22", default-features = false, features = ["std"], optional = true }

# `libc` is only pulled in on Linux. Used by:
# - `shutdown::graceful_shutdown` to call `kill(2)` with `SIGTERM` directly
#   (`std::process::Child::kill` is hard-coded to `SIGKILL`).
# - `uffd` for `mmap`/`poll`/`MAP_PRIVATE` constants the userfaultfd handler
#   needs to map the snapshot mem file and poll the uffd fd for events.
# Gated by target_os so non-Linux builds (where the firecracker feature is
# meaningless) do not pull it in.
[target.'cfg(target_os = "linux")'.dependencies]
libc = "0.2"
# `userfaultfd` is the canonical Rust wrapper around the `userfaultfd(2)`
# syscall family. Used only by `crate::uffd` to service page faults Firecracker
# raises on a snapshot-restored guest. Linux-only, gated on the `firecracker`
# feature so docs.rs builds (and `cargo test --no-default-features`) don't pull
# it in. Pinned to 0.8 — the only series that builds cleanly on edition 2024 +
# rustc 1.91 at the time of writing (0.9 exists but requires a newer nix).
userfaultfd = { version = "0.8", optional = true }

[dev-dependencies]
tempfile = "3"
# Linux vsock listener used only by the `guest_metadata_daemon` example.
# Kept in dev-dependencies so the library itself has no transitive `vsock`
# footprint — the host-side client uses the per-VM Firecracker UDS, not the
# kernel's vsock interface directly.
[target.'cfg(target_os = "linux")'.dev-dependencies]
vsock = "0.5"
base64 = { version = "0.22", default-features = false, features = ["std"] }

[features]
default = []
# Enables the in-process Firecracker driver. Requires a host running KVM and
# a Firecracker binary reachable via PATH (or `MICROVM_FIRECRACKER_BIN`).
firecracker = ["dep:nix", "dep:sha2", "dep:userfaultfd", "dep:base64"]

# Examples that depend on guest-only crates (vsock listener etc.) are listed
# explicitly so `cargo build --examples --no-default-features` doesn't try to
# build them without the `firecracker` feature enabled.
[[example]]
name = "guest_metadata_daemon"
required-features = ["firecracker"]