Snapshots

Create checkpoints of your sandbox environment and restore to any previous state instantly.

What are Snapshots?

Snapshots are Git-based checkpoints that save the entire state of your sandbox:

All files and directories
Git repository state
File permissions and metadata

Think of them as "save points" that you can return to at any time.

Create Snapshot

Create a checkpoint of the current environment state.

// Using SDK
const snapshot = await sandbox.snapshots.commit({
  message: 'Before major refactor'
});

console.log('Snapshot created:', snapshot.commitHash);

POST /snapshots/commit HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "message": "Before major refactor"
}

Response:

{
  "success": true,
  "commitHash": "a1b2c3d4e5f6g7h8",
  "isFirst": false,
  "message": "Checkpoint created successfully"
}

Parameters:

Parameter	Type	Required	Description
`message`	string	Yes	Snapshot description

Restore Snapshot

Restore environment to a previous snapshot.

// Using SDK
await sandbox.snapshots.goto({
  commitHash: 'a1b2c3d4e5f6g7h8'
});

POST /snapshots/goto HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "commitHash": "a1b2c3d4e5f6g7h8"
}

Response:

{
  "success": true,
  "commitHash": "a1b2c3d4e5f6g7h8",
  "message": "Moved to commit successfully"
}

⚠️ Warning: Restoring a snapshot will discard all current changes. Create a snapshot before restoring if you want to save current state.

List Snapshots

Get all available snapshots.

// Using SDK
const snapshots = await sandbox.snapshots.list({
  limit: 20
});

snapshots.checkpoints.forEach(snap => {
  console.log(`${snap.hash.substring(0, 7)} - ${snap.message}`);
  console.log(`  Created: ${snap.date}`);
});

GET /snapshots/checkpoints?limit=20 HTTP/1.1
Authorization: Bearer YOUR_TOKEN

Response:

{
  "success": true,
  "checkpoints": [
    {
      "hash": "a1b2c3d4e5f6g7h8",
      "message": "Before major refactor",
      "author": "AI Agent <ai@oblien.com>",
      "date": "2025-10-16T12:00:00Z",
      "fileCount": 42
    },
    {
      "hash": "h8g7f6e5d4c3b2a1",
      "message": "After adding authentication",
      "author": "AI Agent <ai@oblien.com>",
      "date": "2025-10-16T11:30:00Z",
      "fileCount": 38
    }
  ],
  "count": 2
}

Query Parameters:

Parameter	Type	Description
`limit`	number	Maximum snapshots to return (default: 20)

Get Snapshot Info

Get detailed information about a specific snapshot.

// Using SDK
const info = await sandbox.snapshots.getInfo({
  commitHash: 'a1b2c3d4e5f6g7h8'
});

GET /snapshots/checkpoint/a1b2c3d4e5f6g7h8 HTTP/1.1
Authorization: Bearer YOUR_TOKEN

Response:

{
  "success": true,
  "checkpoint": {
    "hash": "a1b2c3d4e5f6g7h8",
    "message": "Before major refactor",
    "author": "AI Agent <ai@oblien.com>",
    "date": "2025-10-16T12:00:00Z",
    "fileCount": 42,
    "changes": {
      "added": 5,
      "modified": 12,
      "deleted": 2
    }
  }
}

Get Current Snapshot

Get the currently active snapshot.

// Using SDK
const current = await sandbox.snapshots.current();

console.log('Current snapshot:', current.commitHash);

GET /snapshots/current-checkpoint HTTP/1.1
Authorization: Bearer YOUR_TOKEN

Response:

{
  "success": true,
  "commitHash": "a1b2c3d4e5f6g7h8"
}

Delete Snapshots

Delete snapshots after a specific commit.

// Using SDK
await sandbox.snapshots.delete({
  commitHash: 'a1b2c3d4e5f6g7h8'
});

POST /snapshots/delete HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "commitHash": "a1b2c3d4e5f6g7h8"
}

Response:

{
  "success": true,
  "message": "Permanently deleted all commits after a1b2c3d4e5f6g7h8"
}

