Sandbox Lifecycle

Overview

A sandbox is an isolated Firecracker microVM with its own CPU, memory, disk, and network. Sandboxes are created from templates and follow a well-defined lifecycle.

State Machine

Sandboxes transition through the following states:

created --> running --> paused --> running --> killed
                  |                              ^
                  |                              |
                  +------------------------------+
                  |
                  v
               stopped (timeout expired)

Creating a Sandbox

import { LelantosClient } from "@lelantos-ai/sdk";

const client = new LelantosClient({
  apiKey: process.env.LELANTOS_API_KEY!,
});

const sandbox = await client.createSandbox({
  templateID: "base",
});

console.log("Sandbox ID:", sandbox.sandboxID);
console.log("URL:", sandbox.getURL());

curl -X POST https://api.lelantos.ai/sandboxes \
  -H "X-API-Key: lel_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"templateID": "base"}'

Sandbox Details

Retrieve the current state and metadata of a sandbox:

const details = await sandbox.getDetails();
console.log("State:", details.status);
console.log("Template:", details.templateID);
console.log("Created:", details.startedAt);

curl https://api.lelantos.ai/sandboxes/SANDBOX_ID \
  -H "X-API-Key: lel_your_key_here"

Pause & Resume

Pausing a sandbox suspends the microVM, preserving its full state (memory, disk, running processes). Resume restores it to the exact same state.

// Pause to save resources
await sandbox.pause();

// Resume when needed
await sandbox.resume();

Killing a Sandbox

Explicitly terminate a sandbox when you are done with it:

await sandbox.kill();

curl -X DELETE https://api.lelantos.ai/sandboxes/SANDBOX_ID \
  -H "X-API-Key: lel_your_key_here"

Listing Sandboxes

List all sandboxes for your team, optionally filtering by metadata:

const sandboxes = await client.listSandboxes();
for (const sb of sandboxes) {
  console.log(sb.sandboxID, sb.status);
}

Default Resources

Every sandbox is provisioned with the following default resources:

Resource allocation is configured at the template level. All sandboxes created from a template inherit its resource settings.

Warm Pool

Lelantos maintains a warm pool of 30 pre-warmed sandboxes based on the base template. When you create a sandbox from the base template, one is assigned from the pool in under 10ms instead of booting a new microVM.

Sub-pages