isolon

Isolon

Secure, isolated sandbox execution on your own infrastructure

Features • Quick Start • Clustering • Documentation

---

Why Isolon?

AI agents need to run code. CI pipelines need to execute untrusted scripts. Multi-tenant platforms need isolation. Containers don't provide this.

Containers share the host kernel. One vulnerability escapes the sandbox. You need hardware-level isolation — and that's what Isolon delivers.

Isolon gives every sandbox its own kernel, filesystem, and network stack. Not namespaces. Not seccomp. A real VM, booting in ~250ms, powered by the same Firecracker technology behind AWS Lambda.

---

Features

• ~250ms cold start — Firecracker MicroVMs boot fast
• Hardware-level isolation — Separate kernel per sandbox, not a shared container
• Snapshot & restore — Freeze VM state, restore in <100ms
• Warm templates — Pre-created VM states for instant start
• Air-gap ready — Runs fully offline with pre-loaded images
• Built-in auth — Organizations, users, scoped API keys, RBAC
• MCP server — 25 tools for AI agent integration
• Web dashboard — Real-time workspace management UI
• TypeScript, Python & Go SDKs — First-class client libraries
• WebSocket terminals — Interactive PTY sessions
• Git operations — Clone, commit, push inside sandboxes
• Webhook notifications — HMAC-signed HTTP callbacks
• Prometheus metrics — Built-in monitoring endpoint

---

Clustering

Isolon scales horizontally with zero external dependencies. No etcd. No Consul. No Kubernetes. Just the same binary in different modes.

Architecture

                    Commander
                       │
          ┌────────────┼────────────┐
          │            │            │
       Worker 1    Worker 2    Worker N
       (4 vCPU)    (8 vCPU)    (16 vCPU)
       (8 GB)      (16 GB)     (32 GB)
          │            │            │
       ┌──┴──┐      ┌──┴──┐      ┌──┴──┐
       VM VM VM    VM VM VM    VM VM VM

Resource-Aware Scheduling

VMs route to workers based on real-time capacity:

Score = (VM headroom × 0.4) + (Memory availability × 0.4) + (CPU availability × 0.2)

Not round-robin. Not random. Composite scoring across three dimensions.

Live Migration

Move running workspaces between workers without downtime:

1. Snapshot workspace on source worker
2. Create on target worker from snapshot
3. Update routing
4. Resume execution

No drain-and-wait. No dropped connections.

Automatic Capacity

Workers self-calculate max VMs:

• Memory: (Total RAM - 2GB) / VM memory
• CPU: (NumCPU × 4) / VM vCPUs

Set VM defaults. Workers figure out capacity.

Circuit Breaker

Per-worker failure detection:

CLOSED ──(3 failures)──▶ OPEN ──(15s)──▶ HALF_OPEN ──(success)──▶ CLOSED

Automatic workspace reconciliation cleans up phantom mappings after crashes.

---

Quick Start

Prerequisites

• Linux with KVM enabled (/dev/kvm)
• Go 1.25+, Node.js (for building SDK and dashboard)
• firecracker, jailer (v1.0+), mkfs.ext4, ip, iptables in $PATH

macOS ARM64 and Windows can run the commander (cluster coordinator). Windows ARM64 support is experimental. Workers require Linux.

Build & Run

make                    # Full build
sudo ./isolon-server    # Start server

Dashboard: http://localhost:8080

SDKs

// TypeScript
import { Sandbox } from "isolon-sdk";
const sandbox = await Sandbox.create({ image: "node:20-slim" });
await sandbox.commands.run("node", ["-e", 'console.log("Hello!")']);
await sandbox.close();

# Python
from isolon import Sandbox
sandbox = Sandbox.create(image="python:3.12-slim")
sandbox.commands.run("python", ["-c", "print('Hello!')"])
sandbox.close()

// Go
client := isolon.NewClient("http://localhost:8080", "isolon_...")
ws, _ := client.CreateWorkspace(ctx, isolon.WorkspaceRequest{Image: "alpine:latest"})
resp, _ := client.Exec(ctx, ws.ID, isolon.ExecRequest{Cmd: "echo", Args: []string{"Hello!"}})

See TypeScript SDK | Python SDK | Go SDK

---

Documentation

Document	Description
Architecture	System internals — single-node and multi-node
Authentication	Users, organizations, API keys, scopes
Air-Gap Deployment	Offline deployment and image management
Production Host Setup	Host hardening for Firecracker
Prometheus Metrics	Available metrics and example queries
Webhooks	HTTP callbacks for events
TypeScript SDK	TypeScript/JavaScript SDK reference
Python SDK	Python SDK reference
Go SDK	Go SDK and CLI reference

---

License

MIT