push.rocks/smartvm
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial

Browse Source
This commit is contained in:
Jürgen Kunz
2026-02-08 21:47:33 +00:00
commit d8b5e8a6c0
22 changed files with 11080 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

488
readme.md Normal file
View File

@@ -0,0 +1,488 @@
# @push.rocks/smartvm
A TypeScript module that wraps Amazon's [Firecracker VMM](https://firecracker-microvm.github.io/) to create, configure, and manage lightweight microVMs with a clean, type-safe API.
## 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.
## Install
```bash
pnpm install @push.rocks/smartvm
```
> ⚡ **Prerequisites**: Firecracker requires a Linux host with KVM support (`/dev/kvm`). Networking features (TAP devices, bridges, NAT) require root privileges.
## Quick Start
```typescript
import { SmartVM } from '@push.rocks/smartvm';
// 1. Create the orchestrator
const smartvm = new SmartVM({
dataDir: '/opt/smartvm', // where binaries, kernels, rootfs are cached
firecrackerVersion: 'v1.7.0', // or omit for latest
arch: 'x86_64',
});
// 2. Download Firecracker if not already present
await smartvm.ensureBinary();
// 3. Create a MicroVM
const vm = await smartvm.createVM({
bootSource: {
kernelImagePath: '/opt/smartvm/kernels/vmlinux',
bootArgs: 'console=ttyS0 reboot=k panic=1 pci=off',
},
machineConfig: {
vcpuCount: 2,
memSizeMib: 256,
},
drives: [
{
driveId: 'rootfs',
pathOnHost: '/opt/smartvm/rootfs/ubuntu.ext4',
isRootDevice: true,
isReadOnly: false,
},
],
networkInterfaces: [
{ ifaceId: 'eth0' }, // TAP device and MAC auto-generated
],
});
// 4. Start it 🚀
await vm.start();
// 5. Inspect
console.log(vm.state); // 'running'
console.log(await vm.getInfo()); // Firecracker instance info
// 6. Pause / Resume
await vm.pause(); // state → 'paused'
await vm.resume(); // state → 'running'
// 7. Stop and clean up
await vm.stop();
await vm.cleanup();
await smartvm.cleanup();
```
## Architecture Overview
```
┌─────────────────────────────────────────────┐
│ SmartVM │ ← Top-level orchestrator
│ ┌──────────────┐ ┌────────────────────┐ │
│ │ ImageManager │ │ NetworkManager │ │
│ │ (binaries, │ │ (TAP, bridge, │ │
│ │ kernels, │ │ NAT, IP alloc) │ │
│ │ rootfs) │ │ │ │
│ └──────────────┘ └────────────────────┘ │
│ │
│ ┌─────────── MicroVM ────────────────┐ │
│ │ state: created → configuring → │ │
│ │ running → paused → stopped │ │
│ │ │ │
│ │ ┌──────────────────────────────┐ │ │
│ │ │ FirecrackerProcess │ │ │
│ │ │ (child process management) │ │ │
│ │ └──────────────────────────────┘ │ │
│ │ ┌──────────────────────────────┐ │ │
│ │ │ SocketClient │ │ │
│ │ │ (HTTP over Unix socket) │ │ │
│ │ └──────────────────────────────┘ │ │
│ │ ┌──────────────────────────────┐ │ │
│ │ │ VMConfig │ │ │
│ │ │ (camelCase → snake_case) │ │ │
│ │ └──────────────────────────────┘ │ │
│ └────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
```
Firecracker exposes a REST API over a Unix domain socket. This module handles all the plumbing: spawning the process, waiting for the socket, translating your TypeScript config into Firecracker's snake_case API payloads, managing TAP devices, and tearing everything down on exit.
## API Reference
### `SmartVM` — The Orchestrator
The entry point for everything. Manages binary downloads, VM creation, and global cleanup.
```typescript
import { SmartVM } from '@push.rocks/smartvm';
import type { ISmartVMOptions } from '@push.rocks/smartvm';
const smartvm = new SmartVM({
dataDir: '/tmp/.smartvm', // default: /tmp/.smartvm
firecrackerVersion: 'v1.7.0', // default: latest from GitHub
arch: 'x86_64', // default: x86_64 (also: aarch64)
firecrackerBinaryPath: '/usr/bin/firecracker', // optional: skip download
bridgeName: 'svbr0', // default: svbr0
subnet: '172.30.0.0/24', // default: 172.30.0.0/24
});
```
| Method | Description |
|---|---|
| `ensureBinary()` | Downloads Firecracker from GitHub if not cached. Returns path to binary. |
| `createVM(config)` | Creates a `MicroVM` instance (not yet started). Returns the VM. |
| `getVM(id)` | Look up an active VM by ID. |
| `listVMs()` | Returns an array of active VM IDs. |
| `vmCount` | Number of active VMs. |
| `stopAll()` | Stops all running/paused VMs in parallel. |
| `cleanup()` | Stops all VMs, removes TAP devices and bridge. |
### `MicroVM` — VM Lifecycle
Each VM follows a strict state machine: **created → configuring → running → paused → stopped**.
```typescript
const vm = await smartvm.createVM({
id: 'my-vm', // optional, auto-generated UUID if omitted
bootSource: {
kernelImagePath: '/path/to/vmlinux',
bootArgs: 'console=ttyS0 reboot=k panic=1',
initrdPath: '/path/to/initrd', // optional
},
machineConfig: {
vcpuCount: 4,
memSizeMib: 512,
smt: false,
cpuTemplate: 'T2', // optional: C3, T2, T2S, T2CL, T2A, V1N1
trackDirtyPages: true,
},
drives: [
{
driveId: 'rootfs',
pathOnHost: '/path/to/rootfs.ext4',
isRootDevice: true,
isReadOnly: false,
cacheType: 'Unsafe', // or 'Writeback'
rateLimiter: {
bandwidth: { size: 100_000_000, refillTime: 1_000_000_000 },
ops: { size: 1000, refillTime: 1_000_000_000 },
},
},
],
networkInterfaces: [
{
ifaceId: 'eth0',
// hostDevName and guestMac auto-generated if omitted
},
],
vsock: {
guestCid: 3,
udsPath: '/tmp/vsock.sock',
},
balloon: {
amountMib: 128,
deflateOnOom: true,
statsPollingIntervalS: 5,
},
mmds: {
version: 'V2',
networkInterfaces: ['eth0'],
},
logger: {
logPath: '/tmp/firecracker.log',
level: 'Debug',
showLogOrigin: true,
},
metrics: {
metricsPath: '/tmp/firecracker-metrics.fifo',
},
});
```
| Method | Valid States | Description |
|---|---|---|
| `start()` | `created` | Spawns Firecracker, applies config, boots the VM |
| `pause()` | `running` | Pauses VM execution |
| `resume()` | `paused` | Resumes a paused VM |
| `stop()` | `running`, `paused` | Graceful shutdown (Ctrl+Alt+Del), then force kill |
| `cleanup()` | any | Full cleanup: kill process, remove socket, remove TAPs |
| `getInfo()` | any (after start) | Returns Firecracker instance info |
| `getVersion()` | any (after start) | Returns Firecracker version |
| `createSnapshot(params)` | `paused` | Create a VM snapshot |
| `loadSnapshot(params)` | `created`, `configuring` | Load a VM from snapshot |
| `setMetadata(data)` | `running`, `paused` | Set MMDS metadata |
| `getMetadata()` | `running`, `paused` | Get MMDS metadata |
| `updateDrive(id, path)` | `running`, `paused` | Hot-update a drive path |
| `updateBalloon(mib)` | `running`, `paused` | Resize the balloon device |
| `getTapDevices()` | any | Returns TAP devices associated with this VM |
### `ImageManager` — Binary & Image Management
Handles downloading and caching Firecracker binaries, kernels, and rootfs images.
```typescript
const imageManager = smartvm.imageManager;
// Auto-download the latest Firecracker release
const version = await imageManager.getLatestVersion(); // e.g. 'v1.7.0'
const binaryPath = await imageManager.downloadFirecracker(version);
// Download kernel and rootfs images
const kernelPath = await imageManager.downloadKernel(
'https://example.com/vmlinux-5.10',
'vmlinux-5.10',
);
const rootfsPath = await imageManager.downloadRootfs(
'https://example.com/ubuntu-22.04.ext4',
'ubuntu-22.04.ext4',
);
// Create a blank rootfs or clone an existing one
const blankPath = await imageManager.createBlankRootfs('scratch.ext4', 1024);
const clonePath = await imageManager.cloneRootfs(rootfsPath, 'ubuntu-clone.ext4');
```
**Data directory layout:**
```
/tmp/.smartvm/
bin/<version>/firecracker
bin/<version>/jailer
kernels/<name>
rootfs/<name>
sockets/<vmId>.sock
```
### `NetworkManager` — Host Networking
Automatically manages TAP devices, a Linux bridge, and iptables NAT masquerade rules so VMs get internet access out of the box.
```typescript
const networkManager = smartvm.networkManager;
// Manually create a TAP device (usually handled by MicroVM.start())
const tap = await networkManager.createTapDevice('vm-id', 'eth0');
console.log(tap);
// {
// tapName: 'svvmideth0',
// guestIp: '172.30.0.2',
// gatewayIp: '172.30.0.1',
// subnetMask: '255.255.255.0',
// mac: '02:a3:b1:c4:d2:e5'
// }
// Generate kernel boot args for the guest
const bootArgs = networkManager.getGuestNetworkBootArgs(tap);
// 'ip=172.30.0.2::172.30.0.1:255.255.255.0::eth0:off'
```
**Networking architecture:**
- Creates a Linux bridge (default: `svbr0`) with gateway at `.1`
- Each VM gets a TAP device attached to the bridge
- Sequential IP allocation from `.2` onwards
- iptables NAT masquerade for outbound internet
- Deterministic MAC generation (`02:xx:xx:xx:xx:xx` locally-administered)
- TAP names fit Linux's 15-char IFNAMSIZ limit
### `VMConfig` — Config Transformer
Converts your camelCase TypeScript config into Firecracker's snake_case API payloads. Also validates configuration before boot.
```typescript
import { VMConfig } from '@push.rocks/smartvm';
const vmConfig = new VMConfig({
bootSource: { kernelImagePath: '/path/to/vmlinux' },
machineConfig: { vcpuCount: 2, memSizeMib: 256 },
});
// Validate
const result = vmConfig.validate();
// { valid: true, errors: [] }
// Generate API payloads
vmConfig.toBootSourcePayload();
// { kernel_image_path: '/path/to/vmlinux' }
vmConfig.toMachineConfigPayload();
// { vcpu_count: 2, mem_size_mib: 256 }
```
### `SocketClient` — Low-Level HTTP Client
Direct HTTP-over-Unix-socket communication with Firecracker. You typically don't need this directly — `MicroVM` handles it — but it's available if you want raw API access.
```typescript
import { SocketClient } from '@push.rocks/smartvm';
const client = new SocketClient({ socketPath: '/tmp/firecracker.sock' });
const info = await client.get('/');
const putResult = await client.put('/machine-config', { vcpu_count: 2, mem_size_mib: 256 });
const patchResult = await client.patch('/vm', { state: 'Paused' });
// Check if socket is alive (polls with timeout)
const ready = await client.isReady(5000);
```
### `SmartVMError` — Error Handling
All errors thrown by this module are `SmartVMError` instances with structured error codes.
```typescript
import { SmartVMError } from '@push.rocks/smartvm';
try {
await vm.start();
} catch (err) {
if (err instanceof SmartVMError) {
console.log(err.code); // 'INVALID_CONFIG', 'SOCKET_TIMEOUT', 'API_ERROR', etc.
console.log(err.statusCode); // HTTP status from Firecracker (if applicable)
console.log(err.details); // Raw error body from Firecracker (if applicable)
}
}
```
**Error codes:**
| Code | Description |
|---|---|
| `INVALID_STATE` | Operation not valid for current VM state |
| `INVALID_CONFIG` | Config validation failed |
| `SOCKET_TIMEOUT` | Firecracker socket didn't become ready |
| `API_TIMEOUT` | Firecracker API didn't respond in time |
| `SOCKET_REQUEST_FAILED` | HTTP request to socket failed |
| `API_ERROR` | Firecracker returned a non-2xx response |
| `BINARY_NOT_FOUND` | Firecracker binary not at expected path |
| `DOWNLOAD_FAILED` | Failed to download binary/kernel/rootfs |
| `VERSION_FETCH_FAILED` | Couldn't query GitHub for latest version |
| `BRIDGE_SETUP_FAILED` | Failed to create network bridge |
| `TAP_CREATE_FAILED` | Failed to create TAP device |
| `ROOTFS_CREATE_FAILED` | Failed to create blank rootfs |
| `ROOTFS_CLONE_FAILED` | Failed to clone rootfs image |
| `START_FAILED` | VM start sequence failed |
| `NO_CLIENT` | Socket client not initialized |
## Snapshots
Create and restore VM snapshots for fast cold-start or live migration:
```typescript
// Pause first (required for snapshots)
await vm.pause();
// Create a snapshot
await vm.createSnapshot({
snapshotPath: '/tmp/snapshot.bin',
memFilePath: '/tmp/snapshot-mem.bin',
snapshotType: 'Full', // or 'Diff' for incremental
});
// Later: restore from snapshot
const freshVm = await smartvm.createVM({
bootSource: { kernelImagePath: '/path/to/vmlinux' },
machineConfig: { vcpuCount: 2, memSizeMib: 256 },
});
await freshVm.loadSnapshot({
snapshotPath: '/tmp/snapshot.bin',
memFilePath: '/tmp/snapshot-mem.bin',
resumeVm: true,
});
```
## MMDS (Metadata Service)
Pass metadata to your guest VM via Firecracker's Microvm Metadata Service:
```typescript
const vm = await smartvm.createVM({
bootSource: { /* ... */ },
machineConfig: { /* ... */ },
networkInterfaces: [{ ifaceId: 'eth0' }],
mmds: {
version: 'V2',
networkInterfaces: ['eth0'],
},
});
await vm.start();
// Set metadata from host
await vm.setMetadata({
instance: { id: 'my-instance', region: 'eu-central-1' },
secrets: { apiKey: 'sk-...' },
});
// Guest can access via: curl http://169.254.169.254/latest/meta-data/
const data = await vm.getMetadata();
```
## Graceful Cleanup
The module registers cleanup handlers via `@push.rocks/smartexit` so resources are released even if your process crashes:
- 🔌 Firecracker child processes are killed
- 🧹 Unix socket files are removed
- 🌐 TAP devices are deleted
- 🌉 Bridge and NAT rules are torn down
You can also trigger cleanup manually:
```typescript
// Stop one VM
await vm.stop();
await vm.cleanup();
// Stop all VMs and clean everything
await smartvm.stopAll();
await smartvm.cleanup();
```
## TypeScript Interfaces
All configuration interfaces are fully exported for type-safe usage:
```typescript
import type {
ISmartVMOptions,
IMicroVMConfig,
IBootSource,
IMachineConfig,
IDriveConfig,
INetworkInterfaceConfig,
IVsockConfig,
IBalloonConfig,
IMmdsConfig,
ILoggerConfig,
IMetricsConfig,
ISnapshotCreateParams,
ISnapshotLoadParams,
IRateLimiter,
INetworkManagerOptions,
ITapDevice,
ISocketClientOptions,
IApiResponse,
TVMState,
TFirecrackerArch,
TCacheType,
TSnapshotType,
TLogLevel,
} from '@push.rocks/smartvm';
```
## 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.
**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.
### Trademarks
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
### Company Information
Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or further information, please contact us via email at hello@task.vc.
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.