Sandboxes

​

Key concepts

​

How sandboxes compare

​

Lifecycle

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

​

Copy-on-Write overlays

​

Firecracker snapshots

​

Warm pool

​

VM sizes

​

SDK support

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