@push.rocks/smartvm

A TypeScript module that wraps Amazon's Firecracker VMM 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/. 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/ account to submit Pull Requests directly.

Install

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

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.

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.

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.

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.

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.

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.

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.

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:

// 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:

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:

// 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:

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 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.