Sandboxes

A sandbox is an isolated Firecracker micro-VM you spin up on demand, run code inside, and tear down when you’re done. Each one is a full Linux environment with its own filesystem, network, and process namespace — booted in milliseconds, not minutes.

Sandboxes are the compute primitive behind AI agents, code interpreters, evals, and CI-style jobs on Lizard. Where a service is a long-lived deployment tied to a repo, a sandbox is ephemeral, programmatic, and disposable — create a sandbox for each task within the capacity available to your account.

import { Sandbox } from '@lizard-build/sdk';
 
const sandbox = await Sandbox.create('base', { project: 'my-project' });
const { stdout } = await sandbox.process.exec('echo "hello from Lizard"');
console.log(stdout);            // hello from Lizard
await sandbox.kill();

When to use a sandbox

Once an agent has produced a working app inside a sandbox, you can promote it to a persistent service with lizard up — no Dockerfile required.

What makes them fast

• Firecracker micro-VMs — a separate Linux guest for each sandbox. App runtimes have different isolation rules. Hardware virtualization separates the guest from the host. Control credentials and network access for code you do not trust.
• Pause and resume — pausing freezes the micro-VM’s vCPUs. Memory, filesystem, and running processes are kept as they are, so resume picks up exactly where it left off — no re-installing packages or re-warming caches. This is what makes long-running agent sessions survive across separate invocations. State is held in the host’s memory rather than written to disk, so it does not survive a host failure. See pause & resume.
• Boot from a template — every node pre-builds a golden snapshot per template, so create is a restore, not a cold boot.

Templates

A sandbox boots from a template (also called a snapshot in the dashboard). Two are built in:

base is the default. The public create API accepts these two template names. It does not expose a custom-template upload flow.

Lifecycle

A sandbox moves between three states:

create ──▶ running ⇄ paused ──▶ stopped
                              (killed or expired)

• running — the guest can execute commands, work with files, and serve exposed ports.
• paused — vCPUs stop. Guest memory and process state remain on the host; this is not a durable snapshot or a backup.
• stopped — the sandbox ended through deletion or expiration. Its local filesystem is no longer available.

The SDK sends a five-minute lifetime by default. The raw create API accepts timeoutMs: 0 for no expiration. Pass an explicit timeout when a script must behave the same across clients, and release the sandbox when the task ends. Commands do not reset the lifetime.

Pause is intended to preserve the remaining running time. Check the current lifecycle issue before relying on a pause longer than the original deadline. Persistent files belong in a volume; a paused guest does not survive host failure.

Resources & limits

Every sandbox runs at a fixed 4 vCPU / 4096 MiB RAM. The public create API has no per-sandbox size setting. Each sandbox inherits its template’s resources.

Region is chosen automatically from available capacity; in the dashboard you can pin one. Do not assume that app quotas and sandbox capacity use the same enforcement rules. See limits.

Ways to drive sandboxes

Updated September 7, 2026