​
Using the TypeScript SDK

Volume snapshots allow you to create point-in-time backups of your volumes. Snapshots capture the entire state of a volume at a specific moment, enabling you to restore data, clone volumes, or create multiple sandboxes with identical data.

​
Benefits of Volume Snapshots

  • Backup and Recovery: Create backups before making significant changes or updates
  • Point-in-Time Recovery: Restore volumes to a previous state if something goes wrong
  • Volume Cloning: Create new volumes from snapshots to duplicate data across multiple sandboxes
  • Experiment Safely: Take snapshots before experiments, allowing quick rollback if needed
  • Data Sharing: Share volume states by creating snapshots that others can use

​
Step 1: Create a Snapshot

Create a snapshot of an existing volume:

import SandboxSDK from '@avmcodes/sandbox-sdk';

const client = new SandboxSDK({
  apiKey: process.env['SANDBOX_SDK_API_KEY'],
});

// Create a snapshot of an existing volume
const snapshot = await client.volumes.createSnapshot('vol_x1y2z3a4b5c6d7e8', {
  name: 'my-volume-backup',
});

console.log('Snapshot created:', snapshot.id);
console.log('Snapshot name:', snapshot.name);
console.log('Source volume:', snapshot.volume_id);

​
Step 2: Use Snapshot to Create Sandbox

When creating a sandbox, you can use a snapshot ID as the volume_id. This automatically creates a new volume from the snapshot and attaches it to the sandbox:

// Create a sandbox with a volume created from the snapshot
const sandbox = await client.sandboxes.create({
  name: 'Sandbox with Snapshot Data',
  volumes: [
    {
      volume_id: snapshot.id, // Snapshot ID - automatically creates volume from snapshot
      mount_path: '/data',
    },
  ],
});

console.log('Sandbox created with volume from snapshot:', sandbox.id);

Each sandbox created with a snapshot ID gets its own independent copy of the snapshot data, allowing you to clone volumes across multiple sandboxes.

​
Complete Example: Backup and Restore Workflow

Here’s a complete example demonstrating a backup and restore workflow:

import SandboxSDK from '@avmcodes/sandbox-sdk';

const client = new SandboxSDK({
  apiKey: process.env['SANDBOX_SDK_API_KEY'],
});

async function backupAndRestoreWorkflow() {
  // 1. Create a volume and add some data
  const originalVolume = await client.volumes.create({
    name: 'my-data-volume',
    size: '10Gi',
  });

  // 2. Create a sandbox with the volume
  const sandbox = await client.sandboxes.create({
    name: 'Data Sandbox',
    volumes: [
      {
        volume_id: originalVolume.id,
        mount_path: '/data',
      },
    ],
  });

  // 3. Add some important data
  await client.sandboxes.execute(sandbox.id, {
    command: 'echo "Important data" > /data/important.txt',
  });

  // 4. Create a snapshot before making changes
  const snapshot = await client.volumes.createSnapshot(originalVolume.id, {
    name: 'pre-change-backup',
  });

  console.log(`Snapshot created: ${snapshot.id}`);

  // 5. Make some changes (simulating a risky operation)
  await client.sandboxes.execute(sandbox.id, {
    command: 'rm /data/important.txt', // Oops!
  });

  // 6. Restore from snapshot by creating a new volume
  const restoredSandbox = await client.sandboxes.create({
    name: 'Restored Sandbox',
    volumes: [
      {
        volume_id: snapshot.id, // Create volume from snapshot
        mount_path: '/data',
      },
    ],
  });

  // 7. Verify the data is restored
  const result = await client.sandboxes.execute(restoredSandbox.id, {
    command: 'cat /data/important.txt',
  });

  console.log('Restored data:', result.stdout);
  // Output: "Important data"
}

​
Use Case: Cloning Volumes for Parallel Processing

Snapshots are useful when you need to create multiple sandboxes with identical data for parallel processing:

async function cloneVolumeForParallelProcessing() {
  // 1. Create a volume with your dataset
  const sourceVolume = await client.volumes.create({
    name: 'dataset-volume',
    size: '50Gi',
  });

  const setupSandbox = await client.sandboxes.create({
    name: 'Setup Sandbox',
    volumes: [{ volume_id: sourceVolume.id, mount_path: '/data' }],
  });

  // 2. Download or prepare your dataset
  await client.sandboxes.execute(setupSandbox.id, {
    command: 'cd /data && wget https://example.com/large-dataset.zip',
    timeout: 600,
  });

  // 3. Create a snapshot
  const snapshot = await client.volumes.createSnapshot(sourceVolume.id, {
    name: 'dataset-snapshot',
  });

  // 4. Create multiple sandboxes from the snapshot for parallel processing
  const numWorkers = 10;
  const workerSandboxes = await Promise.all(
    Array.from({ length: numWorkers }, (_, i) =>
      client.sandboxes.create({
        name: `Worker ${i + 1}`,
        volumes: [
          {
            volume_id: snapshot.id, // Each sandbox gets its own copy from snapshot
            mount_path: '/data',
          },
        ],
      })
    )
  );

  console.log(`Created ${numWorkers} sandboxes with identical data`);
}

​
Best Practices

  1. Snapshot Before Major Changes: Always create snapshots before making significant modifications to your data
  2. Regular Backups: Schedule regular snapshots for critical volumes
  3. Name Your Snapshots: Use descriptive names to identify snapshot purposes
  4. Clean Up Old Snapshots: Delete snapshots you no longer need to manage storage costs
  5. Test Restores: Periodically test restoring from snapshots to ensure they work correctly

​
Response Structure

The createSnapshot() method returns a VolumeCreateSnapshotResponse object:

const snapshot = await client.volumes.createSnapshot('vol_x1y2z3a4b5c6d7e8', {
  name: 'my-backup',
});

// snapshot contains:
console.log(snapshot.id);        // Snapshot ID
console.log(snapshot.name);       // "my-backup"
console.log(snapshot.volume_id);  // ID of the source volume
console.log(snapshot.created_at); // Timestamp when snapshot was created

​
Parameters

​
name
string
required

A descriptive name for your snapshot

​
Next Steps

Creating your first VolumeExecute Commands