feat(ai-sandbox, ai-sandbox-cloudflare): checkpoint at any time, and a provider over an app-owned container #2136
MergedAlemTuzlakmerged 8 commits into
main fromfeat/sandbox-checkpoints-containermerged by AlemTuzlak View on GitHubtanstack-source reviewed
packages/ai-sandbox/src/snapshots.ts line 783Outdated@@ -653,3 +779,5 @@653779 `${rootPath}/${entry.path}`,654780 getRequiredBlob(blobs, entry.blobKey),655781 )782+ if (plan.links.length > 0)783+ await execInRoot(handle, rootPath, linkCommand(plan.links), 'create links')- docs/sandbox/cloudflare-container.md line 44Outdated@@ -0,0 +24,21 @@24+25+react: @tanstack/ai @tanstack/ai-sandbox @tanstack/ai-sandbox-cloudflare @tanstack/ai-harness @tanstack/ai-openai @cloudflare/sandbox26+vue: @tanstack/ai @tanstack/ai-sandbox @tanstack/ai-sandbox-cloudflare @tanstack/ai-harness @tanstack/ai-openai @cloudflare/sandbox27+solid: @tanstack/ai @tanstack/ai-sandbox @tanstack/ai-sandbox-cloudflare @tanstack/ai-harness @tanstack/ai-openai @cloudflare/sandbox28+svelte: @tanstack/ai @tanstack/ai-sandbox @tanstack/ai-sandbox-cloudflare @tanstack/ai-harness @tanstack/ai-openai @cloudflare/sandbox29+preact: @tanstack/ai @tanstack/ai-sandbox @tanstack/ai-sandbox-cloudflare @tanstack/ai-harness @tanstack/ai-openai @cloudflare/sandbox30+angular: @tanstack/ai @tanstack/ai-sandbox @tanstack/ai-sandbox-cloudflare @tanstack/ai-harness @tanstack/ai-openai @cloudflare/sandbox31+octane: @tanstack/ai @tanstack/ai-sandbox @tanstack/ai-sandbox-cloudflare @tanstack/ai-harness @tanstack/ai-openai @cloudflare/sandbox32+vanilla: @tanstack/ai @tanstack/ai-sandbox @tanstack/ai-sandbox-cloudflare @tanstack/ai-harness @tanstack/ai-openai @cloudflare/sandbox33+34+<!-- ::end:tabs -->35+36+Declare the container and your Durable Object in `wrangler.jsonc`. The image must have `sandbox-shim` at `/usr/local/bin/sandbox-shim`, because `Files` runs it. The `cloudflare/sandbox` image has it. Match the image tag to your `@cloudflare/sandbox` version. See the [Cloudflare requirements](https://developers.cloudflare.com/sandbox/reference/#requirements).37+38+```jsonc39+{40+ "name": "agent-worker",41+ "main": "src/worker.ts",42+ "compatibility_date": "2026-05-01",43+ "compatibility_flags": ["nodejs_compat"],44+ "containers": [{ "class_name": "AgentContainer", "image": "./Dockerfile", "max_instances": 5 }],docs/sandbox/cloudflare-container.md line 82Outdated@@ -0,0 +62,21 @@62+ const container = this.ctx.container63+ if (!container) throw new Error('The container binding is not configured')64+ // Your rules. This container has no internet.65+ if (!container.running) container.start({ enableInternet: false })66+67+ const provider = containerSandbox({68+ container,69+ files: new Files(container),70+ })71+ return provider.create({ id: this.ctx.id.toString() })72+ }73+74+ async hello() {75+ const handle = await this.sandbox()76+ const result = await handle.process.exec('uname -a')77+ return result.stdout78+ }79+}80+```81+82+Export the Durable Object from your Worker, deploy, and call `hello()`. It returns the kernel line of your container.docs/sandbox/portable-snapshots-checkpoints.md lines 42 to 47Outdated@@ -0,0 +27,21 @@27+28+In production, use a durable checkpoint store and an R2 bucket for `blobs`. See [Store Checkpoints](./portable-snapshots-storage).29+30+Start the sandbox and restore the newest checkpoint. Do this before the agent runs, so nothing else writes to the sandbox during the restore.31+32+```ts33+// workspace.ts34+import { restoreSandboxCheckpoint } from '@tanstack/ai-sandbox'35+import { dockerSandbox } from '@tanstack/ai-sandbox-docker'36+import { blobs, checkpoints } from './checkpoint-stores'37+38+const docker = dockerSandbox({ image: 'node:22' })39+40+export async function startWorkspace(threadId: string) {41+ const handle = await docker.create({})42+ const restored = await restoreSandboxCheckpoint({43+ handle,44+ checkpoints,45+ blobs,46+ threadId,47+ })docs/sandbox/portable-snapshots-checkpoints.md line 103Outdated@@ -0,0 +83,21 @@83+ }, 60_000)84+ return () => clearInterval(timer)85+}86+```87+88+Call `checkpoint` where your loop finishes a step, or start `checkpointEveryMinute`. A capture reads the files one by one. For a consistent set of files, capture between steps, when no command writes to the workspace.89+90+Give the sandbox to the coding tools in `bind`:91+92+```ts93+// tools.ts94+import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'95+import { sandboxWorkspaceBackend } from '@tanstack/ai-sandbox/harness'96+import { checkpointEveryMinute } from './checkpoint'97+import { startWorkspace } from './workspace'98+99+export const tools = workspaceTools({100+ workspace: {101+ bind: async ({ run }) => {102+ const handle = await startWorkspace(run.threadId)103+ checkpointEveryMinute(handle, run.threadId)packages/ai-sandbox-cloudflare/src/container.ts lines 61 to 62Outdated@@ -0,0 +42,21 @@42+/** The options this provider passes to `container.exec`. */43+export interface ContainerExecOptions {44+ cwd?: string45+ env?: Record<string, string>46+ signal?: AbortSignal47+ stdin?: 'pipe'48+ stdout?: 'pipe'49+ stderr?: 'pipe'50+}51+52+/** A process that `container.exec` started. */53+export interface ContainerProcessLike {54+ readonly stdout: ReadableStream<Uint8Array> | null55+ readonly stderr: ReadableStream<Uint8Array> | null56+ readonly stdin: WritableStream<Uint8Array> | null57+ readonly exitCode: Promise<number>58+ kill(signal: number): void59+ output(): Promise<{60+ exitCode: number61+ stdout: Uint8Array62+ stderr: Uint8Arraypackages/ai-sandbox-cloudflare/src/container.ts lines 380 to 383Outdated@@ -0,0 +363,21 @@363+ const result = await child.output()364+ return {365+ exitCode: result.exitCode,366+ stdout: decoder.decode(result.stdout),367+ stderr: decoder.decode(result.stderr),368+ }369+ },370+ spawn: async (command, options) => {371+ const child = await container.exec(['sh', '-c', command], {372+ ...execOptions(options),373+ stdin: 'pipe',374+ stdout: 'pipe',375+ stderr: 'pipe',376+ })377+ // Read both streams all the time, so a full pipe never blocks the process.378+ const stdout = new OutputQueue()379+ const stderr = new OutputQueue()380+ const drained = Promise.all([381+ drain(child.stdout, stdout),382+ drain(child.stderr, stderr),383+ ])packages/ai-sandbox-cloudflare/src/container.ts line 497Outdated@@ -0,0 +477,21 @@477+ * container,478+ * files: new Files(container),479+ * backup: new DirectoryBackup(container, this.ctx.exports.DirectoryBackupGateway, {480+ * binding: 'BACKUPS',481+ * }),482+ * })483+ * const handle = await provider.create({ id: 'thread-1' })484+ * await handle.process.exec('npm test')485+ * ```486+ */487+export function containerSandbox(config: ContainerSandboxConfig) {488+ const { backup } = config489+ const workspaceRoot = config.workspaceRoot ?? DEFAULT_WORKSPACE_ROOT490+ const capabilities: SandboxCapabilities = {491+ fs: true,492+ exec: true,493+ env: true,494+ ports: false,495+ backgroundProcesses: true,496+ writableStdin: true,497+ killableProcesses: true,packages/ai-sandbox/src/checkpoint-store.ts line 774Outdated@@ -573,4 +768,7 @@573768 )574769 }575770 this.state.checkpoints.delete(checkpointId)576- if (checkpoint.parentCheckpointId) {771+ // The parent can be gone after `deleteCheckpoints`. Then the thread has no head.772+ if (773+ checkpoint.parentCheckpointId &&774+ this.state.checkpoints.has(checkpoint.parentCheckpointId)packages/ai-sandbox/src/checkpoint-store.ts lines 814 to 817Outdated@@ -580,0 +797,21 @@797+ throw new SandboxCheckpointWriterLostError(798+ 'Checkpoint writer thread does not match operation thread',799+ )800+ }801+ this.assertWriter(writer, threadId)802+ // Walk the parent chain from the head, newest first. The seen set stops803+ // the walk when a removed id was used again by a newer checkpoint.804+ const chain: Array<SandboxCheckpoint> = []805+ const seen = new Set<string>()806+ let id = this.state.heads.get(threadId) ?? null807+ while (id !== null && !seen.has(id)) {808+ seen.add(id)809+ const checkpoint = this.state.checkpoints.get(id)810+ if (!checkpoint || checkpoint.threadId !== threadId) break811+ chain.push(checkpoint)812+ id = checkpoint.parentCheckpointId813+ }814+ const removed = chain.slice(keep).reverse()815+ for (const checkpoint of removed) {816+ this.state.checkpoints.delete(checkpoint.id)817+ this.releaseReferences(checkpoint)packages/ai-sandbox/src/checkpoints.ts lines 127 to 128Outdated@@ -0,0 +108,21 @@108+ handle,109+ { blobs, workspaceRoot: input.workspaceRoot },110+ input.policy,111+ input.secrets,112+ )113+ signal?.throwIfAborted()114+ const head = await checkpoints.getHead(threadId)115+ signal?.throwIfAborted()116+ const checkpoint: SandboxCheckpoint = {117+ id: input.id ?? `checkpoint-${crypto.randomUUID()}`,118+ threadId,119+ parentCheckpointId: head,120+ createdAt: Date.now(),121+ reason: label === undefined ? 'automatic' : 'named',122+ ...(label === undefined ? {} : { label }),123+ files: files.files,124+ conversation: input.conversation ?? [],125+ artifacts: [],126+ }127+ await throwIfLost()128+ await checkpoints.append({ checkpoint, expectedHeadId: head, writer })packages/ai-sandbox/src/middleware.ts line 1263Outdated@@ -1213,3 +1259,5 @@12131259 // the sandbox is about to be destroyed or merely detached, or the final12141260 // file's diff is dropped.12151261 await drainWatcher(state, 'abort')1262+ // Before the lease stops and before any destroy, while the files exist.1263+ await checkpointFailedRun(definition, state, ctx, 'abort')packages/ai-sandbox/src/snapshots.ts lines 252 to 261Outdated@@ -220,0 +241,21 @@241+ // folder, not the arguments, to its own files.242+ const folder = posix.dirname(absolute)243+ const { exitCode, stdout, stderr } = await handle.process.exec(244+ `readlink -- ${shellQuote(posix.basename(absolute))}`,245+ { cwd: folder },246+ )247+ if (exitCode !== 0)248+ throw new SandboxSnapshotError(249+ 'SANDBOX_SNAPSHOT_INVALID_WORKSPACE',250+ `Cannot read the link '${relative}': ${stderr.trim()}`,251+ )252+ const target = stdout.replace(/\n$/, '')253+ const fromRoot = posix.relative(254+ posix.resolve(rootPath),255+ posix.resolve(folder, target),256+ )257+ const isOutside = fromRoot === '..' || fromRoot.startsWith('../')258+ if (isOutside)259+ throw new SandboxSnapshotError(260+ 'SANDBOX_SNAPSHOT_UNSUPPORTED_ENTRY',261+ `The link '${relative}' points outside the workspace. Exclude it from the snapshot.`,packages/ai-sandbox/src/snapshots.ts lines 253 to 257Outdated@@ -220,0 +237,21 @@237+ absolute: string,238+ relative: string,239+) {240+ // Run in the folder of the link with a relative name: the sandbox maps the241+ // folder, not the arguments, to its own files.242+ const folder = posix.dirname(absolute)243+ const { exitCode, stdout, stderr } = await handle.process.exec(244+ `readlink -- ${shellQuote(posix.basename(absolute))}`,245+ { cwd: folder },246+ )247+ if (exitCode !== 0)248+ throw new SandboxSnapshotError(249+ 'SANDBOX_SNAPSHOT_INVALID_WORKSPACE',250+ `Cannot read the link '${relative}': ${stderr.trim()}`,251+ )252+ const target = stdout.replace(/\n$/, '')253+ const fromRoot = posix.relative(254+ posix.resolve(rootPath),255+ posix.resolve(folder, target),256+ )257+ const isOutside = fromRoot === '..' || fromRoot.startsWith('../')packages/ai-sandbox/src/snapshots.ts line 735Outdated@@ -610,0 +715,21 @@715+// ponytail: one shell command for all links and one for all modes. A very716+// large workspace can hit the shell argument limit; split into chunks then.717+function linkCommand(links: ReadonlyArray<PlannedLink>) {718+ return links719+ .map(720+ (link) => `ln -s -- ${shellQuote(link.target)} ${shellQuote(link.path)}`,721+ )722+ .join(' && ')723+}724+725+function chmodCommand(files: ReadonlyArray<PlannedFile>) {726+ const pathsByMode = new Map<number, Array<string>>()727+ for (const file of files) {728+ if (file.mode === undefined) continue729+ const paths = pathsByMode.get(file.mode) ?? []730+ paths.push(shellQuote(file.path))731+ pathsByMode.set(file.mode, paths)732+ }733+ return Array.from(734+ pathsByMode,735+ ([mode, paths]) => `chmod ${mode.toString(8)} -- ${paths.join(' ')}`,
AlemTuzlak pushed7b96196
tanstack-source reviewed
packages/ai-sandbox/src/snapshots.ts line 487Outdated@@ -412,8 +469,19 @@412469 )413470 throw new SandboxSnapshotError(414471 'SANDBOX_SNAPSHOT_INVALID_PATH',415472 `Invalid file entry '${path}'`,416473 )417- paths.set(path, { path, kind: 'file', blobKey, size })474+ paths.set(path, { path, kind: 'file', blobKey, size, mode })418475 } else if (entry.kind === 'dir') paths.set(path, { path, kind: 'dir' })419- else476+ else if (entry.kind === 'symlink') {477+ const { target } = entry478+ if (479+ typeof target !== 'string' ||480+ target.length === 0 ||481+ target.includes('\0')482+ )483+ throw new SandboxSnapshotError(484+ 'SANDBOX_SNAPSHOT_INVALID_PATH',485+ `Invalid symlink entry '${path}'`,486+ )487+ paths.set(path, { path, kind: 'symlink', target })packages/ai-sandbox-cloudflare/src/container.ts line 497Outdated@@ -0,0 +477,21 @@477+ * container,478+ * files: new Files(container),479+ * backup: new DirectoryBackup(container, this.ctx.exports.DirectoryBackupGateway, {480+ * binding: 'BACKUPS',481+ * }),482+ * })483+ * const handle = await provider.create({ id: 'thread-1' })484+ * await handle.process.exec('npm test')485+ * ```486+ */487+export function containerSandbox(config: ContainerSandboxConfig) {488+ const { backup } = config489+ const workspaceRoot = config.workspaceRoot ?? DEFAULT_WORKSPACE_ROOT490+ const capabilities: SandboxCapabilities = {491+ fs: true,492+ exec: true,493+ env: true,494+ ports: false,495+ backgroundProcesses: true,496+ writableStdin: true,497+ killableProcesses: true,
Applied a fix from CI4bf165d
- packages/ai-sandbox-blaxel/src/handle.ts line 563Outdated@@ -544,10 +548,16 @@544548 ' for __tanstack_pid in "${__tanstack_command:-}" "${__tanstack_stdout_reader:-}" "${__tanstack_stderr_reader:-}"; do',545549 ' if [ -n "$__tanstack_pid" ]; then kill -TERM -- "-$__tanstack_pid" 2>/dev/null || true; fi',546550 ' done',547- ' sleep 0.1',548- ' for __tanstack_pid in "${__tanstack_command:-}" "${__tanstack_stdout_reader:-}" "${__tanstack_stderr_reader:-}"; do',549- ' if [ -n "$__tanstack_pid" ]; then kill -KILL -- "-$__tanstack_pid" 2>/dev/null || true; fi',550- ' done',551+ // Wait for the groups to exit (and reap their helpers) before SIGKILL,552+ // so a racey group-KILL cannot leave dd zombies that keep the pgid alive.553+ ' (',554+ ' sleep 1',555+ ' for __tanstack_pid in "${__tanstack_command:-}" "${__tanstack_stdout_reader:-}" "${__tanstack_stderr_reader:-}"; do',556+ ' if [ -n "$__tanstack_pid" ]; then kill -KILL -- "-$__tanstack_pid" 2>/dev/null || true; fi',557+ ' done',558+ ' ) &',559+ ' __tanstack_watchdog=$!',551560 ' for __tanstack_pid in "${__tanstack_command:-}" "${__tanstack_stdout_reader:-}" "${__tanstack_stderr_reader:-}"; do',552561 ' if [ -n "$__tanstack_pid" ]; then wait "$__tanstack_pid" 2>/dev/null || true; fi',553562 ' done',563+ ' kill "$__tanstack_watchdog" 2>/dev/null || true',
tanstack-source reviewed
packages/ai-sandbox/src/snapshots.ts line 756Outdated@@ -630 +756 @@630756 const current = await scanDestination(handle, policy, rootPath)packages/ai-sandbox-cloudflare/src/container.ts line 497Outdated@@ -0,0 +477,21 @@477+ * container,478+ * files: new Files(container),479+ * backup: new DirectoryBackup(container, this.ctx.exports.DirectoryBackupGateway, {480+ * binding: 'BACKUPS',481+ * }),482+ * })483+ * const handle = await provider.create({ id: 'thread-1' })484+ * await handle.process.exec('npm test')485+ * ```486+ */487+export function containerSandbox(config: ContainerSandboxConfig) {488+ const { backup } = config489+ const workspaceRoot = config.workspaceRoot ?? DEFAULT_WORKSPACE_ROOT490+ const capabilities: SandboxCapabilities = {491+ fs: true,492+ exec: true,493+ env: true,494+ ports: false,495+ backgroundProcesses: true,496+ writableStdin: true,497+ killableProcesses: true,
AlemTuzlak pushede35dfac
github-actions[bot](GitHub profile, opens in a new tab) assignedtombeckenham
github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: maintainer
tanstack-source reviewed
packages/ai-sandbox/src/snapshots.ts line 487@@ -412,8 +469,19 @@412469 )413470 throw new SandboxSnapshotError(414471 'SANDBOX_SNAPSHOT_INVALID_PATH',415472 `Invalid file entry '${path}'`,416473 )417- paths.set(path, { path, kind: 'file', blobKey, size })474+ paths.set(path, { path, kind: 'file', blobKey, size, mode })418475 } else if (entry.kind === 'dir') paths.set(path, { path, kind: 'dir' })419- else476+ else if (entry.kind === 'symlink') {477+ const { target } = entry478+ if (479+ typeof target !== 'string' ||480+ target.length === 0 ||481+ target.includes('\0')482+ )483+ throw new SandboxSnapshotError(484+ 'SANDBOX_SNAPSHOT_INVALID_PATH',485+ `Invalid symlink entry '${path}'`,486+ )487+ paths.set(path, { path, kind: 'symlink', target })packages/ai-sandbox-cloudflare/src/container.ts line 497@@ -0,0 +477,21 @@477+ * container,478+ * files: new Files(container),479+ * backup: new DirectoryBackup(container, this.ctx.exports.DirectoryBackupGateway, {480+ * binding: 'BACKUPS',481+ * }),482+ * })483+ * const handle = await provider.create({ id: 'thread-1' })484+ * await handle.process.exec('npm test')485+ * ```486+ */487+export function containerSandbox(config: ContainerSandboxConfig) {488+ const { backup } = config489+ const workspaceRoot = config.workspaceRoot ?? DEFAULT_WORKSPACE_ROOT490+ const capabilities: SandboxCapabilities = {491+ fs: true,492+ exec: true,493+ env: true,494+ ports: false,495+ backgroundProcesses: true,496+ writableStdin: true,497+ killableProcesses: true,AlemTuzlak merged this701ec9c
AlemTuzlak merged this701ec9c
AlemTuzlak closed this
Sign in to join this conversation.
🦋 Changeset detected#
Latest commit: e35dfac38cca44fa5d321b68362a0bc13496df9b
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 2 packages
Not sure what this means? Click here to learn what changesets are.
Click here if you're a maintainer who wants to add another changeset to this PR