v1.4.1

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2026-05-01 - 1.4.1 - fix(readme)
+improve documentation for Firecracker runtime, networking, and base image usage
+
+- expand the project overview and feature summary with clearer runtime, networking, firewall, and WireGuard behavior
+- clarify host requirements, root privilege expectations, and optional tooling for blank rootfs creation
+- add quick-start outcome details and stronger guidance for using hosted base image manifests in production
+
 ## 2026-05-01 - 1.4.0 - feat(network)
 add configurable VM egress firewall policies and WireGuard-based host routing
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartvm",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "private": false,
   "description": "A TypeScript module wrapping Amazon Firecracker VMM for managing lightweight microVMs",
   "type": "module",

readme.md

@@ -1,11 +1,23 @@
 # @push.rocks/smartvm
 
-Run Firecracker microVMs from TypeScript without hand-rolling process management, Unix-socket HTTP calls, TAP devices, bridge setup, image caching, and cleanup. `@push.rocks/smartvm` gives you a typed orchestration layer for building tiny, fast, disk-light VM workflows on Linux/KVM.
+Boot and control Firecracker microVMs from TypeScript without rebuilding the same host plumbing every time. `@push.rocks/smartvm` handles Firecracker binaries, Unix-socket API calls, per-VM runtime directories, base-image bundles, TAP/bridge networking, optional egress firewalling, host-side WireGuard routing, and cleanup so you can focus on the VM workload.
 
 ## Issue Reporting and Security
 
 For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
+## Why It Rocks
+
+`smartvm` is for programmers who want real microVM isolation with a TypeScript control plane and sane defaults:
+
+- 🚀 Boot Firecracker VMs with a few typed calls.
+- 🧊 Keep runtime state ephemeral by default with tmpfs-backed sockets and staged writable drives.
+- 🧰 Use known-good Firecracker CI images for quick starts, or ship your own hosted image manifest with SHA256 verification.
+- 🌐 Create Linux TAP devices, bridges, deterministic guest MACs, static guest IP data, and NAT without custom scripts.
+- 🔒 Apply VM-subnet egress policy with ordered IPv4 firewall rules.
+- 🕳️ Route all VM traffic through a host WireGuard interface without installing WireGuard in the guest.
+- 🧹 Tear down processes, sockets, TAP devices, bridge/NAT/firewall/WireGuard state, and staged drive copies.
+
 ## What It Does
 
 `smartvm` wraps the operational parts of Amazon Firecracker:
@@ -15,14 +27,14 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 - Supports project-owned hosted base-image manifests with SHA256 verification.
 - Creates and controls microVMs through Firecracker's HTTP-over-Unix-socket API.
 - Converts TypeScript camelCase config into Firecracker's snake_case payloads.
-- Creates TAP devices, a Linux bridge, static guest IP assignments, and NAT rules.
+- Creates TAP devices, a Linux bridge, static guest network assignments, and NAT rules.
 - Applies optional global VM egress firewall rules for the managed subnet.
 - Routes VM egress through host-side WireGuard when configured.
 - Defaults VM runtime artifacts to tmpfs via `/dev/shm/.smartvm/runtime` when available.
 - Stages writable drives into per-VM ephemeral storage by default so guest writes do not touch cached rootfs files.
 - Cleans up Firecracker processes, sockets, TAPs, bridges, NAT/firewall/WireGuard rules, and staged drive copies.
 
-The design goal is close to a Cloudflare Workers/Deno-style filesystem model, adapted to Firecracker: immutable root image, explicit writable scratch, no accidental persistent state, and persistence only when you opt in.
+The default mental model is: immutable base image, explicit writable scratch, no accidental persistent state, and persistence only when you opt in.
 
 ## Install
 
@@ -38,13 +50,15 @@ Firecracker is a Linux/KVM technology. The package is TypeScript, but the runtim
 |---|---|
 | Linux with `/dev/kvm` | Firecracker needs KVM acceleration. |
 | Firecracker binary | Downloaded by `ensureBinary()` or supplied through `firecrackerBinaryPath`. |
-| Root privileges for networking | TAP devices, bridges, IP forwarding, and iptables NAT require elevated privileges. |
+| Root privileges for networking | TAP devices, bridges, IP forwarding, iptables NAT, firewalling, and WireGuard policy routing require elevated privileges. |
-| Host tools: `curl`, `tar`, `ip`, `sysctl`, `iptables`, `wg` when WireGuard is used | Used for binary/image downloads and network setup. |
+| Host tools: `curl`, `tar`, `ip`, `sysctl`, `iptables`, `wg` when WireGuard is used | Used for binary/image downloads and network setup. `dd` and `mkfs.ext4` are only needed for `ImageManager.createBlankRootfs()`. |
 | Enough tmpfs memory | Writable VM drives are copied into `/dev/shm` by default when available. |
 
+If you only use `VMConfig`, `SocketClient`, or custom low-level flows without creating host networking, those pieces do not need root. Actual Firecracker boot still needs a Linux/KVM-capable host.
+
 ## Quick Start
 
-This is the happy path: let `smartvm` download Firecracker, resolve a known-good base image, boot it, and clean it up.
+This is the happy path: let `smartvm` download Firecracker, resolve a known-good base image, boot it, and clean everything up. Run it on a Linux host with KVM access.
 
 ```typescript
 import { SmartVM } from '@push.rocks/smartvm';
@@ -91,6 +105,14 @@ try {
 }
 ```
 
+What happened:
+
+- Firecracker was downloaded or reused from `/tmp/.smartvm/bin`.
+- A base image bundle was resolved and cached under `/tmp/.smartvm/base-images`.
+- A per-VM socket directory was created under `/dev/shm/.smartvm/runtime/<vmId>` when `/dev/shm` exists.
+- Writable drives would be staged into that runtime directory before boot; read-only drives stay in place.
+- `cleanup()` removed VM runtime files and networking resources owned by this `SmartVM` instance.
+
 ## Disk-Light Runtime Model
 
 By default, `smartvm` treats VMs as ephemeral execution units.
@@ -222,7 +244,7 @@ const smartvm = new SmartVM(options);
 
 ## Base Images
 
-`BaseImageManager` gives you fast bootable image discovery without committing giant rootfs files to git.
+`BaseImageManager` gives you fast bootable image discovery without committing giant rootfs files to git. The `latest` and `lts` presets use Firecracker CI artifacts, which are excellent for tests, demos, and bring-up. For product workloads, prefer the `hosted` manifest path so you control the kernel/rootfs pair and verify artifacts with SHA256.
 
 ```typescript
 const baseImage = await smartvm.ensureBaseImage(); // preset: "latest"
@@ -278,6 +300,8 @@ Cache behavior:
 - Hosted URL artifacts require SHA256 hashes
 - Hosted local-path artifacts may omit SHA256, but hashes are still recorded in the cached manifest
 
+Hosted manifests are the clean way to ship a project-owned minimal image. Keep big binaries in object storage or release assets, keep only the manifest in git, and let `smartvm` verify the exact bytes before boot.
+
 Hosted manifest example:
 
 The repository ships an example at `assets/base-images/smartvm-minimal.manifest.example.json`.
@@ -773,7 +797,7 @@ import type {
 
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartvm',
-  version: '1.4.0',
+  version: '1.4.1',
   description: 'A TypeScript module wrapping Amazon Firecracker VMM for managing lightweight microVMs'
 }