flashVM

Run short Python snippets in a microVM for strong isolation—without asking users to pull images or learn container tooling. On first run, flashVM imports an embedded OCI image into local containers-storage, and then boots a microVM via krunvm (libkrun). The result (stdout, exit code, and optional artifacts) is returned to your Python process.

Install: pip install flashvm

Why flashVM?

• Real isolation: every run executes inside a tiny KVM-backed microVM (via libkrun).
• Zero image setup: a minimal Python OCI image ships inside the wheel and is auto-imported on first use.
• Friendly API: one call (flashvm.run(...)) returns stdout/stderr, exit code, and optional output files (artifacts).

Requirements

• Linux host with KVM available (/dev/kvm).
• System tools installed on the host:
  • krunvm – launch microVMs from OCI images (uses libkrun/buildah).
  • buildah – rootless image operations and storage.
  • skopeo (optional, recommended) – fast, policy-aware copy from oci: to containers-storage:.
• Python 3.8+.

Installation

From PyPI:

pip install flashvm

From source (editable dev mode):

pip install maturin
maturin develop

Note: krunvm/buildah/skopeo are host tools installed via your OS package manager.

Quick start

import flashvm as fvm

# Optional: import the embedded OCI image now (idempotent)
fvm.prepare_image()  # First run does this automatically if you skip it.

# Run a short snippet in a microVM
res = fvm.run("print('Hello from microVM!')")
print("exit:", res["exit_code"])
print("stdout:", res["stdout"])
print("stderr:", res["stderr"])
print("image_used:", res["image_used"])

With artifacts

code = r"""
with open('/work/out/result.txt', 'w') as f:
    f.write('ok\n')
print('done')
"""

res = fvm.run(code, expect=["out/*.txt"])  # collect files matching glob(s) from /work/out
for a in res["artifacts"]:
    print(a["guest_path"], a["size_bytes"])

Troubleshooting

• “KVM not available” – ensure hardware virtualization is enabled in BIOS/UEFI and /dev/kvm exists (check group permissions).
• Image/transport errors – if skopeo isn’t installed, flashVM falls back to a buildah-based import of the embedded oci: layout into containers-storage:.
• Rootless storage – containers-storage is used by buildah/skopeo; verify images with buildah images.

Security / Isolation notes

flashVM relies on krunvm (which uses libkrun) to run each execution inside a microVM. This provides stronger isolation than plain containers while keeping startup latency low. See the krunvm project for platform support and background.