Skip to content

README.md

Latest commit

 

History

History
284 lines (207 loc) · 7.96 KB

README.md

File metadata and controls

284 lines (207 loc) · 7.96 KB

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
⚡