smartvm/readme.hints.md

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

Key API Patterns

• 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()

Firecracker API

• 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" }