Snapshots

Create checkpoints of your sandbox environment and restore to any previous state. Think of it as version control for your entire workspace.

Create Checkpoint

await sandbox.snapshots.commit({
  message: 'Before major refactoring'
});

console.log('Checkpoint created');

const response = await fetch(`${sandbox.url}/snapshots/commit`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Before major refactoring'
  })
});

const result = await response.json();

curl -X POST https://sandbox.oblien.com/snapshots/commit \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Before major refactoring"}'

Response:

{
  "success": true,
  "message": "Checkpoint created",
  "commitHash": "a1b2c3d4",
  "timestamp": "2025-10-26T12:00:00Z"
}

List Checkpoints

const checkpoints = await sandbox.snapshots.listCheckpoints({
  limit: 20
});

checkpoints.commits.forEach(commit => {
  console.log(`${commit.hash} - ${commit.message}`);
  console.log(`  ${commit.timestamp}`);
});

const response = await fetch(`${sandbox.url}/snapshots/list?limit=20`, {
  headers: {
    'Authorization': `Bearer ${sandbox.token}`
  }
});

const checkpoints = await response.json();

curl https://sandbox.oblien.com/snapshots/list?limit=20 \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN"

Response:

{
  "success": true,
  "commits": [
    {
      "hash": "a1b2c3d4",
      "message": "Before major refactoring",
      "timestamp": "2025-10-26T12:00:00Z"
    },
    {
      "hash": "e5f6g7h8",
      "message": "After adding authentication",
      "timestamp": "2025-10-26T11:30:00Z"
    }
  ],
  "total": 2
}

Get Current Checkpoint

const current = await sandbox.snapshots.getCurrentCheckpoint();

console.log('Current checkpoint:', current.hash);
console.log('Message:', current.message);

const response = await fetch(`${sandbox.url}/snapshots/current`, {
  headers: {
    'Authorization': `Bearer ${sandbox.token}`
  }
});

const current = await response.json();

curl https://sandbox.oblien.com/snapshots/current \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN"

Get Checkpoint Details

const checkpoint = await sandbox.snapshots.getCheckpoint('a1b2c3d4');

console.log('Hash:', checkpoint.hash);
console.log('Message:', checkpoint.message);
console.log('Files changed:', checkpoint.filesChanged);

const response = await fetch(`${sandbox.url}/snapshots/checkpoint/a1b2c3d4`, {
  headers: {
    'Authorization': `Bearer ${sandbox.token}`
  }
});

const checkpoint = await response.json();

curl https://sandbox.oblien.com/snapshots/checkpoint/a1b2c3d4 \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN"

Restore Checkpoint

Go back to a specific checkpoint:

await sandbox.snapshots.goto({
  commitHash: 'a1b2c3d4'
});

console.log('Restored to checkpoint');

const response = await fetch(`${sandbox.url}/snapshots/goto`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    commitHash: 'a1b2c3d4'
  })
});

const result = await response.json();

curl -X POST https://sandbox.oblien.com/snapshots/goto \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"commitHash": "a1b2c3d4"}'

Delete Commits After Hash

Remove all commits after a specific checkpoint:

await sandbox.snapshots.deleteAfter({
  commitHash: 'a1b2c3d4'
});

console.log('Later commits deleted');

const response = await fetch(`${sandbox.url}/snapshots/delete-after`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    commitHash: 'a1b2c3d4'
  })
});

curl -X POST https://sandbox.oblien.com/snapshots/delete-after \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"commitHash": "a1b2c3d4"}'

Cleanup All Checkpoints

Remove all checkpoints (careful!):

await sandbox.snapshots.cleanup();

console.log('All checkpoints removed');

const response = await fetch(`${sandbox.url}/snapshots/cleanup`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`
  }
});

curl -X POST https://sandbox.oblien.com/snapshots/cleanup \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Complete Example

// Create checkpoint before changes
await sandbox.snapshots.commit({
  message: 'Before testing new feature'
});

// Make changes
await sandbox.files.edit({
  filePath: '/opt/app/src/api.js',
  content: '// Experimental code'
});

await sandbox.terminal.execute({
  command: 'npm test',
  cwd: '/opt/app'
});

// If tests fail, restore checkpoint
const testResult = await sandbox.terminal.execute({
  command: 'npm test',
  cwd: '/opt/app'
});

if (testResult.exitCode !== 0) {
  console.log('Tests failed, restoring checkpoint...');
  
  // Get current checkpoint
  const current = await sandbox.snapshots.getCurrentCheckpoint();
  
  // Get previous checkpoint
  const checkpoints = await sandbox.snapshots.listCheckpoints({ limit: 2 });
  const previousHash = checkpoints.commits[1].hash;
  
  // Restore
  await sandbox.snapshots.goto({
    commitHash: previousHash
  });
  
  console.log('Restored to previous checkpoint');
} else {
  console.log('Tests passed, creating success checkpoint');
  await sandbox.snapshots.commit({
    message: 'New feature working'
  });
}

// Create checkpoint
await fetch(`${sandbox.url}/snapshots/commit`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Before testing new feature'
  })
});

// (Make changes and test)

// List checkpoints
let response = await fetch(`${sandbox.url}/snapshots/list?limit=2`, {
  headers: {
    'Authorization': `Bearer ${sandbox.token}`
  }
});

const checkpoints = await response.json();

// Restore if needed
await fetch(`${sandbox.url}/snapshots/goto`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    commitHash: checkpoints.commits[1].hash
  })
});

curl -X POST https://sandbox.oblien.com/snapshots/commit \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Use Cases

Safe Experimentation

// Checkpoint before experiment
await sandbox.snapshots.commit({ message: 'Before experiment' });

// Try something risky
// ...

// Restore if it doesn't work
await sandbox.snapshots.goto({ commitHash: 'previous-hash' });

Testing Workflows

// Checkpoint before tests
const before = await sandbox.snapshots.commit({ 
  message: 'Pre-test state' 
});

// Run tests
// ...

// Restore for next test run
await sandbox.snapshots.goto({ commitHash: before.commitHash });

Development Milestones

// Checkpoint at milestones
await sandbox.snapshots.commit({ message: 'Feature complete' });
await sandbox.snapshots.commit({ message: 'Tests passing' });
await sandbox.snapshots.commit({ message: 'Ready for review' });

Best Practices

Create meaningful messages:

message: 'Before refactoring auth module'
// Not: 'checkpoint'

Checkpoint before major changes: Create safety points before risky operations
Clean up old checkpoints: Remove unused checkpoints to save space
List checkpoints regularly: Review available restore points
Document important checkpoints: Use descriptive messages for key states

Next Steps

Snapshot Archives - Long-term storage
File Operations - Work with files
Git Operations - Version control

On this page