Documentation

Getting started

Deploy Isolon on any Linux host with KVM. From first binary to production cluster in minutes.

Prerequisites

What you need

Hardware

Component	Minimum	Recommended
CPU	2 cores	8+ cores
Memory	4 GB	32+ GB
Disk	50 GB SSD	500 GB NVMe
Network	1 Gbps	10 Gbps
Virtualization	VT-x/AMD-V + KVM (check /dev/kvm)

Software

Linux kernel 5.10+

Required for modern Firecracker features and async I/O

cgroups v2

Strongly recommended for resource isolation. cgroups v1 supported but deprecated.

Self-contained binaries

All runtime dependencies are bundled. No additional packages to install.

bash

# Verify KVM support
ls /dev/kvm

# Add user to kvm group
sudo usermod -aG kvm $USER

# Verify cgroups v2
mount | grep cgroup2

Installation

Build from source

bash

# Clone and build
git clone https://github.com/naqvi-labs/isolon.git
cd isolon

# Full build: SDK + dashboard + Go binaries
make build

# Linux binaries only
make linux

# Native binary for local testing (macOS/Linux)
make local

Output binaries

Binary	Description
isolon-server	Server (standalone, commander, or worker mode)
isolon-agent	Guest VM agent (injected into every MicroVM)
fetch-images	Offline image downloader for air-gapped environments
isolon-cli	Command-line interface for sandbox management

bash

# Package for amd64 with all dependencies
make package

# Package for arm64
make package-arm64

Packaging assembles a self-contained deployment with binaries, kernel, and pre-converted images. Ideal for air-gapped environments.

Copy isolon-config.example.jsonc to isolon-config.json and customize. Key settings:

isolon-config.json

{
  "port": 8080,
  "db": "/var/lib/isolon/isolon.db",
  "workdir": "/var/lib/isolon/workspaces",
  "templates": "/var/lib/isolon/templates",
  "kernel": "/var/lib/isolon/kernel/vmlinux.bin",
  "cidr": "172.16.0.0/24",
  "mode": "standalone",
  "auth": {
    "enabled": true,
    "admin_org": "Engineering",
    "admin_user": "admin",
    "admin_password": "change-me"
  },
  "vm_defaults": {
    "vcpus": 1,
    "memory_mb": 512,
    "disk_size_gb": 10
  }
}

Standalone mode

Single process runs API, VMs, dashboard, and SQLite. No additional configuration needed.

sudo ./isolon-server --config isolon-config.json

Cluster mode

Commander routes to Workers. Workers auto-register and heartbeat to Commander.

# Commander (macOS or Linux)
./isolon-server --mode commander

# Worker (Linux with KVM only)
sudo ./isolon-server \
  --mode worker \
  --commander http://commander:8080 \
  --worker-address http://worker1:8080 \
  --cluster-token shared-secret

Quick Start

Your first sandbox

bash

# Create a sandbox
./isolon-cli -url http://localhost:8080 create python:3.12-alpine
# Created: ws-abc123-dead-beef

# Execute a command
./isolon-cli -url http://localhost:8080 exec ws-abc123 "python --version"
# Python 3.12.3

# Open interactive shell
./isolon-cli -url http://localhost:8080 shell ws-abc123
root@ws-abc123:~# # interactive PTY

# Stream logs
./isolon-cli -url http://localhost:8080 logs ws-abc123

# Commit as reusable image
./isolon-cli -url http://localhost:8080 commit ws-abc123 my-image

# List and destroy
./isolon-cli -url http://localhost:8080 list
./isolon-cli -url http://localhost:8080 destroy ws-abc123

sandbox.ts

import { Sandbox } from "isolon-sdk";

const sandbox = await Sandbox.create({
  image: "python:3.12-alpine",
  cpus: 2,
  memory_mb: 1024,
});

const result = await sandbox.commands.run("python --version");
console.log(result.stdout);  // Python 3.12.3

await sandbox.files.write("/app/main.py", "print('Hello')");

const term = sandbox.terminal.connect();
term.onData((data) => process.stdout.write(data));
term.write("ls -la\n");

await sandbox.commit("my-image");
await sandbox.close();

sandbox.py

from isolon import Sandbox

sandbox = Sandbox.create(
    image="python:3.12-alpine",
    cpus=2,
    memory_mb=1024,
)

result = sandbox.commands.run("python --version")
print(result.stdout)  # Python 3.12.3

sandbox.files.write("/app/main.py", "print('Hello')")

sandbox.git.clone("https://github.com/user/repo.git", path="/workspace")

forked = sandbox.fork()
sandbox.close()

main.go

package main

import (
    "context"
    "fmt"
    isolon "isolon/sdk/go/isolon"
)

func main() {
    ctx := context.Background()
    client := isolon.NewClient("http://localhost:8080", "")

    ws, _ := client.CreateWorkspace(ctx, isolon.WorkspaceRequest{
        Image:    "python:3.12-alpine",
        Cpus:     2,
        MemoryMB: 1024,
    })

    resp, _ := client.Exec(ctx, ws.ID, isolon.ExecRequest{
        Cmd:  "python",
        Args: []string{"-c", "print('Hello from MicroVM')"},
    })
    fmt.Println(resp.Stdout)

    client.DeleteWorkspace(ctx, ws.ID)
}

Resources

Learn more

Architecture

Request flows, Commander/Worker clustering, guest agent capabilities, and persistence design.

Security

Authentication modes, API key scopes, user roles, audit logging, jailer privilege drop, and rate limiting.

Air-Gap Deployment

Offline mode, pre-converted images, packaging scripts, registry mirroring, and image commit workflows.

Production Setup

Host hardening, jailer user setup, cgroups configuration, TLS, file permissions, systemd service, and capacity planning.