Snapshots

Snapshots create point-in-time copies of your sandboxes, enabling backup, restore, and cloning workflows.

What Are Snapshots?

A snapshot captures the complete state of a sandbox at a specific moment:

Filesystem - All files and directories
Configuration - Environment variables, resource settings

Use snapshots to:

Create backups before risky operations
Clone working environments
Share reproducible setups
Restore from known-good states

Create a Snapshot

import SandboxSDK from '@akiralabs/sandbox-sdk';
 
const client = new SandboxSDK({
  apiKey: process.env['AKIRA_API_KEY'],
});
 
// Create a snapshot of a running sandbox
const snapshot = await client.sandboxes.snapshot(sandbox.id, {
  name: 'pre-deployment-backup',
  quick: true,  // Optional: crash-consistent (faster) vs application-consistent
});
 
console.log(`Snapshot ID: ${snapshot.id}`);
console.log(`Created at: ${snapshot.created_at}`);

List Snapshots

const snapshots = await client.snapshots.list();
 
for (const snap of snapshots) {
  console.log(`${snap.id}: ${snap.name} (${snap.created_at})`);
}

Restore from Snapshot

Create a new sandbox from a snapshot:

const restoredSandbox = await client.snapshots.restore(snapshot.id, {
  name: 'restored-sandbox',
});
 
console.log(`Restored sandbox: ${restoredSandbox.id}`);

The restored sandbox has the exact filesystem state from when the snapshot was created.

You can also specify optional parameters when restoring:

const restoredSandbox = await client.snapshots.restore(snapshot.id, {
  name: 'restored-sandbox',
  resources: { cpus: 2, memory: 4096 },  // Optional overrides
  wait_for_ready: true,
});

Clone a Sandbox

Quickly duplicate a running sandbox with all its state:

const result = await client.sandboxes.clone(sandbox.id, {
  name: 'sandbox-clone',
});
 
console.log(`Clone ID: ${result.sandbox.id}`);
console.log(`Clone name: ${result.sandbox.name}`);
console.log(`Intermediate snapshot: ${result.snapshot.id}`);

Cloning creates an intermediate snapshot and immediately restores it, giving you an identical copy. The response includes both the new sandbox and the snapshot that was created.

Clone Options

You can customize the clone with several options:

const result = await client.sandboxes.clone(sandbox.id, {
  // Name for the cloned sandbox (auto-generated if not provided)
  name: 'my-cloned-sandbox',
 
  // Custom name for the intermediate snapshot
  snapshot_name: 'clone-backup-1',
 
  // Override resources (storage is inherited from source)
  resources: {
    cpus: 4,      // 1-32 CPUs
    memory: 8192, // 128-32768 MiB
  },
 
  // Override the Docker image
  image: 'akiralabs/akira-default-sandbox',
 
  // Wait for sandbox to be ready before returning
  wait_for_ready: true,
});

Cloning vs Snapshots

Use clone when you want an immediate copy of a running sandbox. Use snapshot + restore when you want to save state for later or create multiple copies from the same snapshot.

Clone Response

The clone response includes both the new sandbox and the intermediate snapshot:

{
  sandbox: {
    id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    name: 'my-cloned-sandbox',
    created_at: '2024-01-17T20:00:00Z',
    cpu: 2,
    memory: 1024,
    storage: 10,
    status: 'creating'
  },
  snapshot: {
    id: 'c3d4e5f6-a7b8-9012-cdef-123456789012',
    name: 'clone-backup-1',
    source_sandbox_id: 'd4e5f6a7-b8c9-0123-def0-234567890123',
    source_sandbox_name: 'source-sandbox',
    status: 'ready',
    created_at: '2024-01-17T19:59:50Z',
    consistency: 'application'
  }
}

Delete Snapshots

await client.snapshots.delete(snapshot.id);

Storage Costs

Snapshots consume storage space. Delete old snapshots you no longer need to reduce costs.

REST API

Create Snapshot

curl -X POST https://api.akiralabs.ai/v1/sandboxes/{sandbox_id}/snapshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-backup"
  }'

List Snapshots

curl https://api.akiralabs.ai/v1/snapshots/list \
  -H "x-api-key: YOUR_API_KEY"

Restore Snapshot

curl -X POST https://api.akiralabs.ai/v1/snapshots/{snapshot_id}/restore \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "restored-sandbox"}'

