Creating your first Volume

Learn how to set up persistent volumes and connect them to your sandboxes.

Using the TypeScript SDK

Volumes enable durable storage that remains intact across sandbox restarts. Let’s create one, confirm it’s available, and attach it to a sandbox.

1

Create a Volume

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

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

// Create a volume with default size (10Gi)
const volume = await client.volumes.create({
  name: 'my-persistent-storage',
});

console.log('Volume created:', volume.id);
console.log('Volume name:', volume.name);
console.log('Volume size:', volume.size);
console.log('Volume status:', volume.status);

2

Verify the Volume Exists

Retrieve all volumes to verify that your volume was created successfully.

// List all volumes
const volumesResponse = await client.volumes.list();

// Find your volume
const myVolume = volumesResponse.data.find(
  v => v.name === 'my-persistent-storage'
);

if (myVolume) {
  console.log('Volume found:', myVolume.id);
  console.log('Status:', myVolume.status); // Should be "Bound" when ready
} else {
  console.log('Volume not found');
}

3

Create a Sandbox with the Volume

Mount your volume to a sandbox using a custom directory path.

// Create a sandbox with the volume mounted at /data
const sandbox = await client.sandboxes.create({
  name: 'Sandbox with Persistent Storage',
  volumes: [
    {
      volume_id: volume.id,
      mount_path: '/data', // Custom mount point
    },
  ],
  resources: {
    cpus: 2,
    memory: 512,
  },
});

console.log('Sandbox created:', sandbox.id);
console.log('Volumes mounted:', sandbox.volumes);

4

Download Something Heavy

Show data persistence by downloading a large repository or dataset.

// Clone a large repository to the mounted volume
const result = await client.sandboxes.execute(sandbox.id, {
  command: 'cd /data && git clone --depth 1 https://github.com/torvalds/linux.git',
  timeout: 300, // 5 minutes for large downloads
});

if (result.status === 'completed' && result.exit_code === 0) {
  console.log('Repository cloned successfully!');
  console.log('Output:', result.stdout);
} else {
  console.error('Clone failed:', result.stderr);
}

5

Verify Data Persistence

Verify that the data is stored on the volume.

// List files in the mounted volume
const listResult = await client.sandboxes.execute(sandbox.id, {
  command: 'ls -lh /data',
  working_dir: '/data',
});

console.log('Files on volume:', listResult.stdout);

// Check the size of what we downloaded
const sizeResult = await client.sandboxes.execute(sandbox.id, {
  command: 'du -sh /data/linux 2>/dev/null || echo "Directory not found"',
});

console.log('Downloaded size:', sizeResult.stdout);

Complete Example

Below is a full example that brings all the pieces together.

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

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

async function createVolumeAndSandbox() {
  // 1. Create a volume
  console.log('Creating volume...');
  const volume = await client.volumes.create({
    name: 'my-dataset-storage',
    size: '20Gi', // Larger size for big datasets
  });
  console.log(`Volume created: ${volume.id}`);

  // 2. Wait a moment for volume to be ready
  await new Promise(resolve => setTimeout(resolve, 2000));

  // 3. Verify volume exists
  const volumesResponse = await client.volumes.list();
  const foundVolume = volumesResponse.data.find(v => v.id === volume.id);
  if (!foundVolume) {
    throw new Error('Volume not found after creation');
  }
  console.log(`Volume verified: ${foundVolume.status}`);

  // 4. Create sandbox with volume mounted
  console.log('Creating sandbox with volume...');
  const sandbox = await client.sandboxes.create({
    name: 'Data Processing Sandbox',
    volumes: [
      {
        volume_id: volume.id,
        mount_path: '/workspace', // Custom mount point
      },
    ],
    resources: {
      cpus: 4,
      memory: 2048,
    },
  });
  console.log(`Sandbox created: ${sandbox.id}`);

  // 5. Download a large dataset (example: TensorFlow models)
  console.log('Downloading large dataset...');
  const downloadResult = await client.sandboxes.execute(sandbox.id, {
    command: 'cd /workspace && wget -q --show-progress https://github.com/tensorflow/tensorflow/archive/refs/heads/master.zip -O tensorflow.zip',
    timeout: 600, // 10 minutes
  });

  if (downloadResult.status === 'completed') {
    console.log('Download completed!');
    console.log('Exit code:', downloadResult.exit_code);
  }

  // 6. Verify the download
  const verifyResult = await client.sandboxes.execute(sandbox.id, {
    command: 'ls -lh /workspace/tensorflow.zip',
  });
  console.log('File info:', verifyResult.stdout);

  return { volume, sandbox };
}

// Run the example
createVolumeAndSandbox()
  .then(({ volume, sandbox }) => {
    console.log('Success!');
    console.log(`Volume ID: ${volume.id}`);
    console.log(`Sandbox ID: ${sandbox.id}`);
  })
  .catch(console.error);

Customizing Volume Size

Volume capacity can be defined at creation time.

// Small volume (100Mi)
const smallVolume = await client.volumes.create({
  name: 'small-storage',
  size: '100Mi',
});

// Medium volume (10Gi - default)
const mediumVolume = await client.volumes.create({
  name: 'medium-storage',
  size: '10Gi',
});

// Large volume (100Gi)
const largeVolume = await client.volumes.create({
  name: 'large-storage',
  size: '100Gi',
});

Using Multiple Volumes

A single sandbox can have multiple volumes attached.

// Create multiple volumes
const dataVolume = await client.volumes.create({
  name: 'data-volume',
  size: '50Gi',
});

const cacheVolume = await client.volumes.create({
  name: 'cache-volume',
  size: '10Gi',
});

// Mount both volumes to a sandbox
const sandbox = await client.sandboxes.create({
  name: 'Multi-Volume Sandbox',
  volumes: [
    {
      volume_id: dataVolume.id,
      mount_path: '/data',
    },
    {
      volume_id: cacheVolume.id,
      mount_path: '/cache',
    },
  ],
});

Response Structure

The create() method returns a Volume object:

const volume = await client.volumes.create({
  name: 'my-volume',
});

// volume contains:
console.log(volume.id);        // "vol_x1y2z3a4b5c6d7e8"
console.log(volume.name);       // "my-volume"
console.log(volume.size);       // "10Gi"
console.log(volume.status);     // "Bound" or "Pending"
console.log(volume.created_at); // "2024-01-15T12:00:00Z"

Parameters

name string required

A descriptive name for your volume

---

size string default:"10Gi"

Volume size in Kubernetes format (e.g., ‘10Gi’, ‘100Mi’, ‘1Ti’). Supported units: Mi, Gi, Ti

---

Volume Status

Volumes can have different statuses:

• Pending - Volume is being created

• Bound - Volume is ready to use

• Lost - Volume is unavailable (rare)

Wait for the volume status to be Bound before mounting it to a sandbox for best results.

Best Practices

• Select suitable capacities by estimating your storage requirements to prevent space limitations.

• Name volumes according to what they’re used for (e.g., ml-models, datasets, cache).

• Verify before use: Always check that a volume exists and is Bound before mounting.

• Mount at logical paths: Use meaningful mount paths like /data, /workspace, /models.

• Remove volumes you no longer need to reclaim storage resources.

Next Steps

• Create volume snapshots for data backup Learn how to capture point-in-time snapshots to protect and preserve volume data.

• Review all volume-related API endpoints Consult the API reference for a complete overview of supported volume operations.