Save a Named Version | TanStack AI Docs

snapshots.save writes the live sandbox to a named checkpoint. Automatic saves still run at the end of each completed run.

The method needs a live, reusable sandbox for the thread. A lifecycle with reuse: 'none' cannot create a named checkpoint.

Keep this route on the server. Read the owner from the session. If the owner cannot access the thread, return 404. Then call snapshots.save.

When you create the snapshots object, bind sandbox and instances. You can also pass them on save. Use the same instance store that withSandbox uses. See Keep Files After Reload.

import { requireSession } from './auth'
import { snapshots } from './sandbox-server'

export async function POST(request: Request) {
  const session = await requireSession(request)
  let payload: unknown
  try {
    payload = await request.json()
  } catch {
    return new Response('Invalid request', { status: 400 })
  }
  if (
    payload === null ||
    typeof payload !== 'object' ||
    !('threadId' in payload) ||
    !('runId' in payload) ||
    !('label' in payload) ||
    typeof payload.threadId !== 'string' ||
    typeof payload.runId !== 'string' ||
    typeof payload.label !== 'string'
  ) {
    return new Response('Invalid request', { status: 400 })
  }
  const threadId = payload.threadId
  const runId = payload.runId
  const label = payload.label
  if (!(await session.canAccessThread(threadId))) {
    return new Response('Not found', { status: 404 })
  }

  const checkpoint = await snapshots.save({
    threadId,
    runId,
    label,
    tenant: { userId: session.userId },
  })
  return Response.json({ checkpointId: checkpoint.id, label: checkpoint.label })
}

The client sends its request to this route. It does not call snapshots.save or read the persistence stores.

export async function saveCheckpoint(
  threadId: string,
  runId: string,
  label: string,
) {
  const response = await fetch('/api/snapshots/save', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ threadId, runId, label }),
  })
  if (!response.ok) throw new Error('Could not save checkpoint')
  return response.json()
}

A named checkpoint stays available for a read or a selected fork. Automatic restore still uses the latest checkpoint. See Branch From a Version to copy one selected checkpoint into a new thread.

When the agent must call save itself, use Let the Agent Save and Fork.