chore: initial extraction from microvm-blueprint

Phase 0 of the decentralized microVM primitive scope-out.

This crate ships the Firecracker driver that Tangle blueprints
(sandbox, microvm, future cloud-style ones) consume directly as a
Cargo dep. No HTTP server, no auth, no sessions — operators ARE the
hosts, so there is no second process to deploy.

Source: tangle-network/microvm-blueprint @ chore/sdk-bump-0.2.0-alpha.6
        microvm-runtime/ (676 LOC firecracker adapter + traits)

Added vs. source:
  - Standalone Cargo.toml metadata (description, repository,
    keywords, categories, license).
  - rust-toolchain.toml pinned to 1.91 to match workspace expectation.
  - .github/workflows/ci.yml — fmt + clippy + test (all-features and
    no-default-features) + docs.
  - .github/dependabot.yml — cargo + actions, daily/weekly.
  - README.md — usage, env vars, hardening checklist.
  - docs/ROADMAP.md — per-release plan to production-grade.
  - LICENSE (Unlicense, matching sibling Tangle crates).

One clippy fix applied to clear -D warnings:
  src/adapters/firecracker.rs:373 — manual_unwrap_or_default
  (split_once match → unwrap_or_default).

Tests green: 1 lifecycle test from in_memory adapter. The firecracker
adapter is process-spawning so it isn't unit-tested here; integration
tests live in downstream blueprint repos and stay there for now.

Author: drewstone

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 5
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: -D warnings
+
+jobs:
+  fmt:
+    name: rustfmt
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@1.91
+        with:
+          components: rustfmt
+      - run: cargo fmt --all -- --check
+
+  clippy:
+    name: clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@1.91
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo clippy --all-targets --all-features -- -D warnings
+
+  test:
+    name: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@1.91
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo test --all-features
+      - run: cargo test --no-default-features
+
+  docs:
+    name: docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@1.91
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo doc --all-features --no-deps
+        env:
+          RUSTDOCFLAGS: -D warnings

.gitignore

@@ -0,0 +1,6 @@
+target/
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store

Cargo.lock

