SDK Reference

Installation

npm install @lelantos-ai/sdk

LelantosClient

The main entry point. All API operations go through this class.

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

const client = new LelantosClient({
  apiKey: "lel_...",
  baseURL: "https://api.lelantos.ai", // optional, this is the default
  timeout: 30000,                      // optional, request timeout in ms
});

Sandboxes

`createSandbox(opts)` → `SandboxHandle`

Create a new sandbox. Returns a SandboxHandle with convenience methods.

const sandbox = await client.createSandbox({
  templateID: "base",
  timeout: 3600,                        // optional, seconds (default: 86400)
  metadata: { project: "demo" },        // optional
  envVars: { NODE_ENV: "production" },  // optional
});

`listSandboxes(metadata?)` → `ListedSandbox[]`

List all running sandboxes. Optionally filter by metadata.

`listSandboxesV2(opts?)` → `PaginatedResult<ListedSandbox>`

Paginated sandbox list. Returns data array and optional nextToken.

const page = await client.listSandboxesV2({ limit: 10 });
console.log(page.data);      // ListedSandbox[]
console.log(page.nextToken);  // string | undefined

`getSandbox(sandboxID)` → `SandboxDetail`

Get full details including state, resources, and metadata.

`killSandbox(sandboxID)` → `void`

Immediately terminate a sandbox.

`pauseSandbox(sandboxID)` → `void`

Pause a running sandbox. Resume later with resumeSandbox.

`resumeSandbox(sandboxID, opts?)` → `Sandbox`

Resume a paused sandbox.

`setSandboxTimeout(sandboxID, timeout)` → `void`

Set the sandbox timeout in seconds.

`refreshSandbox(sandboxID, duration)` → `void`

Extend sandbox lifetime by duration seconds.

Lifecycle Events

`getSandboxLogs(sandboxID, opts?)` → `SandboxLogs`

Retrieve lifecycle events for a sandbox. Works for both live and historical sandboxes — you can query events even after a sandbox has been killed.

const logs = await client.getSandboxLogs("sandbox-id", {
  start: 0,   // optional, offset for pagination
  limit: 100, // optional, max events to return (default: 1000)
});

for (const ev of logs.logs) {
  console.log(`[${ev.timestamp}] ${ev.line}`);
}
// [2026-03-06T10:00:52Z] sandbox.lifecycle.created
// [2026-03-06T10:01:15Z] sandbox.lifecycle.paused
// [2026-03-06T10:05:30Z] sandbox.lifecycle.resumed
// [2026-03-06T10:10:00Z] sandbox.lifecycle.killed

Available event types:

sandbox.lifecycle.created — sandbox was created
sandbox.lifecycle.running — sandbox started running on a node
sandbox.lifecycle.paused — sandbox was paused
sandbox.lifecycle.resumed — sandbox was resumed
sandbox.lifecycle.killed — sandbox was killed via API
sandbox.lifecycle.stopped — sandbox stopped (node confirmed)
sandbox.lifecycle.error — sandbox encountered an error

Metrics

`getSandboxMetrics(sandboxID)` → `SandboxMetric[]`

Get sandbox resource metrics. Currently returns allocated resources (CPU count, memory, disk).

Real-time CPU/memory usage collection is coming soon.

Files

`uploadFile(sandboxID, path, content)` → `void`

Upload a file to the sandbox filesystem.

await client.uploadFile("sandbox-id", "/home/user/data.json", JSON.stringify({ key: "value" }));

`downloadFile(sandboxID, path)` → `ArrayBuffer`

Download a file from the sandbox filesystem.

const buf = await client.downloadFile("sandbox-id", "/home/user/data.json");
const text = new TextDecoder().decode(buf);

Build a new template from a Dockerfile. The build runs asynchronously — poll build status with getTemplateBuildStatus. Optionally set cpuCount (1–8) and memoryMB (128–8192). Defaults: 2 vCPU, 512 MB.

const template = await client.createTemplate({
  dockerfile: "FROM python:3.12\nRUN pip install numpy",
  alias: "python-numpy",  // optional human-readable name
  cpuCount: 4,             // optional (default: 2)
  memoryMB: 2048,          // optional (default: 512)
});

`listTemplates(teamID?)` → `Template[]`

List all templates accessible to the team.

`getTemplate(templateID)` → `Template`

Get template details including cpuCount, memoryMB, build count, and spawn count.

`rebuildTemplate(templateID, opts)` → `Template`

Rebuild an existing template with a new Dockerfile.

`deleteTemplate(templateID)` → `void`

Delete a template.

`updateTemplate(templateID, opts)` → `void`

Update template settings (e.g. { public: true }).

`getTemplateBuildStatus(templateID, buildID)` → `TemplateBuildInfo`

Check the status of a template build.

const status = await client.getTemplateBuildStatus(template.templateID, template.buildID);
// status.status: "building" | "waiting" | "ready" | "error"
// status.logs: string[] (build output)

Snapshots

`createSnapshot(sandboxID, name?)` → `SnapshotInfo`

Create a point-in-time snapshot of a running sandbox.

`listSnapshots(opts?)` → `PaginatedResult<SnapshotInfo>`

List snapshots, optionally filtered by sandbox ID.

API Keys

`listAPIKeys()` → `TeamAPIKey[]`

List API keys for the team.

`createAPIKey(name)` → `CreatedTeamAPIKey`

Create a new API key. The apiKey field is only returned once.

Store the returned apiKey value immediately. It cannot be retrieved again after creation.

`deleteAPIKey(apiKeyID)` → `void`

Revoke an API key.

SandboxHandle

Returned by createSandbox(). Wraps a sandbox ID and provides convenience methods that delegate to the client.

Method	Returns	Description
`getDetails()`	`SandboxDetail`	Full sandbox details
`kill()`	`void`	Terminate the sandbox
`pause()`	`void`	Pause the sandbox
`resume(timeout?)`	`Sandbox`	Resume the sandbox
`setTimeout(seconds)`	`void`	Set timeout
`refresh(seconds)`	`void`	Extend lifetime
`getLogs(opts?)`	`SandboxLogs`	Lifecycle events
`getMetrics()`	`SandboxMetric[]`	Resource metrics
`uploadFile(path, content)`	`void`	Upload a file
`downloadFile(path)`	`ArrayBuffer`	Download a file
`snapshot(name?)`	`SnapshotInfo`	Create snapshot
`getURL(port?)`	`string \| null`	Sandbox URL for HTTP access

Error Handling

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

try {
  await client.killSandbox("nonexistent");
} catch (err) {
  if (err instanceof LelantosError) {
    console.log(err.status);   // 404
    console.log(err.message);  // "sandbox not found"
  }
  if (err instanceof TimeoutError) {
    console.log("Request timed out");
  }
}