# Run management
URL: /docs/core/concepts/run-management

List, inspect, resume, and delete past sandbox sessions from the ledger.



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

## List all sessions [#list-all-sessions]

```ts
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 [#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 [#filter-by-name]

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

## Filter by status or date [#filter-by-status-or-date]

```ts
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 [#get-a-single-session]

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

## Delete a session [#delete-a-session]

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

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

## Resume from a checkpoint [#resume-from-a-checkpoint]

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

```ts
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 [#typical-cleanup-pattern]

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

```ts
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);
  }
}
```