@@ -0,0 +1,24 @@
+[package]
+name = "microvm-runtime"
+version = "0.1.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"
+
+[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 = []

Cargo.toml

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

LICENSE

@@ -0,0 +1,67 @@
+# microvm-runtime
+
+[![crates.io](https://img.shields.io/crates/v/microvm-runtime.svg)](https://crates.io/crates/microvm-runtime)
+[![docs.rs](https://docs.rs/microvm-runtime/badge.svg)](https://docs.rs/microvm-runtime)
+
+Firecracker microVM driver for decentralized Tangle operators.
+
+A pure-Rust primitive. No HTTP server, no auth layer, no sessions, no business
+logic — just the driver that speaks the Firecracker API over its unix socket
+and exposes a small lifecycle trait. Tangle blueprints (the operator binaries)
+consume it directly as a Cargo dependency — operators **are** the hosts, so
+there is no second process to deploy.
+
+## Why this exists
+
+Every Tangle blueprint that wants microVM isolation (sandbox blueprint,
+microvm blueprint, future cloud-style blueprints) needs the same driver. This
+crate is that driver, extracted into a single primitive with a narrow surface
+so it can be hardened in one place.
+
+## Status
+
+`0.1.0-alpha.1` — extracted from `microvm-blueprint`. Lifecycle works
+(create / start / stop / snapshot / destroy). Production hardening is the
+next several releases:
+
+- [ ] Network configuration (TAP / bridge / iptables NAT)
+- [ ] Vsock device for guest↔host RPC
+- [ ] Snapshot restore (`PUT /snapshot/load`)
+- [ ] Console log ring buffer for post-mortem
+- [ ] Graceful shutdown (SIGTERM → wait → SIGKILL)
+- [ ] Jailer wrapper (chroot / cgroup v2 / seccomp / UID-GID mapping)
+- [ ] Rate limiters on drives and NICs
+- [ ] Egress firewall per session
+- [ ] Metrics polling (`GET /vm` for CPU / memory / network)
+- [ ] VM rename for warm-pool handoff
+
+See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the per-phase plan.
+
+## Usage
+
+```rust
+use microvm_runtime::{adapters::firecracker::{FirecrackerConfig, FirecrackerVmProvider}, VmProvider, VmQuery};
+
+let provider = FirecrackerVmProvider::from_env();
+provider.create_vm("vm-1")?;
+provider.start_vm("vm-1")?;
+provider.snapshot_vm("vm-1", "snap-a")?;
+provider.stop_vm("vm-1")?;
+provider.destroy_vm("vm-1")?;
+```
+
+## Environment variables
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `MICROVM_FIRECRACKER_BIN` | `/usr/local/bin/firecracker` | Firecracker binary path |
+| `MICROVM_FIRECRACKER_KERNEL` | `/var/lib/firecracker/vmlinux` | Linux kernel image |
+| `MICROVM_FIRECRACKER_ROOTFS` | `/var/lib/firecracker/rootfs/default.ext4` | Rootfs image |
+| `MICROVM_FIRECRACKER_SOCKET_DIR` | `/var/run/microvm/sockets` | Per-VM API socket parent dir |
+| `MICROVM_FIRECRACKER_STATE_DIR` | `/var/lib/microvm/state` | Per-VM state dir |
+| `MICROVM_FIRECRACKER_VCPU` | `1` | Default vCPU count |
+| `MICROVM_FIRECRACKER_MEM_MIB` | `256` | Default memory size |
+
+## License
+
+[Unlicense](LICENSE) — public domain.

README.md

@@ -0,0 +1,54 @@
+# Roadmap
+
+This crate ships in alpha-cadence releases until the production hardening list
+is complete. Each phase below is a release boundary.
+
+## 0.1.x — Extraction (current)
+
+Lifecycle: create / start / stop / snapshot (create only) / destroy. Direct
+unix-socket HTTP to the Firecracker API. No SDK dep. Process management with
+kill-on-error rollback. In-memory test adapter for downstream blueprint tests.
+
+What works for an operator today: provision a VM, boot it, capture a snapshot
+of its memory, tear it down. Not yet useful for sandboxing — the VM has no
+network and no guest↔host channel.
+
+## 0.2.x — Make it useful
+
+The minimum for any operator to actually run workloads inside a VM.
+
+- **Network setup**: TAP device creation, bridge attachment, IP allocation,
+  `PUT /network-interfaces`, host iptables NAT.
+- **Vsock**: CID allocation, `PUT /vsock`, parent dir mkdir before
+  `/snapshot/load` (FC v1.6 race fix).
+- **Snapshot restore**: `PUT /snapshot/load` + UFFD handler coordination.
+  Pairs with 0.1 snapshot-create for fast warm boot.
+- **Console capture**: stderr ring buffer (200-line tail per VM) so kernel
+  panics and init failures are debuggable post-mortem instead of `Stdio::null`.
+- **Graceful shutdown**: SIGTERM → poll → SIGKILL on timeout.
+- **Per-VM config override**: kernel, rootfs, vCPU, memory, boot args — today
+  these are workspace-level, which prevents sizing VMs to workload.
+
+## 0.3.x — Production hardening
+
+Required before a security-conscious operator should run this in production.
+
+- **Jailer wrapper**: chroot + cgroup v2 + seccomp + UID-GID mapping.
+- **Rate limiters**: bandwidth + ops quota on drives + NICs, plumbed to the FC
+  API rather than the current hardcoded `None`.
+- **Egress firewall**: per-session iptables FORWARD chain with cleanup on
+  destroy. Operator can scope what each VM can reach.
+- **Metrics polling**: periodic `GET /vm` for CPU, memory, network counters.
+- **VM rename**: FC 1.10+ identifier swap for warm-pool handoff without
+  re-snapshotting.
+
+## 0.4.x — Optional surfaces
+
+Per use case, not blocking either consumer.
+
+- MMDS (instance metadata service).
+- Balloon device (pre-snapshot memory reclaim).
+- CPU templates (cross-host migration compatibility).
+- Multi-drive support: workspace, sidecar, nix store as separate drives with
+  separate rate limits.
+- Metrics fifo for in-VM observability tools.

docs/ROADMAP.md

@@ -0,0 +1,4 @@
+[toolchain]
+channel = "1.91"
+profile = "minimal"
+components = ["rustfmt", "clippy"]