mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-15 18:01:30 +00:00
441083ea2a
- Fix insertEvent call in client.ts to pass sessionId as first argument - Update Daytona provider create options to use Partial type (image has default) - Update StrictUniqueSessionPersistDriver in tests to match new insertEvent signature - Sync persist packages, openapi spec, and docs with upstream changes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
121 lines
3.4 KiB
Text
121 lines
3.4 KiB
Text
---
|
|
title: "Persisting Sessions"
|
|
description: "Choose and configure session persistence for the TypeScript SDK."
|
|
icon: "database"
|
|
---
|
|
|
|
The TypeScript SDK uses a `SessionPersistDriver` to store session records and event history.
|
|
If you do not provide one, the SDK uses in-memory storage.
|
|
With persistence enabled, sessions can be restored after runtime/session loss. See [Session Restoration](/session-restoration).
|
|
|
|
Each driver stores:
|
|
|
|
- `SessionRecord` (`id`, `agent`, `agentSessionId`, `lastConnectionId`, `createdAt`, optional `destroyedAt`, optional `sandboxId`, optional `sessionInit`)
|
|
- `SessionEvent` (`id`, `eventIndex`, `sessionId`, `connectionId`, `sender`, `payload`, `createdAt`)
|
|
|
|
## Persistence drivers
|
|
|
|
### In-memory (built-in)
|
|
|
|
Best for local dev and ephemeral workloads. No extra dependencies required.
|
|
|
|
```ts
|
|
import { InMemorySessionPersistDriver, SandboxAgent } from "sandbox-agent";
|
|
|
|
const persist = new InMemorySessionPersistDriver({
|
|
maxSessions: 1024,
|
|
maxEventsPerSession: 500,
|
|
});
|
|
|
|
const sdk = await SandboxAgent.connect({
|
|
baseUrl: "http://127.0.0.1:2468",
|
|
persist,
|
|
});
|
|
```
|
|
|
|
### SQLite
|
|
|
|
Best for local/server Node apps that need durable storage without a DB server.
|
|
|
|
```bash
|
|
npm install better-sqlite3
|
|
```
|
|
|
|
```ts
|
|
import { SandboxAgent } from "sandbox-agent";
|
|
import { SQLiteSessionPersistDriver } from "./persist.ts";
|
|
|
|
const persist = new SQLiteSessionPersistDriver({
|
|
filename: "./sandbox-agent.db",
|
|
});
|
|
|
|
const sdk = await SandboxAgent.connect({
|
|
baseUrl: "http://127.0.0.1:2468",
|
|
persist,
|
|
});
|
|
```
|
|
|
|
See the [full SQLite example](https://github.com/nichochar/sandbox-agent/tree/main/examples/persist-sqlite) for the complete driver implementation you can copy into your project.
|
|
|
|
### Postgres
|
|
|
|
Use when you already run Postgres and want shared relational storage.
|
|
|
|
```bash
|
|
npm install pg
|
|
```
|
|
|
|
```ts
|
|
import { SandboxAgent } from "sandbox-agent";
|
|
import { PostgresSessionPersistDriver } from "./persist.ts";
|
|
|
|
const persist = new PostgresSessionPersistDriver({
|
|
connectionString: process.env.DATABASE_URL,
|
|
schema: "public",
|
|
});
|
|
|
|
const sdk = await SandboxAgent.connect({
|
|
baseUrl: "http://127.0.0.1:2468",
|
|
persist,
|
|
});
|
|
```
|
|
|
|
See the [full Postgres example](https://github.com/nichochar/sandbox-agent/tree/main/examples/persist-postgres) for the complete driver implementation you can copy into your project.
|
|
|
|
### IndexedDB (browser)
|
|
|
|
Best for browser apps that should survive reloads. See the [Inspector source](https://github.com/nichochar/sandbox-agent/tree/main/frontend/packages/inspector/src/persist-indexeddb.ts) for a complete IndexedDB driver you can copy into your project.
|
|
|
|
### Rivet
|
|
|
|
Recommended for sandbox orchestration with actor state. See [Multiplayer](/multiplayer) for a full Rivet actor example with inline persistence.
|
|
|
|
### Custom driver
|
|
|
|
Implement `SessionPersistDriver` for custom backends.
|
|
|
|
```ts
|
|
import type { SessionPersistDriver } from "sandbox-agent";
|
|
|
|
class MyDriver implements SessionPersistDriver {
|
|
async getSession(id) { return undefined; }
|
|
async listSessions(request) { return { items: [] }; }
|
|
async updateSession(session) {}
|
|
async listEvents(request) { return { items: [] }; }
|
|
async insertEvent(sessionId, event) {}
|
|
}
|
|
```
|
|
|
|
## Replay controls
|
|
|
|
`SandboxAgent.connect(...)` supports:
|
|
|
|
- `replayMaxEvents` (default `50`)
|
|
- `replayMaxChars` (default `12000`)
|
|
|
|
These cap replay size when restoring sessions.
|
|
|
|
## Related docs
|
|
|
|
- [SDK Overview](/sdk-overview)
|
|
- [Session Restoration](/session-restoration)
|