⚠️ Warning: This permanently deletes snapshots. This action cannot be undone.

Cleanup All Snapshots

Remove all snapshots and start fresh.

// Using SDK
await sandbox.snapshots.cleanup();

POST /snapshots/cleanup HTTP/1.1
Authorization: Bearer YOUR_TOKEN

Response:

{
  "success": true,
  "message": "All checkpoints cleaned up - started fresh"
}

Common Workflows

Safe Experimentation

// 1. Create snapshot before risky changes
const snapshot = await sandbox.snapshots.commit({
  message: 'Before experimental refactor'
});

try {
  // 2. Make experimental changes
  await sandbox.files.edit({ ... });
  await sandbox.terminal.execute({ command: 'npm run build' });
  
  // 3. Test the changes
  const tests = await sandbox.terminal.execute({ command: 'npm test' });
  
  if (tests.exitCode !== 0) {
    // Tests failed - rollback
    await sandbox.snapshots.goto({ commitHash: snapshot.commitHash });
    console.log('Rolled back changes');
  } else {
    console.log('Changes successful!');
  }
} catch (error) {
  // Error occurred - rollback
  await sandbox.snapshots.goto({ commitHash: snapshot.commitHash });
  console.log('Rolled back due to error:', error.message);
}

Version History

// Track multiple versions
await sandbox.snapshots.commit({ message: 'v1.0.0 - Initial release' });

// Make changes...
await sandbox.snapshots.commit({ message: 'v1.1.0 - Add new feature' });

// Make more changes...
await sandbox.snapshots.commit({ message: 'v1.2.0 - Performance improvements' });

// View history
const snapshots = await sandbox.snapshots.list({ limit: 10 });
snapshots.checkpoints.forEach(s => {
  console.log(`${s.date} - ${s.message}`);
});

A/B Testing

// Create two different implementations
const original = await sandbox.snapshots.commit({ message: 'Original implementation' });

// Try approach A
await implementApproachA();
const snapshotA = await sandbox.snapshots.commit({ message: 'Approach A' });
const resultA = await runTests();

// Restore and try approach B
await sandbox.snapshots.goto({ commitHash: original.commitHash });
await implementApproachB();
const snapshotB = await sandbox.snapshots.commit({ message: 'Approach B' });
const resultB = await runTests();

// Choose the better one
if (resultA.performance > resultB.performance) {
  await sandbox.snapshots.goto({ commitHash: snapshotA.commitHash });
} else {
  await sandbox.snapshots.goto({ commitHash: snapshotB.commitHash });
}

Snapshot vs Git Commits

Feature	Snapshots	Git Commits
Purpose	Environment checkpoints	Code version control
Scope	Entire sandbox state	Tracked files only
Speed	Instant rollback	Fast but requires checkout
Remote	Local only	Can push to remote
Best For	Experimentation, testing	Long-term version control

ℹ️ Info: Snapshots are perfect for temporary checkpoints during development. Use Git commits for permanent version control.

Best Practices

1. Create Snapshots Before Risky Operations

// Before major changes
await sandbox.snapshots.commit({ message: 'Before dependency upgrade' });
await sandbox.terminal.execute({ command: 'npm install package@latest' });

2. Use Descriptive Messages

// ✅ Good
await sandbox.snapshots.commit({ message: 'Before database migration' });
await sandbox.snapshots.commit({ message: 'After successful build' });

// ❌ Bad
await sandbox.snapshots.commit({ message: 'snapshot 1' });
await sandbox.snapshots.commit({ message: 'test' });

3. Regular Cleanup

// Keep only recent snapshots
const snapshots = await sandbox.snapshots.list({ limit: 100 });

if (snapshots.count > 50) {
  // Delete old snapshots
  const oldestToKeep = snapshots.checkpoints[49];
  await sandbox.snapshots.delete({ commitHash: oldestToKeep.hash });
}

Next Steps

Explore Snapshot Archive for long-term storage
Learn about Git Commits for version control
Check File Operations for file management

On this page