Using the TypeScript SDK

The easiest way to create a sandbox is using our official TypeScript SDK:

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

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

// Create a sandbox with default settings
const sandbox = await client.sandboxes.create({
  name: 'My First Sandbox',
});

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

Customizing Resources

You can customize the CPU and memory allocation:

const sandbox = await client.sandboxes.create({
  name: 'High Performance Sandbox',
  resources: {
    cpus: 4,
    memory: 2048, // Memory in MiB
  },
});

Using a Custom Docker Image

By default, sandboxes use avmcodes/avm-default-sandbox. You can specify a different image:

const sandbox = await client.sandboxes.create({
  name: 'Custom Image Sandbox',
  image: 'avmcodes/avm-default-sandbox',
  resources: {
    cpus: 2,
    memory: 512,
  },
});

Attaching Volumes

You can attach persistent volumes to your sandbox:

const sandbox = await client.sandboxes.create({
  name: 'Sandbox with Volume',
  volumes: [
    {
      volume_id: 'vol_x1y2z3a4b5c6d7e8',
      mount_path: '/data',
    },
  ],
});

Setting Environment Variables

Pass environment variables to your sandbox:

const sandbox = await client.sandboxes.create({
  name: 'Sandbox with Env Vars',
  env_vars: {
    API_KEY: 'your-api-key',
    DEBUG: 'true',
  },
});

Response Structure

The create() method returns a SandboxCreateResponse object:

const sandbox = await client.sandboxes.create({
  name: 'My First Sandbox',
  resources: {
    cpus: 2,
    memory: 512,
  },
});

// sandbox contains:
console.log(sandbox.id);        // "sbx_x1y2z3a4b5c6d7e8"
console.log(sandbox.name);      // "My First Sandbox"
console.log(sandbox.status);    // "creating"
console.log(sandbox.cpu);       // 2
console.log(sandbox.memory);    // 512
console.log(sandbox.created_at); // "2024-01-15T12:00:00Z"
console.log(sandbox.volumes);   // Array of mounted volumes (if any)

Parameters

name
string

A descriptive name for your sandbox

image
string
default:
"avmcodes/avm-default-sandbox"

Docker image name to use for the sandbox

resources
object

Resource allocation for the sandbox

resources.cpus
integer
default:
"2"

Number of vCPUs (1-32)

resources.memory
integer
default:
"512"

Memory size in MiB (128-32768)

env_vars
object

Environment variables to set in the sandbox (key-value pairs)

volumes
array

Array of volumes to attach to the sandbox

volumes[].volume_id
string
required

Volume ID or Snapshot ID. If a snapshot ID is provided, a new volume will be created from the snapshot.

volumes[].mount_path
string
required

Mount path in the container (e.g., /data)

Next Steps

Once your sandbox is created, you can: