How Isolon creates, manages, and destroys secure sandboxes. From a single node to a distributed cluster with resource-aware scheduling.
One process handles everything: HTTP API, VM lifecycle, networking, image management, and the React dashboard. The Machine Provider boots each VM through a hardened VMM process. Perfect for development and small deployments.
Auth middleware validates API key or session cookie. Control plane validates the request and resolves the image through the five-tier resolution system.
If the image is remote, the Image Manager pulls it and converts to a bootable ext4 rootfs. Cached images are reused for sub-second boots. The rootfs is prepared as a copy-on-write overlay or full copy.
The Network Manager allocates an IP from the configured range, creates a virtual network interface for the VM, and configures NAT for outbound traffic.
The Machine Provider invokes Firecracker's Jailer which drops privileges to the configured UID/GID, enters a chroot, applies seccomp-bpf filters with a tightly restricted syscall whitelist, and isolates the VMM with PID/NET/IPC/MNT namespaces and cgroups. Only then does the MicroVM boot with its kernel, rootfs, network config, and bootstrap metadata.
The control plane connects to the guest agent through a fast host-guest channel or over the virtual network, marks the workspace as ready, and returns the ID to the client.
If webhooks are configured, the Webhook Sender fires a workspace.created event with HMAC signature to all subscribed endpoints.
| Path | Protocol | Purpose |
|---|---|---|
| Host → Guest | Fast host-guest channel or TCP | Command execution, file I/O, terminal, process management |
| Guest → Host | Metadata service | Bootstrap metadata: IP, gateway, DNS, environment variables |
| External → Workspace | HTTP proxy | Preview URLs reverse-proxied through isolon-server |
Scale horizontally by separating the API gateway from compute. The Commander routes requests, schedules workloads, and monitors health. Workers run VMs and report statistics.
Lightweight HTTP server. No VMs. Routes API requests to workers via scheduling, maintains worker registry, and serves the React dashboard. Needs only SQLite and auth store.
Runs VMs and registers with Commander on startup. Auto-calculates capacity from host resources. Heartbeat loop with exponential backoff re-registration on failures.
Internal traffic uses a shared cluster token in the Authorization header, plus HMAC-SHA256 request signing. Workers validate Commander origin; Commander validates worker heartbeats.
| Strategy | Description | Best for |
|---|---|---|
| resource-aware default | Considers VM count, free memory, and CPU usage across all healthy workers | General purpose, heterogeneous hardware |
| least-loaded | Picks the worker with the fewest running VMs | Uniform hardware, simple distribution |
| round-robin | Cycles through workers evenly regardless of load | Testing, predictable distribution |
| State | Description | Accepts new work? |
|---|---|---|
| healthy | Normal operation, heartbeats arriving on schedule | Yes |
| suspect | Missed heartbeats for worker_timeout_seconds (default 30s) | Yes (with caution) |
| offline | Missed heartbeats for 2x timeout (default 60s) | No |
| draining | Admin-initiated drain, worker finishing existing VMs | No |
When a client creates a workspace, the Commander selects a healthy worker, forwards the POST /workspaces request, and stores the workspace-to-worker mapping. Subsequent requests (exec, files, terminal) are proxied to the correct worker.
Workspace-to-worker mappings are cached in memory (default TTL: 5 minutes) to avoid repeated database lookups for hot paths.
Per-worker circuit breakers trip after 3 consecutive proxy failures. Requests fast-fail for 15 seconds before a half-open probe retry.
Workers include their active workspace list in heartbeats. If the Commander restarts, it rebuilds location mappings from the next heartbeat round.
A lightweight agent runs inside every MicroVM, enabling command execution, file operations, terminal sessions, and telemetry without exposing the host.
Run commands with streaming stdout/stderr, interactive PTY sessions over WebSocket, and background process management with signal support.
Read, write, delete, and rename files. Upload and download directories as tar archives. Watch directories for changes in real time.
Clone, commit, push, and pull repositories. Monitor CPU, memory, disk, and network usage from inside the sandbox.
Direct host-to-guest communication without network stack overhead. Fast, secure, and bypasses the virtual network entirely. Requires Linux with vsock support.
Host connects to the guest agent over TCP through the virtual network bridge. Used on macOS development or when the fast channel is unavailable.