Installation & Usage

Install this tool and use it with the AI SDK

1. Install the package

npm install @tpmjs/tools-sprites-checkpoint-restore

pnpm add @tpmjs/tools-sprites-checkpoint-restore

yarn add @tpmjs/tools-sprites-checkpoint-restore

bun add @tpmjs/tools-sprites-checkpoint-restore

deno add npm:@tpmjs/tools-sprites-checkpoint-restore

2. Import the tool

import { spritesCheckpointRestoreTool } from '@tpmjs/tools-sprites-checkpoint-restore';

3. Use with AI SDK

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { spritesCheckpointRestoreTool } from '@tpmjs/tools-sprites-checkpoint-restore';

const result = await generateText({
  model: openai('gpt-4o'),
  tools: { spritesCheckpointRestoreTool },
  prompt: 'Your prompt here...',
});

console.log(result.text);

Parameters

Available configuration options

Auto-extracted

name

Required

Type: string

Name of the sprite to restore

checkpointId

Required

Type: string

ID of the checkpoint to restore to

Schema extracted: 1/16/2026, 3:45:35 AM

README

@tpmjs/sprites-checkpoint-restore

Restore a sprite to a previous checkpoint state, reverting all filesystem changes.

Installation

npm install @tpmjs/sprites-checkpoint-restore

Requirements

SPRITES_TOKEN environment variable - Get your token from https://sprites.dev

Usage

import { spritesCheckpointRestoreTool } from '@tpmjs/sprites-checkpoint-restore';

const result = await spritesCheckpointRestoreTool.execute({
  name: 'my-sandbox',
  checkpointId: 'chk_abc123'
});

console.log(result);
// {
//   restored: true,
//   checkpointId: 'chk_abc123',
//   sprite: {
//     name: 'my-sandbox',
//     status: 'running',
//     createdAt: '2024-01-15T10:30:00Z'
//   }
// }

Input Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	Name of the sprite to restore
`checkpointId`	`string`	Yes	ID of the checkpoint to restore to

Output

Field	Type	Description
`restored`	`boolean`	Whether restoration was successful
`checkpointId`	`string`	ID of the checkpoint that was restored
`sprite`	`Sprite`	Updated sprite details after restoration

Sprite Object

Field	Type	Description
`name`	`string`	Name of the sprite
`status`	`'creating' \| 'running' \| 'stopped' \| 'error'`	Current status
`createdAt`	`string`	ISO 8601 timestamp of creation
`runtime`	`string?`	Optional runtime configuration
`metadata`	`object?`	Optional custom metadata

Use Cases

Undo changes after failed experiments
Recover from errors or corrupted state
Reset to a known good state
Rollback after testing

Warning

Restoring a checkpoint will replace the current filesystem state. Any changes made after the checkpoint was created will be lost.

Error Handling

The tool throws errors in these cases:

SPRITES_TOKEN environment variable is not set
Sprite or checkpoint not found (HTTP 404)
Invalid or expired API token (HTTP 401)
Network timeout (120 second limit for large restorations)
API errors with descriptive messages

License

MIT

spritesCheckpointRestoreTool

Interactive Playground