microvm

README

AerolVM

AerolVM is a self-hosted platform for creating isolated Docker-backed sandboxes on a single Linux host. This repository contains the server, installer, SDKs, and documentation you use to provision a host, create containers, expose preview URLs, and manage sandboxes over an API.

Start Here

Guide	Description
Quick Start	Spin up a sandbox and run a command in under five minutes.
Server Setup	Install and configure AerolVM on a Linux host.
SDK Setup	Connect an SDK to your AerolVM server.

Install a Server

Trial / single-user (HTTP-01 on-demand TLS):

curl -fsSL https://github.com/aerol-ai/microvm/releases/latest/download/install.sh | sudo bash -s -- \
    --domain sandbox.example.com \
    --pat-token your-secret-pat

Production (DNS-01 wildcard TLS via Cloudflare - required for real workloads):

curl -fsSL https://github.com/aerol-ai/microvm/releases/latest/download/install.sh | sudo bash -s -- \
    --domain sandbox.example.com \
    --pat-token your-secret-pat \
    --dns-provider cloudflare \
    --dns-api-token your-cloudflare-api-token

Pick the right TLS mode up-front. In HTTP-01 mode Caddy issues one Let's Encrypt certificate per sandbox subdomain on first access. Let's Encrypt caps certificate issuance at 50 new certs per registered domain per week. DNS-01 issues exactly two certs total (<domain> + *.<domain>) regardless of how many sandboxes exist, so it scales indefinitely and is required for real workloads.

If you omit --pat-token, the installer generates a token and prints it once at the end.

What AerolVM Does

• Creates isolated sandboxes backed by Docker on your own infrastructure.
• Exposes sandbox URLs as https://<sandbox-id>.<domain> and port URLs as https://<sandbox-id>-<port>.<domain>.
• Provides a PAT-authenticated REST API and SDKs for TypeScript, Python, Go, Java, and Rust.
• Supports Docker by default and gVisor as an opt-in runtime for untrusted code.
• Uses Caddy for TLS termination and public routing on a single Linux host.

SDK Example

import { MicroVM } from '@aerol-ai/aerolvm-sdk'

const client = new MicroVM({
  apiUrl: process.env.SB_API_URL,
  patToken: process.env.SB_PAT_TOKEN,
})

const sandbox = await client.create({ image: 'ubuntu:22.04' })
console.log(sandbox.publicUrl)
await sandbox.destroy()

Runtime Options

Runtime	Status	Notes
Docker	Available	Default runtime with the lowest overhead.
gVisor	Available	Install with --with-gvisor for stronger isolation.
Kata Containers	Planned	Create requests return runtime not yet implemented.

Install with gVisor support:

curl -fsSL https://github.com/aerol-ai/microvm/releases/latest/download/install.sh | sudo bash -s -- \
    --domain sandbox.example.com \
    --pat-token your-secret-pat \
    --with-gvisor

Develop and Test

make build
make test
make docs-install
make docs-dev

License

MIT