Delete Snapshot

curl -X DELETE https://api.akiralabs.ai/v1/snapshots/{snapshot_id} \
  -H "x-api-key: YOUR_API_KEY"

Clone Sandbox

curl -X POST https://api.akiralabs.ai/v1/sandboxes/{sandbox_id}/clone \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-cloned-sandbox",
    "snapshot_name": "clone-backup-1",
    "resources": {
      "cpus": 2,
      "memory": 1024
    }
  }'

Use Cases

Pre-Deployment Backup

Always snapshot before deploying changes:

// Snapshot current state
const backup = await client.sandboxes.snapshot(sandbox.id, {
  name: `pre-deploy-${Date.now()}`,
});
 
try {
  // Deploy changes
  await client.sandboxes.execute(sandbox.id, {
    command: './deploy.sh',
  });
} catch (error) {
  // Rollback on failure
  console.log('Deployment failed, restoring backup...');
  const restored = await client.snapshots.restore(backup.id, {
    name: 'restored-from-backup',
  });
  console.log(`Restored to: ${restored.id}`);
}

Environment Templates

Create snapshots of configured environments for reuse:

// Set up a fully configured dev environment
const devSandbox = await client.sandboxes.create({
  image: 'akiralabs/akira-default-sandbox',
});
 
// Install dependencies, configure tools
await client.sandboxes.execute(devSandbox.id, {
  command: 'apt-get update && apt-get install -y vim git nodejs',
});
 
await client.sandboxes.execute(devSandbox.id, {
  command: 'npm install -g typescript eslint prettier',
});
 
// Snapshot as template
const template = await client.sandboxes.snapshot(devSandbox.id, {
  name: 'dev-environment-template',
});
 
// Create new environments from template
const newDev = await client.snapshots.restore(template.id, {
  name: 'new-dev-environment',
});

Experiment Branching

Create branches for parallel experiments:

// Base experiment setup
const experiment = await client.sandboxes.create({
  image: 'akiralabs/akira-default-sandbox',
});
 
await client.sandboxes.execute(experiment.id, {
  command: 'pip install torch numpy pandas',
});
 
// Snapshot base state
const baseState = await client.sandboxes.snapshot(experiment.id, {
  name: 'experiment-base',
});
 
// Branch A: Try approach 1
const branchA = await client.snapshots.restore(baseState.id, {
  name: 'experiment-branch-a',
});
await client.sandboxes.execute(branchA.id, {
  command: 'python train_v1.py',
});
 
// Branch B: Try approach 2
const branchB = await client.snapshots.restore(baseState.id, {
  name: 'experiment-branch-b',
});
await client.sandboxes.execute(branchB.id, {
  command: 'python train_v2.py',
});

Parallel Clones for Scale

Use cloning to quickly spin up parallel workers from a configured base:

// Set up a configured sandbox
const baseSandbox = await client.sandboxes.create({
  image: 'akiralabs/akira-default-sandbox',
});
 
await client.sandboxes.execute(baseSandbox.id, {
  command: 'pip install torch numpy pandas scikit-learn',
});
 
// Create multiple clones for parallel processing
const tasks = ['data1.csv', 'data2.csv', 'data3.csv', 'data4.csv'];
 
const clones = await Promise.all(
  tasks.map(async (dataFile, i) => {
    const result = await client.sandboxes.clone(baseSandbox.id, {
      name: `worker-${i}`,
      wait_for_ready: true,
    });
    return result.sandbox;
  })
);
 
// Run parallel processing on each clone
await Promise.all(
  clones.map((clone, i) =>
    client.sandboxes.execute(clone.id, {
      command: `python process.py ${tasks[i]}`,
    })
  )
);
 
// Clean up
await Promise.all(clones.map((clone) => client.sandboxes.delete(clone.id)));
await client.sandboxes.delete(baseSandbox.id);

Best Practices

Name snapshots descriptively - Include timestamps or purpose
Clean up old snapshots - Delete after they're no longer needed
Snapshot before changes - Create backups before risky operations
Use for templates - Snapshot configured environments for quick setup
Use clones for parallel work - Clone a configured sandbox for quick parallel workers

Next Steps

Learn about command execution patterns
Explore use cases for AI agents

Create Sandbox Execute Commands