microheart 0.1.0__tar.gz

microheart-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ajay Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

microheart-0.1.0/NOTICE

@@ -0,0 +1,15 @@
+microheart
+Copyright (c) 2026 Ajay Kumar. Licensed under the MIT License (see LICENSE).
+
+This project downloads (or, in platform wheels, bundles) unmodified third-party software:
+
+  Firecracker  - Apache License 2.0
+                 Copyright Amazon.com, Inc. or its affiliates.
+                 https://github.com/firecracker-microvm/firecracker
+
+  Linux guest kernel images from the Firecracker CI artifacts - GPL-2.0
+                 Source: https://github.com/firecracker-microvm/firecracker
+                 and https://www.kernel.org/
+
+"Firecracker" is a name of Amazon Web Services. microheart is an independent project.
+It is not affiliated with, endorsed by, or sponsored by AWS.

microheart-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: microheart
+Version: 0.1.0
+Summary: Boot Firecracker microVMs from Python or the command line. Zero dependencies, Linux/KVM, Docker only to build the disk.
+Author: Ajay Kumar
+License: MIT
+Project-URL: Homepage, https://github.com/Aj7Ay/microheart
+Project-URL: Source, https://github.com/Aj7Ay/microheart
+Project-URL: Issues, https://github.com/Aj7Ay/microheart/issues
+Project-URL: Changelog, https://github.com/Aj7Ay/microheart/blob/main/CHANGELOG.md
+Keywords: firecracker,microvm,kvm,virtualization,sandbox,vm,isolation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Emulators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# microheart
+
+**Boot a [Firecracker](https://firecracker-microvm.github.io/) microVM with one command or three lines of Python.**
+No Python dependencies. Linux with KVM only.
+
+> **Unofficial. Not affiliated with or endorsed by Amazon Web Services.** "Firecracker" is an AWS project and name.
+>
+> **Status: alpha.** The code has not been tested on a real host yet. Test it before you rely on it.
+> See [SECURITY.md](SECURITY.md) for the known limits.
+
+## What it does
+
+Firecracker is a very small virtual machine monitor (3.6 MB). It starts a Linux guest in about a second,
+but you must do many manual steps first: get the binary, get a kernel, build a disk, make a network
+device, set NAT, write the API calls. microheart does these steps for you.
+
+| Step | By hand | With microheart |
+|---|---|---|
+| Firecracker binary | download, unpack | `fetch` (or bundled in the wheel) |
+| Guest kernel | find on S3, download | `fetch` (or bundled in the wheel) |
+| Root disk | Docker image, export, `mkfs.ext4` | `build-rootfs` |
+| Network | `ip tuntap`, `iptables`, forwarding | `up` |
+| Boot | 5 curl calls to the API socket | `up` (one `--config-file`) |
+| Login | key, route, DNS inside the guest | key, route and DNS are in the disk |
+| Clean up | remove TAP and NAT rule | `down` |
+
+## Requirements
+
+**To run a VM**
+
+- Linux, `x86_64` (or `aarch64`), with `/dev/kvm` readable and writable by root
+- Root access (`sudo`): TAP devices and `iptables` need it
+- `ip`, `iptables`, `sysctl`, `ssh` (normally present)
+- Python 3.9 or newer
+- A virtualization-capable host. A cloud VM works if nested virtualization is on (tested idea: DigitalOcean droplet)
+
+**To build the root disk (once, on any machine)**
+
+- Docker, `mkfs.ext4`, `e2fsck`, `ssh-keygen`
+
+Docker is **not** needed to run the VM. Build the disk once and copy the `.ext4` file.
+
+## Install
+
+    pip install microheart
+
+## Quick start
+
+    sudo microheart fetch            # Firecracker + kernel (skipped when bundled in the wheel)
+    sudo microheart build-rootfs     # build alpine.ext4 + an SSH key (needs Docker)
+    sudo microheart up               # boot the VM and wait for SSH
+    sudo microheart ssh uname -a     # run one command, or open a shell without arguments
+    sudo microheart down             # stop the VM, remove tap0 and the NAT rule
+
+Files go to `~/.cache/microheart/` (change with `MICROHEART_HOME`). With `sudo`, `~` is root's home.
+
+## Command reference
+
+| Command | What it does |
+|---|---|
+| `microheart fetch` | Get the Firecracker binary and the newest CI kernel into the cache. |
+| `microheart build-rootfs [--size 512M] [--output FILE]` | Build the ext4 disk from the bundled `Dockerfile`. Make an ed25519 key if none exists. |
+| `microheart up` | Make `tap0`, set NAT, write the config file, start Firecracker, wait for SSH. |
+| `microheart ssh [command...]` | SSH to the guest at `172.16.0.2` with the generated key. |
+| `microheart status` | Print `running (pid N)` or `stopped`. |
+| `microheart console [-n 40]` | Show the last lines of the guest console. |
+| `microheart down` | Stop the VM and remove the TAP device and NAT rule. |
+
+Global options (before the command): `--rootfs FILE`, `--key FILE`, `--vcpu N` (default 1), `--mem MIB` (default 256).
+
+## Python API
+
+    from microheart import MicroVM
+
+    with MicroVM("alpine.ext4", "vm_key", vcpu=2, mem_mib=512) as vm:
+        print(vm.ssh("uname -a").stdout)
+
+| Member | Meaning |
+|---|---|
+| `MicroVM(rootfs, key, vcpu=1, mem_mib=256, tap="tap0", run_dir=None)` | Describe a VM. Nothing starts yet. |
+| `.start(wait=60)` | Boot. Return the seconds until SSH worked. Needs root. |
+| `.stop()` | Ask the guest to reboot (Firecracker then exits). Kill it after 10 s. |
+| `.clean()` | `stop()` plus remove the TAP device and NAT rule. |
+| `.ssh(cmd, check=True, timeout=30)` | Run a command in the guest. Return `subprocess.CompletedProcess`. |
+| `.running()`, `.pid()` | State of the Firecracker process. |
+| `.machine_config()` | Read `/machine-config` from the Firecracker API. |
+| `.tail(n)` | Last `n` console lines. |
+
+## How it works
+
+1. `assets.py` finds the Firecracker binary and kernel (bundled, then cache, then download).
+2. `net.py` makes `tap0` with host IP `172.16.0.1/30`, turns on IP forwarding and adds `MASQUERADE`.
+3. `vm.py` writes `vm_config.json` and starts `firecracker --config-file ... --enable-pci`.
+4. The guest MAC `06:00:AC:10:00:02` and the disk's `/etc/network/interfaces` give the guest `172.16.0.2/30`
+   with gateway `172.16.0.1`. DNS (`8.8.8.8`) is written at boot.
+5. microheart polls SSH until the guest answers.
+
+Network layout:
+
+    guest eth0 172.16.0.2/30 <--virtio--> host tap0 172.16.0.1/30 --NAT--> host default interface --> internet
+
+One VM at a time for now: the IP addresses and `tap0` are fixed.
+
+## Root disk recipe
+
+`src/microheart/data/` holds the recipe:
+
+- `Dockerfile`: Alpine 3.20, OpenRC, OpenSSH, iproute2, curl. SSH is key-only.
+- `files/`: network config, DNS at boot, serial console options.
+- `build-rootfs.sh`: Docker image to folder, add your public key, `mkfs.ext4 -d`, `e2fsck`.
+
+Edit the recipe to add your own packages, then run `build-rootfs` again.
+
+## Security notes
+
+- The serial console logs in as **root with no password** (test setting).
+  Edit `data/files/etc/conf.d/agetty.ttyS0` before real use.
+- SSH accepts keys only. The key is made on your machine and is never part of the package.
+- The guest can reach the internet through host NAT. The guest and host `FORWARD` policy is set to `ACCEPT`.
+- Firecracker's `jailer` (extra isolation) is not used yet.
+- microheart runs as root and changes host network settings. Read the code first.
+
+## Limits and roadmap
+
+- Alpha, untested on a real host.
+- One VM at a time (fixed addresses).
+- No snapshots, no jailer, no multi-VM networking.
+- Planned: per-VM addresses, `--config-file` options, snapshots, jailer support, `aarch64` tests.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Build a wheel with the binary and kernel inside:
+
+    python scripts/bundle.py && python -m build --wheel
+    wheel tags --platform-tag manylinux_2_17_x86_64 --remove dist/*.whl
+
+## License
+
+MIT, see [LICENSE](LICENSE). Third-party software (Firecracker: Apache-2.0; Linux kernel: GPL-2.0) is
+downloaded or bundled unchanged. See [NOTICE](NOTICE).

microheart-0.1.0/README.md

@@ -0,0 +1,140 @@
+# microheart
+
+**Boot a [Firecracker](https://firecracker-microvm.github.io/) microVM with one command or three lines of Python.**
+No Python dependencies. Linux with KVM only.
+
+> **Unofficial. Not affiliated with or endorsed by Amazon Web Services.** "Firecracker" is an AWS project and name.
+>
+> **Status: alpha.** The code has not been tested on a real host yet. Test it before you rely on it.
+> See [SECURITY.md](SECURITY.md) for the known limits.
+
+## What it does
+
+Firecracker is a very small virtual machine monitor (3.6 MB). It starts a Linux guest in about a second,
+but you must do many manual steps first: get the binary, get a kernel, build a disk, make a network
+device, set NAT, write the API calls. microheart does these steps for you.
+
+| Step | By hand | With microheart |
+|---|---|---|
+| Firecracker binary | download, unpack | `fetch` (or bundled in the wheel) |
+| Guest kernel | find on S3, download | `fetch` (or bundled in the wheel) |
+| Root disk | Docker image, export, `mkfs.ext4` | `build-rootfs` |
+| Network | `ip tuntap`, `iptables`, forwarding | `up` |
+| Boot | 5 curl calls to the API socket | `up` (one `--config-file`) |
+| Login | key, route, DNS inside the guest | key, route and DNS are in the disk |
+| Clean up | remove TAP and NAT rule | `down` |
+
+## Requirements
+
+**To run a VM**
+
+- Linux, `x86_64` (or `aarch64`), with `/dev/kvm` readable and writable by root
+- Root access (`sudo`): TAP devices and `iptables` need it
+- `ip`, `iptables`, `sysctl`, `ssh` (normally present)
+- Python 3.9 or newer
+- A virtualization-capable host. A cloud VM works if nested virtualization is on (tested idea: DigitalOcean droplet)
+
+**To build the root disk (once, on any machine)**
+
+- Docker, `mkfs.ext4`, `e2fsck`, `ssh-keygen`
+
+Docker is **not** needed to run the VM. Build the disk once and copy the `.ext4` file.
+
+## Install
+
+    pip install microheart
+
+## Quick start
+
+    sudo microheart fetch            # Firecracker + kernel (skipped when bundled in the wheel)
+    sudo microheart build-rootfs     # build alpine.ext4 + an SSH key (needs Docker)
+    sudo microheart up               # boot the VM and wait for SSH
+    sudo microheart ssh uname -a     # run one command, or open a shell without arguments
+    sudo microheart down             # stop the VM, remove tap0 and the NAT rule
+
+Files go to `~/.cache/microheart/` (change with `MICROHEART_HOME`). With `sudo`, `~` is root's home.
+
+## Command reference
+
+| Command | What it does |
+|---|---|
+| `microheart fetch` | Get the Firecracker binary and the newest CI kernel into the cache. |
+| `microheart build-rootfs [--size 512M] [--output FILE]` | Build the ext4 disk from the bundled `Dockerfile`. Make an ed25519 key if none exists. |
+| `microheart up` | Make `tap0`, set NAT, write the config file, start Firecracker, wait for SSH. |
+| `microheart ssh [command...]` | SSH to the guest at `172.16.0.2` with the generated key. |
+| `microheart status` | Print `running (pid N)` or `stopped`. |
+| `microheart console [-n 40]` | Show the last lines of the guest console. |
+| `microheart down` | Stop the VM and remove the TAP device and NAT rule. |
+
+Global options (before the command): `--rootfs FILE`, `--key FILE`, `--vcpu N` (default 1), `--mem MIB` (default 256).
+
+## Python API
+
+    from microheart import MicroVM
+
+    with MicroVM("alpine.ext4", "vm_key", vcpu=2, mem_mib=512) as vm:
+        print(vm.ssh("uname -a").stdout)
+
+| Member | Meaning |
+|---|---|
+| `MicroVM(rootfs, key, vcpu=1, mem_mib=256, tap="tap0", run_dir=None)` | Describe a VM. Nothing starts yet. |
+| `.start(wait=60)` | Boot. Return the seconds until SSH worked. Needs root. |
+| `.stop()` | Ask the guest to reboot (Firecracker then exits). Kill it after 10 s. |
+| `.clean()` | `stop()` plus remove the TAP device and NAT rule. |
+| `.ssh(cmd, check=True, timeout=30)` | Run a command in the guest. Return `subprocess.CompletedProcess`. |
+| `.running()`, `.pid()` | State of the Firecracker process. |
+| `.machine_config()` | Read `/machine-config` from the Firecracker API. |
+| `.tail(n)` | Last `n` console lines. |
+
+## How it works
+
+1. `assets.py` finds the Firecracker binary and kernel (bundled, then cache, then download).
+2. `net.py` makes `tap0` with host IP `172.16.0.1/30`, turns on IP forwarding and adds `MASQUERADE`.
+3. `vm.py` writes `vm_config.json` and starts `firecracker --config-file ... --enable-pci`.
+4. The guest MAC `06:00:AC:10:00:02` and the disk's `/etc/network/interfaces` give the guest `172.16.0.2/30`
+   with gateway `172.16.0.1`. DNS (`8.8.8.8`) is written at boot.
+5. microheart polls SSH until the guest answers.
+
+Network layout:
+
+    guest eth0 172.16.0.2/30 <--virtio--> host tap0 172.16.0.1/30 --NAT--> host default interface --> internet
+
+One VM at a time for now: the IP addresses and `tap0` are fixed.
+
+## Root disk recipe
+
+`src/microheart/data/` holds the recipe:
+
+- `Dockerfile`: Alpine 3.20, OpenRC, OpenSSH, iproute2, curl. SSH is key-only.
+- `files/`: network config, DNS at boot, serial console options.
+- `build-rootfs.sh`: Docker image to folder, add your public key, `mkfs.ext4 -d`, `e2fsck`.
+
+Edit the recipe to add your own packages, then run `build-rootfs` again.
+
+## Security notes
+
+- The serial console logs in as **root with no password** (test setting).
+  Edit `data/files/etc/conf.d/agetty.ttyS0` before real use.
+- SSH accepts keys only. The key is made on your machine and is never part of the package.
+- The guest can reach the internet through host NAT. The guest and host `FORWARD` policy is set to `ACCEPT`.
+- Firecracker's `jailer` (extra isolation) is not used yet.
+- microheart runs as root and changes host network settings. Read the code first.
+
+## Limits and roadmap
+
+- Alpha, untested on a real host.
+- One VM at a time (fixed addresses).
+- No snapshots, no jailer, no multi-VM networking.
+- Planned: per-VM addresses, `--config-file` options, snapshots, jailer support, `aarch64` tests.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Build a wheel with the binary and kernel inside:
+
+    python scripts/bundle.py && python -m build --wheel
+    wheel tags --platform-tag manylinux_2_17_x86_64 --remove dist/*.whl
+
+## License
+
+MIT, see [LICENSE](LICENSE). Third-party software (Firecracker: Apache-2.0; Linux kernel: GPL-2.0) is
+downloaded or bundled unchanged. See [NOTICE](NOTICE).

microheart-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "microheart"
+version = "0.1.0"
+description = "Boot Firecracker microVMs from Python or the command line. Zero dependencies, Linux/KVM, Docker only to build the disk."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "Ajay Kumar"}]
+keywords = ["firecracker", "microvm", "kvm", "virtualization", "sandbox", "vm", "isolation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Emulators",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Aj7Ay/microheart"
+Source = "https://github.com/Aj7Ay/microheart"
+Issues = "https://github.com/Aj7Ay/microheart/issues"
+Changelog = "https://github.com/Aj7Ay/microheart/blob/main/CHANGELOG.md"
+
+[project.scripts]
+microheart = "microheart.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+microheart = ["data/*", "data/files/**/*", "bin/*"]

microheart-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

microheart-0.1.0/src/microheart/__init__.py

@@ -0,0 +1,5 @@
+"""microheart: run Firecracker microVMs with no Python dependencies."""
+from .vm import MicroVM
+
+__all__ = ["MicroVM"]
+__version__ = "0.1.0"

microheart-0.1.0/src/microheart/api.py

@@ -0,0 +1,31 @@
+"""Tiny client for the Firecracker API on a Unix socket (standard library only)."""
+from __future__ import annotations
+
+import http.client
+import json
+import socket
+
+
+class _UnixConn(http.client.HTTPConnection):
+    def __init__(self, path: str, timeout: float = 5):
+        super().__init__("localhost", timeout=timeout)
+        self._path = path
+
+    def connect(self):
+        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        self.sock.settimeout(self.timeout)
+        self.sock.connect(self._path)
+
+
+def request(sock_path: str, method: str, route: str, body: dict | None = None):
+    conn = _UnixConn(sock_path)
+    try:
+        data = json.dumps(body) if body is not None else None
+        conn.request(method, route, body=data, headers={"Content-Type": "application/json"})
+        resp = conn.getresponse()
+        raw = resp.read().decode()
+        if resp.status >= 300:
+            raise RuntimeError(f"{method} {route} -> {resp.status}: {raw}")
+        return json.loads(raw) if raw else None
+    finally:
+        conn.close()

microheart-0.1.0/src/microheart/assets.py

@@ -0,0 +1,84 @@
+"""Find the Firecracker binary and the guest kernel.
+
+Order: files bundled in the wheel (microheart/bin), then the cache folder.
+If neither exists, download them into the cache folder.
+"""
+import os
+import platform
+import re
+import shutil
+import stat
+import tarfile
+import tempfile
+import urllib.request
+from pathlib import Path
+
+S3 = "https://s3.amazonaws.com/spec.ccfc.min"
+RELEASES = "https://github.com/firecracker-microvm/firecracker/releases"
+PKG = Path(__file__).parent
+
+
+def cache_dir() -> Path:
+    base = os.environ.get("MICROHEART_HOME") or os.path.join(
+        os.environ.get("XDG_CACHE_HOME", os.path.expanduser("~/.cache")), "microheart")
+    p = Path(base)
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def _get(url: str) -> bytes:
+    with urllib.request.urlopen(url, timeout=60) as r:
+        return r.read()
+
+
+def _save(url: str, dest: Path) -> None:
+    with urllib.request.urlopen(url, timeout=120) as r, open(dest, "wb") as f:
+        shutil.copyfileobj(r, f)
+
+
+def _find(name_glob: str):
+    for d in (PKG / "bin", cache_dir()):
+        hits = sorted(d.glob(name_glob)) if d.is_dir() else []
+        if hits:
+            return hits[-1]
+    return None
+
+
+def firecracker_path() -> Path:
+    found = _find("firecracker")
+    if found:
+        return found
+    arch = platform.machine()
+    latest_url = urllib.request.urlopen(f"{RELEASES}/latest", timeout=60).geturl()
+    tag = latest_url.rstrip("/").split("/")[-1]
+    dest = cache_dir() / "firecracker"
+    with tempfile.TemporaryDirectory() as tmp:
+        tgz = Path(tmp) / "fc.tgz"
+        _save(f"{RELEASES}/download/{tag}/firecracker-{tag}-{arch}.tgz", tgz)
+        with tarfile.open(tgz) as t:
+            t.extractall(tmp, filter="data") if hasattr(tarfile, "data_filter") else t.extractall(tmp)
+        src = Path(tmp) / f"release-{tag}-{arch}" / f"firecracker-{tag}-{arch}"
+        shutil.copy(src, dest)
+    dest.chmod(dest.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return dest
+
+
+def kernel_path() -> Path:
+    found = _find("vmlinux-*")
+    if found:
+        return found
+    arch = platform.machine()
+    top = _get(f"{S3}?list-type=2&prefix=firecracker-ci/&delimiter=/").decode()
+    prefixes = re.findall(r"<Prefix>(firecracker-ci/[0-9]{8}-[^/]+/)</Prefix>", top)
+    prefix = sorted(prefixes)[-1]
+    listing = _get(f"{S3}?list-type=2&prefix={prefix}{arch}/vmlinux-").decode()
+    keys = re.findall(rf"<Key>({re.escape(prefix)}{arch}/vmlinux-\d+\.\d+\.\d{{1,3}})</Key>", listing)
+    key = sorted(keys, key=lambda k: [int(x) for x in re.findall(r"\d+", k.rsplit("vmlinux-", 1)[1])])[-1]
+    dest = cache_dir() / key.rsplit("/", 1)[1]
+    _save(f"{S3}/{key}", dest)
+    return dest
+
+
+def recipe_dir() -> Path:
+    """Folder with the Dockerfile and build-rootfs.sh."""
+    return PKG / "data"

microheart-0.1.0/src/microheart/cli.py

@@ -0,0 +1,85 @@
+"""Command line: microheart build-rootfs | fetch | up | ssh | status | console | down"""
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from . import assets
+from .vm import MicroVM
+
+
+def _paths():
+    home = assets.cache_dir()
+    return home / "alpine.ext4", home / "vm_key"
+
+
+def _vm(a):
+    rootfs, key = _paths()
+    return MicroVM(a.rootfs or rootfs, a.key or key, vcpu=a.vcpu, mem_mib=a.mem)
+
+
+def cmd_fetch(a):
+    print("firecracker:", assets.firecracker_path())
+    print("kernel:     ", assets.kernel_path())
+
+
+def cmd_build(a):
+    rootfs, key = _paths()
+    if not key.exists():
+        subprocess.run(["ssh-keygen", "-q", "-t", "ed25519", "-f", str(key), "-N", ""], check=True)
+    script = assets.recipe_dir() / "build-rootfs.sh"
+    subprocess.run(["bash", str(script), f"{key}.pub", a.size, str(a.output or rootfs)], check=True)
+
+
+def cmd_up(a):
+    secs = _vm(a).start()
+    print(f"VM is up ({secs:.1f} s). Try: sudo microheart ssh")
+
+
+def cmd_ssh(a):
+    vm = _vm(a)
+    os.execvp("ssh", ["ssh", "-i", vm.key, "-o", "StrictHostKeyChecking=no",
+                      "-o", "UserKnownHostsFile=/dev/null", "-o", "LogLevel=ERROR",
+                      "root@172.16.0.2", *a.command])
+
+
+def cmd_status(a):
+    vm = _vm(a)
+    print(f"running (pid {vm.pid()})" if vm.running() else "stopped")
+
+
+def cmd_console(a):
+    print(_vm(a).tail(a.lines))
+
+
+def cmd_down(a):
+    _vm(a).clean()
+    print("stopped; removed tap device and NAT rule")
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="microheart")
+    p.add_argument("--rootfs"); p.add_argument("--key")
+    p.add_argument("--vcpu", type=int, default=1); p.add_argument("--mem", type=int, default=256)
+    sub = p.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("fetch", help="download Firecracker and the kernel").set_defaults(f=cmd_fetch)
+    b = sub.add_parser("build-rootfs", help="build the ext4 disk from the Dockerfile (needs Docker, root)")
+    b.add_argument("--size", default="512M"); b.add_argument("--output", type=Path)
+    b.set_defaults(f=cmd_build)
+    sub.add_parser("up", help="boot the VM").set_defaults(f=cmd_up)
+    s = sub.add_parser("ssh", help="log in to the guest"); s.add_argument("command", nargs="*")
+    s.set_defaults(f=cmd_ssh)
+    sub.add_parser("status").set_defaults(f=cmd_status)
+    c = sub.add_parser("console"); c.add_argument("-n", "--lines", type=int, default=40)
+    c.set_defaults(f=cmd_console)
+    sub.add_parser("down", help="stop the VM and clean the network").set_defaults(f=cmd_down)
+    a = p.parse_args(argv)
+    try:
+        a.f(a)
+    except (PermissionError, RuntimeError, TimeoutError, subprocess.CalledProcessError) as e:
+        sys.exit(f"ERROR: {e}")
+
+
+if __name__ == "__main__":
+    main()

microheart-0.1.0/src/microheart/data/Dockerfile

@@ -0,0 +1,43 @@
+# Root file system for a Firecracker microVM.
+# Base: Alpine Linux. Init system: OpenRC.
+# This follows the recipe in docs/rootfs-and-kernel-setup.md (official Firecracker docs).
+# Status: alpha, not yet tested on a real host.
+
+FROM alpine:3.20
+
+# Packages:
+#   openrc          the init system (starts services at boot)
+#   util-linux      gives the agetty program (serial console login)
+#   openssh         the SSH server
+#   iproute2        the "ip" command
+#   curl, ca-certificates   test tools for the network
+RUN apk add --no-cache openrc util-linux openssh iproute2 curl ca-certificates
+
+# Serial console login on ttyS0 (from the official doc).
+RUN ln -s agetty /etc/init.d/agetty.ttyS0 \
+ && echo ttyS0 > /etc/securetty
+
+# Config files: network, DNS at boot, console options.
+COPY files/ /
+RUN chmod 755 /etc/local.d/10-dns.start
+
+# SSH: allow root login with a key only. No passwords.
+RUN echo "PermitRootLogin prohibit-password" >> /etc/ssh/sshd_config \
+ && echo "PasswordAuthentication no" >> /etc/ssh/sshd_config
+
+# Services.
+# boot level: special file systems, host name, root file system, network.
+# default level: console login, SSH, local scripts (DNS).
+RUN rc-update add devfs boot \
+ && rc-update add procfs boot \
+ && rc-update add sysfs boot \
+ && rc-update add hostname boot \
+ && rc-update add bootmisc boot \
+ && rc-update add root boot \
+ && rc-update add networking boot \
+ && rc-update add agetty.ttyS0 default \
+ && rc-update add sshd default \
+ && rc-update add local default
+
+# No SSH key and no password go into this image.
+# The build script adds the public key to the disk file after the build.

microheart-0.1.0/src/microheart/data/build-rootfs.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Build an ext4 disk file from the Dockerfile in this folder.
+#
+# Usage:   sudo ./build-rootfs.sh <public-key-file> [size] [output-file]
+# Example: sudo ./build-rootfs.sh ~/.cache/microheart/vm_key.pub 512M alpine.ext4
+#
+# Steps:
+#   1. Docker builds the image and writes its files into a folder.
+#   2. The script adds the SSH public key and the host name to the folder.
+#   3. mkfs.ext4 -d copies the folder into a new ext4 file.
+#   4. e2fsck checks the new file.
+set -euo pipefail
+
+PUBKEY="${1:?Give the path of a public key file (ends in .pub)}"
+SIZE="${2:-512M}"
+OUT="${3:-alpine.ext4}"
+
+[ -f "$PUBKEY" ] || { echo "ERROR: $PUBKEY does not exist"; exit 1; }
+[ "$(id -u)" -eq 0 ] || { echo "ERROR: run this script as root"; exit 1; }
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+echo "Step 1: build the image and write its files to a folder"
+# --output type=local writes the image files straight to a folder.
+# It avoids the empty /etc/hostname, /etc/hosts and /etc/resolv.conf
+# that "docker export" can leave behind. Verify this on your Docker version.
+docker build --output "type=local,dest=$WORK/root" "$(dirname "$0")"
+
+echo "Step 2: add the SSH public key and the host name"
+install -d -m 700 "$WORK/root/root/.ssh"
+install -m 600 "$PUBKEY" "$WORK/root/root/.ssh/authorized_keys"
+echo "fc-alpine" > "$WORK/root/etc/hostname"
+printf '127.0.0.1 localhost\n' > "$WORK/root/etc/hosts"
+mkdir -p "$WORK/root"/{dev,proc,sys,run,tmp,var}
+
+echo "Step 3: make the ext4 file ($SIZE)"
+rm -f "$OUT"
+truncate -s "$SIZE" "$OUT"
+mkfs.ext4 -q -d "$WORK/root" -F "$OUT"
+
+echo "Step 4: check the file system"
+e2fsck -fn "$OUT" > /dev/null && echo "OK: $OUT is a valid ext4 file system"
+ls -lh "$OUT"

microheart-0.1.0/src/microheart/data/files/etc/conf.d/agetty.ttyS0

@@ -0,0 +1,4 @@
+# Serial console login. TEST ONLY: root logs in with no password.
+# Anyone who reaches the console becomes root. Remove this for real use.
+# If login does not work, run "passwd -d root" in the build script instead.
+agetty_options="--autologin root --noclear"

microheart-0.1.0/src/microheart/data/files/etc/local.d/10-dns.start

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Runs at boot (OpenRC "local" service).
+# Docker does not keep /etc/resolv.conf in an image, so we write it at boot.
+printf 'nameserver 8.8.8.8\noptions single-request-reopen\n' > /etc/resolv.conf

microheart-0.1.0/src/microheart/data/files/etc/network/interfaces

@@ -0,0 +1,8 @@
+auto lo
+iface lo inet loopback
+
+auto eth0
+iface eth0 inet static
+    address 172.16.0.2
+    netmask 255.255.255.252
+    gateway 172.16.0.1

microheart-0.1.0/src/microheart/net.py

@@ -0,0 +1,38 @@
+"""Host network: one TAP device and one NAT rule. Needs root."""
+import json
+import subprocess
+
+
+def _run(*cmd, check=True, capture=False):
+    return subprocess.run(cmd, check=check, text=True,
+                          stdout=subprocess.PIPE if capture else None,
+                          stderr=subprocess.DEVNULL if not check else None)
+
+
+def host_iface() -> str:
+    out = _run("ip", "-j", "route", "list", "default", capture=True).stdout
+    return json.loads(out)[0]["dev"]
+
+
+def up(tap: str, host_ip: str) -> str:
+    if _run("ip", "link", "show", tap, check=False).returncode != 0:
+        _run("ip", "tuntap", "add", "dev", tap, "mode", "tap")
+    if f"{host_ip}/30" not in _run("ip", "addr", "show", "dev", tap, capture=True).stdout:
+        _run("ip", "addr", "add", f"{host_ip}/30", "dev", tap)
+    _run("ip", "link", "set", "dev", tap, "up")
+    _run("sysctl", "-q", "-w", "net.ipv4.ip_forward=1")
+    _run("iptables", "-P", "FORWARD", "ACCEPT")
+    iface = host_iface()
+    if _run("iptables", "-t", "nat", "-C", "POSTROUTING", "-o", iface, "-j", "MASQUERADE",
+            check=False).returncode != 0:
+        _run("iptables", "-t", "nat", "-A", "POSTROUTING", "-o", iface, "-j", "MASQUERADE")
+    return iface
+
+
+def down(tap: str) -> None:
+    _run("ip", "link", "del", tap, check=False)
+    try:
+        iface = host_iface()
+    except (IndexError, subprocess.CalledProcessError):
+        return
+    _run("iptables", "-t", "nat", "-D", "POSTROUTING", "-o", iface, "-j", "MASQUERADE", check=False)

microheart-0.1.0/src/microheart/vm.py

@@ -0,0 +1,116 @@
+"""MicroVM: build a config file, boot Firecracker, reach the guest over SSH."""
+import json
+import os
+import signal
+import subprocess
+import time
+from pathlib import Path
+
+from . import api, assets, net
+
+GUEST_IP = "172.16.0.2"   # fixed in the rootfs: data/files/etc/network/interfaces
+HOST_IP = "172.16.0.1"
+GUEST_MAC = "06:00:AC:10:00:02"
+
+
+class MicroVM:
+    def __init__(self, rootfs, key, vcpu=1, mem_mib=256, tap="tap0", run_dir=None):
+        self.rootfs = str(Path(rootfs).resolve())
+        self.key = str(Path(key).resolve())
+        self.vcpu, self.mem, self.tap = vcpu, mem_mib, tap
+        self.run_dir = Path(run_dir or assets.cache_dir() / "run")
+        self.run_dir.mkdir(parents=True, exist_ok=True)
+        self.sock = str(self.run_dir / "firecracker.socket")
+        self.pidfile = self.run_dir / "firecracker.pid"
+        self.console = self.run_dir / "console.log"
+
+    # -- state ---------------------------------------------------------
+    def pid(self):
+        try:
+            pid = int(self.pidfile.read_text())
+            os.kill(pid, 0)
+            return pid
+        except (FileNotFoundError, ValueError, ProcessLookupError):
+            return None
+
+    def running(self) -> bool:
+        return self.pid() is not None
+
+    # -- lifecycle -----------------------------------------------------
+    def config(self) -> dict:
+        return {
+            "boot-source": {"kernel_image_path": str(assets.kernel_path()),
+                            "boot_args": "console=ttyS0 reboot=k panic=1"},
+            "drives": [{"drive_id": "rootfs", "path_on_host": self.rootfs,
+                        "is_root_device": True, "is_read_only": False}],
+            "network-interfaces": [{"iface_id": "net1", "guest_mac": GUEST_MAC,
+                                    "host_dev_name": self.tap}],
+            "machine-config": {"vcpu_count": self.vcpu, "mem_size_mib": self.mem},
+        }
+
+    def start(self, wait=60):
+        if os.geteuid() != 0:
+            raise PermissionError("run as root (use sudo)")
+        if not os.access("/dev/kvm", os.R_OK | os.W_OK):
+            raise PermissionError("no access to /dev/kvm")
+        if self.running():
+            return
+        fc = assets.firecracker_path()
+        net.up(self.tap, HOST_IP)
+        cfg = self.run_dir / "vm_config.json"
+        cfg.write_text(json.dumps(self.config(), indent=2))
+        Path(self.sock).unlink(missing_ok=True)
+        with open(self.console, "w") as log:
+            proc = subprocess.Popen([str(fc), "--api-sock", self.sock, "--config-file", str(cfg),
+                                     "--enable-pci"], stdout=log, stderr=subprocess.STDOUT,
+                                    stdin=subprocess.DEVNULL, start_new_session=True)
+        self.pidfile.write_text(str(proc.pid))
+        t0 = time.time()
+        while time.time() - t0 < wait:
+            if proc.poll() is not None:
+                raise RuntimeError("Firecracker stopped:\n" + self.tail())
+            if self.ssh("true", check=False).returncode == 0:
+                return time.time() - t0
+            time.sleep(1)
+        raise TimeoutError(f"no SSH after {wait} s:\n" + self.tail())
+
+    def stop(self):
+        pid = self.pid()
+        if pid:
+            self.ssh("reboot", check=False)       # a guest reboot makes Firecracker exit
+            for _ in range(10):
+                if not self.running():
+                    break
+                time.sleep(1)
+            if self.running():
+                os.kill(pid, signal.SIGTERM)
+        self.pidfile.unlink(missing_ok=True)
+        Path(self.sock).unlink(missing_ok=True)
+
+    def clean(self):
+        self.stop()
+        net.down(self.tap)
+
+    # -- guest access --------------------------------------------------
+    def ssh(self, command: str, check=True, timeout=30):
+        return subprocess.run(
+            ["ssh", "-i", self.key, "-o", "StrictHostKeyChecking=no",
+             "-o", "UserKnownHostsFile=/dev/null", "-o", "LogLevel=ERROR",
+             "-o", "ConnectTimeout=3", f"root@{GUEST_IP}", command],
+            check=check, text=True, capture_output=True, timeout=timeout)
+
+    def machine_config(self):
+        return api.request(self.sock, "GET", "/machine-config")
+
+    def tail(self, n=30) -> str:
+        try:
+            return "\n".join(self.console.read_text().splitlines()[-n:])
+        except FileNotFoundError:
+            return ""
+
+    def __enter__(self):
+        self.start()
+        return self
+
+    def __exit__(self, *exc):
+        self.clean()

microheart-0.1.0/src/microheart.egg-info/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: microheart
+Version: 0.1.0
+Summary: Boot Firecracker microVMs from Python or the command line. Zero dependencies, Linux/KVM, Docker only to build the disk.
+Author: Ajay Kumar
+License: MIT
+Project-URL: Homepage, https://github.com/Aj7Ay/microheart
+Project-URL: Source, https://github.com/Aj7Ay/microheart
+Project-URL: Issues, https://github.com/Aj7Ay/microheart/issues
+Project-URL: Changelog, https://github.com/Aj7Ay/microheart/blob/main/CHANGELOG.md
+Keywords: firecracker,microvm,kvm,virtualization,sandbox,vm,isolation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Emulators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# microheart
+
+**Boot a [Firecracker](https://firecracker-microvm.github.io/) microVM with one command or three lines of Python.**
+No Python dependencies. Linux with KVM only.
+
+> **Unofficial. Not affiliated with or endorsed by Amazon Web Services.** "Firecracker" is an AWS project and name.
+>
+> **Status: alpha.** The code has not been tested on a real host yet. Test it before you rely on it.
+> See [SECURITY.md](SECURITY.md) for the known limits.
+
+## What it does
+
+Firecracker is a very small virtual machine monitor (3.6 MB). It starts a Linux guest in about a second,
+but you must do many manual steps first: get the binary, get a kernel, build a disk, make a network
+device, set NAT, write the API calls. microheart does these steps for you.
+
+| Step | By hand | With microheart |
+|---|---|---|
+| Firecracker binary | download, unpack | `fetch` (or bundled in the wheel) |
+| Guest kernel | find on S3, download | `fetch` (or bundled in the wheel) |
+| Root disk | Docker image, export, `mkfs.ext4` | `build-rootfs` |
+| Network | `ip tuntap`, `iptables`, forwarding | `up` |
+| Boot | 5 curl calls to the API socket | `up` (one `--config-file`) |
+| Login | key, route, DNS inside the guest | key, route and DNS are in the disk |
+| Clean up | remove TAP and NAT rule | `down` |
+
+## Requirements
+
+**To run a VM**
+
+- Linux, `x86_64` (or `aarch64`), with `/dev/kvm` readable and writable by root
+- Root access (`sudo`): TAP devices and `iptables` need it
+- `ip`, `iptables`, `sysctl`, `ssh` (normally present)
+- Python 3.9 or newer
+- A virtualization-capable host. A cloud VM works if nested virtualization is on (tested idea: DigitalOcean droplet)
+
+**To build the root disk (once, on any machine)**
+
+- Docker, `mkfs.ext4`, `e2fsck`, `ssh-keygen`
+
+Docker is **not** needed to run the VM. Build the disk once and copy the `.ext4` file.
+
+## Install
+
+    pip install microheart
+
+## Quick start
+
+    sudo microheart fetch            # Firecracker + kernel (skipped when bundled in the wheel)
+    sudo microheart build-rootfs     # build alpine.ext4 + an SSH key (needs Docker)
+    sudo microheart up               # boot the VM and wait for SSH
+    sudo microheart ssh uname -a     # run one command, or open a shell without arguments
+    sudo microheart down             # stop the VM, remove tap0 and the NAT rule
+
+Files go to `~/.cache/microheart/` (change with `MICROHEART_HOME`). With `sudo`, `~` is root's home.
+
+## Command reference
+
+| Command | What it does |
+|---|---|
+| `microheart fetch` | Get the Firecracker binary and the newest CI kernel into the cache. |
+| `microheart build-rootfs [--size 512M] [--output FILE]` | Build the ext4 disk from the bundled `Dockerfile`. Make an ed25519 key if none exists. |
+| `microheart up` | Make `tap0`, set NAT, write the config file, start Firecracker, wait for SSH. |
+| `microheart ssh [command...]` | SSH to the guest at `172.16.0.2` with the generated key. |
+| `microheart status` | Print `running (pid N)` or `stopped`. |
+| `microheart console [-n 40]` | Show the last lines of the guest console. |
+| `microheart down` | Stop the VM and remove the TAP device and NAT rule. |
+
+Global options (before the command): `--rootfs FILE`, `--key FILE`, `--vcpu N` (default 1), `--mem MIB` (default 256).
+
+## Python API
+
+    from microheart import MicroVM
+
+    with MicroVM("alpine.ext4", "vm_key", vcpu=2, mem_mib=512) as vm:
+        print(vm.ssh("uname -a").stdout)
+
+| Member | Meaning |
+|---|---|
+| `MicroVM(rootfs, key, vcpu=1, mem_mib=256, tap="tap0", run_dir=None)` | Describe a VM. Nothing starts yet. |
+| `.start(wait=60)` | Boot. Return the seconds until SSH worked. Needs root. |
+| `.stop()` | Ask the guest to reboot (Firecracker then exits). Kill it after 10 s. |
+| `.clean()` | `stop()` plus remove the TAP device and NAT rule. |
+| `.ssh(cmd, check=True, timeout=30)` | Run a command in the guest. Return `subprocess.CompletedProcess`. |
+| `.running()`, `.pid()` | State of the Firecracker process. |
+| `.machine_config()` | Read `/machine-config` from the Firecracker API. |
+| `.tail(n)` | Last `n` console lines. |
+
+## How it works
+
+1. `assets.py` finds the Firecracker binary and kernel (bundled, then cache, then download).
+2. `net.py` makes `tap0` with host IP `172.16.0.1/30`, turns on IP forwarding and adds `MASQUERADE`.
+3. `vm.py` writes `vm_config.json` and starts `firecracker --config-file ... --enable-pci`.
+4. The guest MAC `06:00:AC:10:00:02` and the disk's `/etc/network/interfaces` give the guest `172.16.0.2/30`
+   with gateway `172.16.0.1`. DNS (`8.8.8.8`) is written at boot.
+5. microheart polls SSH until the guest answers.
+
+Network layout:
+
+    guest eth0 172.16.0.2/30 <--virtio--> host tap0 172.16.0.1/30 --NAT--> host default interface --> internet
+
+One VM at a time for now: the IP addresses and `tap0` are fixed.
+
+## Root disk recipe
+
+`src/microheart/data/` holds the recipe:
+
+- `Dockerfile`: Alpine 3.20, OpenRC, OpenSSH, iproute2, curl. SSH is key-only.
+- `files/`: network config, DNS at boot, serial console options.
+- `build-rootfs.sh`: Docker image to folder, add your public key, `mkfs.ext4 -d`, `e2fsck`.
+
+Edit the recipe to add your own packages, then run `build-rootfs` again.
+
+## Security notes
+
+- The serial console logs in as **root with no password** (test setting).
+  Edit `data/files/etc/conf.d/agetty.ttyS0` before real use.
+- SSH accepts keys only. The key is made on your machine and is never part of the package.
+- The guest can reach the internet through host NAT. The guest and host `FORWARD` policy is set to `ACCEPT`.
+- Firecracker's `jailer` (extra isolation) is not used yet.
+- microheart runs as root and changes host network settings. Read the code first.
+
+## Limits and roadmap
+
+- Alpha, untested on a real host.
+- One VM at a time (fixed addresses).
+- No snapshots, no jailer, no multi-VM networking.
+- Planned: per-VM addresses, `--config-file` options, snapshots, jailer support, `aarch64` tests.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Build a wheel with the binary and kernel inside:
+
+    python scripts/bundle.py && python -m build --wheel
+    wheel tags --platform-tag manylinux_2_17_x86_64 --remove dist/*.whl
+
+## License
+
+MIT, see [LICENSE](LICENSE). Third-party software (Firecracker: Apache-2.0; Linux kernel: GPL-2.0) is
+downloaded or bundled unchanged. See [NOTICE](NOTICE).

microheart-0.1.0/src/microheart.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+NOTICE
+README.md
+pyproject.toml
+src/microheart/__init__.py
+src/microheart/api.py
+src/microheart/assets.py
+src/microheart/cli.py
+src/microheart/net.py
+src/microheart/vm.py
+src/microheart.egg-info/PKG-INFO
+src/microheart.egg-info/SOURCES.txt
+src/microheart.egg-info/dependency_links.txt
+src/microheart.egg-info/entry_points.txt
+src/microheart.egg-info/top_level.txt
+src/microheart/data/Dockerfile
+src/microheart/data/build-rootfs.sh
+src/microheart/data/files/etc/conf.d/agetty.ttyS0
+src/microheart/data/files/etc/local.d/10-dns.start
+src/microheart/data/files/etc/network/interfaces

microheart-0.1.0/src/microheart.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

microheart-0.1.0/src/microheart.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+microheart = microheart.cli:main

microheart-0.1.0/src/microheart.egg-info/top_level.txt

@@ -0,0 +1 @@
+microheart