# 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.
**Under the hood:** krunvm is a CLI for creating microVMs from OCI images using libkrun and buildah; it targets Linux/KVM.
The embedded image uses standard OCI transports; tools like skopeo can copy oci: layouts into containers-storage: for local use.
## Why flashVM?
- **Real isolation:** Code executes inside a tiny KVM-backed microVM (via libkrun).
- **Zero setup for images:** A minimal Python image ships inside the wheel (OCI layout) and is auto-imported on first run.
- **Friendly API:** One call in Python (`flashvm.run(...)`) returns stdout/stderr, exit code, and optional output files (“artifacts”).
## How it works
```mermaid
flowchart LR
A[Your Python code] --> B[flashVM]
B --> C[krunvm]
C --> D[MicroVM]
D --> E[stdout / artifacts]
%% optional first-run step (imports the embedded image)
B -. first run .-> F[(Embedded OCI image)]
F --> G[/containers-storage/]
G --> C
```
> krunvm: “CLI-based utility for creating microVMs from OCI images, using libkrun and buildah” and targeting Linux/KVM.
> OCI transports: oci:PATH[:ref] and containers-storage:… are standard transports; skopeo copy can move images between them (e.g., oci: → containers-storage:).
## Requirements
### Host OS / hardware
- Linux with KVM available (i.e., /dev/kvm exists), because krunvm/libkrun rely on KVM.
### System tools (installed on the host)
- **krunvm** – microVM launcher.
- **buildah** – used by krunvm and for rootless image operations.
- **skopeo** (optional but recommended) – for fast, policy-aware copying of the embedded oci: layout into local containers-storage: on first run.
> Package names are typically krunvm, buildah, and skopeo on mainstream distros. See your distribution’s repositories or the krunvm project page for install options.
### Python
- Python 3.8+.
## Installation
From PyPI:
```bash
pip install flashvm
```
From source (editable dev mode):
```bash
pip install maturin
maturin develop
```
> krunvm/buildah/skopeo are host tools, installed via your OS package manager. See the krunvm repository for up-to-date guidance.
## Quick start
```python
import flashvm as fvm
# Optional: import the embedded OCI image into containers-storage 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"])
```
> Example with artifacts:
```python
code = r"""
with open('/work/out/result.txt', 'w') as f:
f.write('ok\n')
print('done')
"""
res = fvm.run(code, expect=["out/*.txt"])
for a in res["artifacts"]:
print(a["guest_path"], a["size_bytes"])
```
## What ships in the wheel?
An embedded OCI image layout (minimal Python userspace) placed inside the package data.
> On first use, flashVM imports that layout into local containers-storage: (using skopeo copy if present; otherwise a buildah fallback), then boots it via krunvm.
## Troubleshooting
- **“KVM not available”** – ensure hardware virtualization is enabled in BIOS/UEFI and /dev/kvm exists (group permissions may apply). krunvm targets Linux/KVM.
- **Image/transport errors** – skopeo copy supports oci: and containers-storage: transports. If skopeo isn’t installed, flashVM falls back to buildah-based import.
- **Rootless storage** – buildah and the underlying containers stack use containers-storage; this is the local image store queried by tools (buildah images, etc.). Transport syntax and examples are documented in the containers-transports manpage.
## 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 background and supported platforms.
## License
MIT (this project). krunvm/libkrun and the containers tooling are separate projects with their own licenses. See upstream repositories for details.
## Acknowledgments
The krunvm project and libkrun for making userspace microVMs practical.
The containers ecosystem (buildah, skopeo, containers-image/storage) for robust image transports—especially oci: and containers-storage:.
## Appendix: Useful references
- krunvm project page (overview, install, supported platforms).
- containers-transports manpage (syntax for oci:… and containers-storage:…, examples with skopeo copy).
Raw data
{
"_id": null,
"home_page": "https://github.com/fullzer4/flashvm",
"name": "flashvm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "python, vm, isolation, libkrun, krunvm, oci, skopeo",
"author": null,
"author_email": "fullzer4 <fullzer4@example.com>",
"download_url": null,
"platform": null,
"description": "# flashVM\n\nRun short Python snippets in a microVM for strong isolation\u2014without 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.\n\n**Under the hood:** krunvm is a CLI for creating microVMs from OCI images using libkrun and buildah; it targets Linux/KVM. \nThe embedded image uses standard OCI transports; tools like skopeo can copy oci: layouts into containers-storage: for local use.\n\n## Why flashVM?\n\n- **Real isolation:** Code executes inside a tiny KVM-backed microVM (via libkrun).\n- **Zero setup for images:** A minimal Python image ships inside the wheel (OCI layout) and is auto-imported on first run.\n- **Friendly API:** One call in Python (`flashvm.run(...)`) returns stdout/stderr, exit code, and optional output files (\u201cartifacts\u201d).\n\n## How it works\n\n```mermaid\nflowchart LR\n A[Your Python code] --> B[flashVM]\n B --> C[krunvm]\n C --> D[MicroVM]\n D --> E[stdout / artifacts]\n\n %% optional first-run step (imports the embedded image)\n B -. first run .-> F[(Embedded OCI image)]\n F --> G[/containers-storage/]\n G --> C\n```\n\n> krunvm: \u201cCLI-based utility for creating microVMs from OCI images, using libkrun and buildah\u201d and targeting Linux/KVM. \n> OCI transports: oci:PATH[:ref] and containers-storage:\u2026 are standard transports; skopeo copy can move images between them (e.g., oci: \u2192 containers-storage:).\n\n## Requirements\n\n### Host OS / hardware\n- Linux with KVM available (i.e., /dev/kvm exists), because krunvm/libkrun rely on KVM.\n\n### System tools (installed on the host)\n- **krunvm** \u2013 microVM launcher.\n- **buildah** \u2013 used by krunvm and for rootless image operations.\n- **skopeo** (optional but recommended) \u2013 for fast, policy-aware copying of the embedded oci: layout into local containers-storage: on first run.\n\n> Package names are typically krunvm, buildah, and skopeo on mainstream distros. See your distribution\u2019s repositories or the krunvm project page for install options.\n\n### Python\n- Python 3.8+.\n\n## Installation\n\nFrom PyPI:\n```bash\npip install flashvm\n```\n\nFrom source (editable dev mode):\n```bash\npip install maturin\nmaturin develop\n```\n\n> krunvm/buildah/skopeo are host tools, installed via your OS package manager. See the krunvm repository for up-to-date guidance.\n\n## Quick start\n\n```python\nimport flashvm as fvm\n\n# Optional: import the embedded OCI image into containers-storage now (idempotent)\nfvm.prepare_image() # First run does this automatically if you skip it.\n\n# Run a short snippet in a microVM\nres = fvm.run(\"print('Hello from microVM!')\")\nprint(\"exit:\", res[\"exit_code\"])\nprint(\"stdout:\", res[\"stdout\"])\nprint(\"stderr:\", res[\"stderr\"])\nprint(\"image_used:\", res[\"image_used\"])\n```\n\n> Example with artifacts:\n\n```python\ncode = r\"\"\"\nwith open('/work/out/result.txt', 'w') as f:\n f.write('ok\\n')\nprint('done')\n\"\"\"\n\nres = fvm.run(code, expect=[\"out/*.txt\"])\nfor a in res[\"artifacts\"]:\n print(a[\"guest_path\"], a[\"size_bytes\"])\n```\n\n## What ships in the wheel?\n\nAn embedded OCI image layout (minimal Python userspace) placed inside the package data.\n\n> On first use, flashVM imports that layout into local containers-storage: (using skopeo copy if present; otherwise a buildah fallback), then boots it via krunvm.\n\n## Troubleshooting\n\n- **\u201cKVM not available\u201d** \u2013 ensure hardware virtualization is enabled in BIOS/UEFI and /dev/kvm exists (group permissions may apply). krunvm targets Linux/KVM.\n- **Image/transport errors** \u2013 skopeo copy supports oci: and containers-storage: transports. If skopeo isn\u2019t installed, flashVM falls back to buildah-based import.\n- **Rootless storage** \u2013 buildah and the underlying containers stack use containers-storage; this is the local image store queried by tools (buildah images, etc.). Transport syntax and examples are documented in the containers-transports manpage.\n\n## Security / Isolation notes\n\n> 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 background and supported platforms.\n\n## License\n\nMIT (this project). krunvm/libkrun and the containers tooling are separate projects with their own licenses. See upstream repositories for details.\n\n## Acknowledgments\n\nThe krunvm project and libkrun for making userspace microVMs practical.\n\nThe containers ecosystem (buildah, skopeo, containers-image/storage) for robust image transports\u2014especially oci: and containers-storage:.\n\n## Appendix: Useful references\n\n- krunvm project page (overview, install, supported platforms).\n- containers-transports manpage (syntax for oci:\u2026 and containers-storage:\u2026, examples with skopeo copy).\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Run Python code inside libkrun microVMs, with an embedded offline OCI image",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/fullzer4/flashvm",
"Repository": "https://github.com/fullzer4/flashvm"
},
"split_keywords": [
"python",
" vm",
" isolation",
" libkrun",
" krunvm",
" oci",
" skopeo"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "efc6261aebcfd9f7227e95240060c032bfc64d72d28b745811a34eefcba10bf5",
"md5": "fdf95f410ed9d4933b5567d7408eba44",
"sha256": "4b746383cc0af0e22e266049a59ae2777a55baf5d033c6969c1815d73ba3628e"
},
"downloads": -1,
"filename": "flashvm-0.1.0-cp38-abi3-manylinux_2_39_x86_64.whl",
"has_sig": false,
"md5_digest": "fdf95f410ed9d4933b5567d7408eba44",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.8",
"size": 357957,
"upload_time": "2025-09-03T18:05:23",
"upload_time_iso_8601": "2025-09-03T18:05:23.322315Z",
"url": "https://files.pythonhosted.org/packages/ef/c6/261aebcfd9f7227e95240060c032bfc64d72d28b745811a34eefcba10bf5/flashvm-0.1.0-cp38-abi3-manylinux_2_39_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-03 18:05:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fullzer4",
"github_project": "flashvm",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "flashvm"
}
JSON
