Hypermachine

Spawn Firecracker microVMs with excellent DX for AI agents.

Overview

Hypermachine is a lightweight tool for creating and managing Firecracker microVMs. It provides both a CLI and a programmatic API for spawning isolated sandbox environments, perfect for running untrusted code from AI agents.

Key features:

• Boot microVMs in ~150ms
• Simple CLI for quick operations
• TypeScript SDK for programmatic control
• Minimal resource footprint (128MB RAM default)
• Snapshot and restore support
• OCI image support - Pull and run Docker/OCI images
• Built with Bun for maximum performance

Requirements

• Linux with KVM support (/dev/kvm)
• Root privileges (for VM creation)
• Bun runtime (for development)
• skopeo (for OCI image pulling): apt-get install -y skopeo
• e2fsprogs (for ext4 filesystem creation): apt-get install -y e2fsprogs

Installation

From Binary

Download latest release and place it in your PATH:

sudo mv hypermachine-linux /usr/local/bin/hypermachine
sudo chmod +x /usr/local/bin/hypermachine

From Source

git clone https://github.com/valyentdev/hypermachine.git
cd hypermachine
bun install
bun run build

Quick Start

1. Setup (Optional - for rootfs images)

Download kernel and create a root filesystem:

sudo hypermachine setup

This will:

• Download a Linux kernel to /opt/hypermachine/vmlinux.bin
• Create an Alpine-based rootfs at /opt/hypermachine/rootfs.ext4
• Generate default configuration at /etc/hypermachine/config.json

Note: Setup is optional if you're using OCI images - they provide their own rootfs.

2. Create a Sandbox with OCI Image

sudo hypermachine create --image nginx:alpine --vcpus 2 --memory 256

3. Create a Sandbox (traditional method)

sudo hypermachine create --vcpus 2 --memory 256

4. List Running Sandboxes

hypermachine list

5. Destroy a Sandbox

sudo hypermachine destroy <id>

CLI Reference

hypermachine <command> [options]

COMMANDS:
  create      Create and start a new sandbox
  list        List all running sandboxes
  stop        Stop a running sandbox
  destroy     Destroy a sandbox
  status      Show status of a sandbox
  setup       Download kernel and rootfs
  version     Show version

OPTIONS:
  --vcpus <n>       Number of vCPUs (default:1)
  --memory <mb>     Memory in MB (default: 128)
  --kernel <path>   Path to kernel image
  --rootfs <path>   Path to root filesystem
  --image <ref>     OCI image reference (e.g., docker.io/library/nginx:alpine)
  --debug           Enable debug logging
  --help            Show this help

Programmatic API

OCI Image Support

import { Hypermachine } from 'hypermachine';

const hypermachine = new Hypermachine({
  dataDir: '/var/lib/hypermachine',
  firecrackerPath: '/usr/local/bin/firecracker',
  jailerPath: '/usr/local/bin/jailer',
});

// Create sandbox from OCI image
const sandbox = await hypermachine.create({
  imageRef: 'docker.io/library/nginx:alpine',
  vcpus: 2,
  memoryMb: 256,
});

console.log(`Sandbox ${sandbox.id} is running!`);

// Stop and cleanup
await sandbox.destroy();

Traditional Rootfs Method

import { Hypermachine } from 'hypermachine';

const hypermachine = new Hypermachine({
  defaultKernelPath: '/opt/hypermachine/vmlinux.bin',
  defaultRootfsPath: '/opt/hypermachine/rootfs.ext4',
});

const sandbox = await hypermachine.create({
  vcpus: 2,
  memoryMb: 256,
  rootfsPath: '/custom/rootfs.ext4',
});

await sandbox.pause();
await sandbox.resume();

Configuration Options

interface HypermachineConfig {
  dataDir?: string;           // Data directory (default: /var/lib/hypermachine)
  firecrackerPath?: string;   // Path to firecracker binary
  jailerPath?: string;        // Path to jailer binary
  defaultKernelPath?: string; // Default kernel image
  defaultRootfsPath?: string; // Default root filesystem
  debug?: boolean;            // Enable debug logging
}

interface SandboxOptions {
  vcpus?: number;             // Number of vCPUs (default:1)
  memoryMb?: number;          // Memory in MB (default: 128)
  kernelPath?: string;        // Custom kernel path
  rootfsPath?: string;        // Custom rootfs path
  imageRef?: string;          // OCI image reference
  enableNetworking?: boolean; // Enable networking (default: false)
  timeout?: number;           // Operation timeout in ms (default: 30000)
}

OCI Image Format

Hypermachine supports full Docker image reference format:

• nginx:alpine - Official image with tag
• docker.io/library/nginx:alpine - Full reference
• ghcr.io/user/repo:latest - Custom registry
• ghcr.io/user/repo@sha256:abc... - Digest reference
• localhost:5000/myrepo:tag - Local registry

How It Works

1. Image Parsing: Parses registry, repository, and tag/digest
2. Image Pulling: Uses skopeo copy to download image to local cache
3. Layer Extraction: Extracts each layer tar.gz in order
4. Whiteout Handling: Processes OCI whiteout files (.wh.*) for deletions
5. Layer Merging: Combines layers into final rootfs
6. Ext4 Creation: Creates ext4 filesystem from rootfs for Firecracker
7. Caching: Stores images in /var/lib/hypermachine/oci/ to avoid re-downloads

Caching

Images are cached by their full reference. To force a re-pull:

sudo rm -rf /var/lib/hypermachine/oci/docker.io_library_nginx_alpine/

Backward Compatibility

Traditional workflows using --rootfs and --kernel continue to work unchanged:

# Old method (still supported)
sudo hypermachine create --rootfs /custom/rootfs.ext4 --kernel /custom/vmlinux.bin

# New method (OCI images)
sudo hypermachine create --image nginx:alpine --rootfs /custom/rootfs.ext4 --kernel /custom/vmlinux.bin

Architecture

┌──────────────────────────────────────────────────────┐
│                    Hypermachine                       │
├──────────────────────────────────────────────────────┤
│  CLI (hypermachine)    │    SDK (Hypermachine)       │
├──────────────────────────────────────────────────────┤
│       OCI Image Management                          │
├──────────────────────────────────────────────────────┤
│              FirecrackerVM Management                 │
├──────────────────────────────────────────────────────┤
│              FirecrackerClient (HTTP API)             │
├──────────────────────────────────────────────────────┤
│                  Firecracker VMM                      │
└──────────────────────────────────────────────────────┘

Development

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run tests
bun test

# Type check
bun run typecheck

# Build for production
bun run build

Testing

# Unit tests
bun run test:unit

# Integration tests
bun run test:integration

# Full test suite on VPS
./test-vps.sh

License

MIT License - see LICENSE for details.

Credits

Built by Alexis Bouchez.

Powered by Firecracker and Bun.

See Also

• OCI Image Support Documentation
• Implementation Summary