Skip to main content
Sandboxes are currently in beta. Do not run production workloads on sandboxes — data loss may occur during this phase.
Sandboxes are lightweight, isolated virtual machines built on Firecracker that spin up in milliseconds. Each sandbox runs a full Linux environment from a pre-built template, with filesystem operations and command execution via API.

​
Key concepts

Ephemeral sandboxes

Disposable environments with a time-to-live. Automatically destroyed when the timeout expires. Ideal for one-off code execution, CI jobs, and short-lived tasks.

Persistent sandboxes

Long-lived environments that auto-suspend after idle periods using Firecracker snapshots, and wake on demand in under 500ms. Ideal for development environments and AI coding agents.

Templates

Pre-built VM images (Python, Node.js, Go, or custom) that define the base environment for sandboxes. Templates use Docker-to-ext4 conversion for maximum compatibility.

Warm pool

A configurable pool of pre-booted VMs per template for sub-200ms sandbox creation. Eliminates cold boot latency for latency-sensitive workloads.

​
How sandboxes compare

AppsAgentsSandboxes
PurposeDeployed servicesAI agent workspacesEphemeral code execution
LifetimePermanentHours to daysSeconds to hours
Created byDeveloper via CLIDeveloper via CLI/APIAI agent via SDK/API
InterfaceHTTP routes, proxySSH, terminal, gitExecute API, file API
Boot speedRolling deploy (minutes)Template launch (seconds)Instant from warm pool (< 200ms)

​
Lifecycle

Every sandbox is a Firecracker microVM running on a Linux host with KVM support:
  1. Create — A sandbox is created from a template. If a warm pool VM is available, it’s claimed instantly. Otherwise, a new VM cold-boots (~2-3 seconds).
  2. Run — The sandbox is a fully functional Linux VM. Execute commands, upload/download files, and interact via the REST API or CLI.
  3. Suspend (persistent only) — After the idle timeout expires, the VM’s full memory and CPU state are snapshotted to disk. The Firecracker process is killed, freeing all host resources.
  4. Wake (persistent only) — Any API call to a suspended sandbox triggers automatic restoration from the snapshot. The VM resumes exactly where it left off in under 500ms.
  5. Destroy — The VM is stopped, all resources (TAP devices, IP allocations, overlay files, snapshots) are cleaned up.

​
Architecture

Each sandbox uses three key technologies for performance and isolation:

​
Copy-on-Write overlays

Instead of copying the full template image for each sandbox, ZWRM uses a read-only base image with a sparse writable overlay per VM. Inside the VM, overlayfs merges the two layers via pivot_root. This reduces image preparation from ~1.4 seconds to ~9 milliseconds. Each sandbox gets a sparse 2GB writable ext4 overlay on top of the shared, read-only base template image. This reduces image preparation from ~1.4 seconds to ~9 milliseconds.

​
Firecracker snapshots

Persistent sandboxes use Firecracker’s snapshot/restore capability to freeze and thaw VM state. A full snapshot includes the VM’s memory contents and CPU register state, enabling sub-500ms restore times. Snapshot files are stored with restricted permissions (0600) since they contain memory contents.

​
Warm pool

Pre-booted VMs sit ready in a pool, already past the kernel boot sequence. When a sandbox is created, ZWRM atomically claims a warm VM (using FOR UPDATE SKIP LOCKED for safe concurrency) and transfers ownership. A background replenisher keeps the pool at target sizes.

​
VM sizes

Sandboxes can be created with any of these VM presets:
PresetvCPUsMemory
shared-cpu-1x1256 MB
shared-cpu-2x1512 MB
shared-cpu-4x21024 MB
performance-1x12048 MB
performance-2x24096 MB
performance-4x48192 MB
performance-8x816384 MB
The default size is shared-cpu-1x.

​
SDK support

Python and TypeScript SDKs wrap the sandbox API for programmatic use: 
from zwrmd import Sandbox

with Sandbox.create(template="python", timeout="10m") as sbx:
    sbx.upload("./data.csv", "/home/user/data.csv")
    result = sbx.execute("python3 analyze.py")
    print(result.stdout)
    sbx.download("/home/user/report.pdf", "./report.pdf")

import { Sandbox } from '@zwrmd/sdk';

const sbx = await Sandbox.create({ template: 'node', timeout: '10m' });
await sbx.upload('./data.json', '/home/user/data.json');
const result = await sbx.execute('node process.js');
console.log(result.stdout);
await sbx.destroy();

​
Next steps

Quickstart

Create your first sandbox in under a minute.

API reference

Full REST API documentation for sandbox endpoints.