Run management

Every sandbox session is stored in the ledger. client.sandboxes gives you full access to that history.

List all sessions

const sessions = await client.sandboxes.list();

for (const session of sessions) {
  console.log(session.sandboxId, session.name, session.status, session.execCount);
}

Sessions are returned newest first.

SandboxDetails

Each session has:

Field	Type	Description
`sandboxId`	`string`	OpenSandbox container ID
`name`	`string`	User-provided name (or auto-generated)
`status`	`SandboxStatus`	`"running"` or `"completed"` — that's the full set; there is no `"failed"` or `"cancelled"` status
`startedAt`	`number`	Unix timestamp (ms) of `sandbox.created` event
`completedAt`	`number?`	Unix timestamp (ms) of `sandbox.closed` event
`execCount`	`number`	Number of completed execs

There is no error field on SandboxDetails — a sandbox that failed to start doesn't get a ledger entry with a "failed" status; it just never has a sandbox.created event to derive one from.

Filter by name

// All sessions with a given name
const sessions = await client.sandboxes.listByName("my-ci-job");

Filter by status or date

import { SandboxStatus } from "@alineo-labs/sandbox";

// Only running sessions
const running = await client.sandboxes.list({ status: SandboxStatus.Running });

// Sessions started before a timestamp
const old = await client.sandboxes.list({ before: Date.now() - 86_400_000 });

// Limit results
const recent = await client.sandboxes.list({ limit: 10 });

Get a single session

const session = await client.sandboxes.get("my-job", sandboxId);
if (!session) {
  console.log("not found");
}

Delete a session

Removes all ledger events for the session. Does not affect the container (which is already closed):

await client.sandboxes.delete("my-job", sandboxId);

Resume from a checkpoint

If a session was checkpointed before it was closed, you can restore it:

const sbResume = await client.resume(sandboxId);
try {
  // Execs before the checkpoint are replayed from cache
  await sbResume.exec("pip install -q requests && echo installed");
  // Execs after the checkpoint run live on the restored container
  await sbResume.exec("python3 script.py").pipe(process.stdout);
} finally {
  await sbResume.close();
}

client.resume() throws SandboxClientError (status 404) if no session with that ID is found in the ledger, and if no checkpoint exists in the session's history.

Typical cleanup pattern

For scripts that accumulate many sessions, periodically clean up completed runs:

import { SandboxStatus } from "@alineo-labs/sandbox";

const completed = await client.sandboxes.list({ status: SandboxStatus.Completed });

for (const session of completed) {
  const ageMs = Date.now() - session.startedAt;
  if (ageMs > 7 * 24 * 60 * 60 * 1000) {
    // older than 7 days
    await client.sandboxes.delete(session.name, session.sandboxId);
  }
}

Run management

On this page