Skip to main content
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. Each driver stores:
  • SessionRecord (id, agent, agentSessionId, lastConnectionId, createdAt, optional destroyedAt, optional sandboxId, optional sessionInit, optional configOptions, optional modes)
  • SessionEvent (id, eventIndex, sessionId, connectionId, sender, payload, createdAt)

​
Persistence drivers

​
Rivet

Recommended for sandbox orchestration with actor state. See Multiplayer for a full Rivet actor example with persistence in actor state.

​
IndexedDB (browser)

Best for browser apps that should survive reloads. See the Inspector source for a complete IndexedDB driver you can copy into your project.

​
In-memory (built-in)

Best for local dev and ephemeral workloads. No extra dependencies required. 
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. 
npm install better-sqlite3

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 for the complete driver implementation you can copy into your project.

​
Postgres

Use when you already run Postgres and want shared relational storage. 
npm install pg

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 for the complete driver implementation you can copy into your project.

​
Custom driver

Implement SessionPersistDriver for custom backends. 
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.