Project Hints

Architecture

Wraps Amazon Firecracker VMM using HTTP-over-Unix-socket API
Uses @push.rocks/smartrequest with URL format http://unix:<socket>:<path> for socket communication
Uses @push.rocks/smartshell execStreaming() to manage Firecracker child processes
Uses @push.rocks/smartexit for cleanup on process exit
BaseImageManager downloads Firecracker CI demo artifacts or hosted project manifests into /tmp/.smartvm/base-images by default
Base image cache keeps 2 bundles by default and warns before evicting older bundles
Hosted manifest examples live in assets/base-images/
VM runtime files default to /dev/shm/.smartvm/runtime when available
Writable drives are staged into per-VM runtime storage by default and removed during cleanup; use ephemeral: false only for explicit persistence

SmartRequest: SmartRequest.create().url(...).json(body).put() — response has .status, .ok, .json()
Smartshell: shell.execStreaming(cmd) returns { childProcess, terminate(), kill(), finalPromise }
SmartExit: smartExit.addProcess(child), smartExit.addCleanupFunction(fn), smartExit.killAll()

Pre-boot config: PUT /boot-source, PUT /machine-config, PUT /drives/{id}, PUT /network-interfaces/{id}
Start: PUT /actions { action_type: "InstanceStart" }
Pause/Resume: PATCH /vm { state: "Paused" | "Resumed" }
Stop: PUT /actions { action_type: "SendCtrlAltDel" }

Default pnpm test skips real Firecracker boot testing
Set SMARTVM_RUN_INTEGRATION=true to run the opt-in boot test
SMARTVM_BASE_IMAGE_PRESET supports latest and lts; default is latest
Hosted/project-owned bundles use baseImageManifestUrl, baseImageManifestPath, manifestUrl, or manifestPath