compute.sandbox

Overview

Core methods for creating, destroying, listing, and retrieving sandbox instances.

---

create(options?)

Create a new compute sandbox instance.

Parameters:

• options (CreateSandboxOptions, optional): Configuration options for sandbox creation

  • timeout (number, optional): Sandbox execution timeout in milliseconds
  • templateId (string, optional): Provider-agnostic template or image identifier to boot from
  • snapshotId (string, optional): Snapshot ID to restore from; each provider maps this to its native concept (E2B template, Daytona snapshot, Modal image, etc.)
  • metadata (Record<string, any>, optional): Custom metadata to attach to the sandbox
  • envs (Record<string, string>, optional): Environment variables to set in the sandbox
  • signal (AbortSignal, optional): Cancels sandbox creation and cleans up an orphaned sandbox if the signal aborts
  • name, namespace, directory (string, optional): Provider-specific naming/placement hints
  • Additional provider-specific properties are passed through (e.g. domain for E2B)

Returns: Promise<Sandbox> - New sandbox instance ready for code execution and commands

Sandbox instance properties:

• sandboxId (string): Unique identifier for the sandbox
• provider (string): Provider hosting the sandbox (e.g., 'e2b', 'modal', 'vercel')
• filesystem (SandboxFileSystem): File system operations interface
• Core methods: runCommand(), getInfo(), getUrl(), destroy()
• See Sandbox API Reference for complete interface documentation

CreateSandboxOptions interface:

{
  timeout?: number;                // Execution timeout in milliseconds
  templateId?: string;             // Provider template/image identifier
  snapshotId?: string;             // Snapshot to restore from
  metadata?: Record<string, any>;  // Custom metadata
  envs?: Record<string, string>;   // Environment variables
  signal?: AbortSignal;            // Cancel creation / clean up orphaned sandbox
  name?: string;                   // Provider-specific name
  namespace?: string;              // Provider-specific namespace
  directory?: string;              // Provider-specific working directory
  [key: string]: any;              // Provider-specific properties
}

Examples:

import { e2b } from '@computesdk/e2b';

const compute = e2b({ apiKey: process.env.E2B_API_KEY });

// Basic sandbox creation
const sandbox = await compute.sandbox.create();
console.log(sandbox.sandboxId);  // "sb_abc123..."
console.log(sandbox.provider);   // "e2b"

// With timeout (30 minutes)
const sandbox = await compute.sandbox.create({
  timeout: 30 * 60 * 1000
});

// With environment variables
const sandbox = await compute.sandbox.create({
  envs: {
    API_KEY: 'your-api-key',
    NODE_ENV: 'production',
    DATABASE_URL: 'postgresql://...'
  }
});

// With provider template/image
const sandbox = await compute.sandbox.create({
  templateId: 'your-template-id'
});

// With custom metadata
const sandbox = await compute.sandbox.create({
  metadata: {
    userId: 'user-123',
    projectId: 'proj-456',
    environment: 'staging'
  }
});

// With multiple options combined
const sandbox = await compute.sandbox.create({
  timeout: 60 * 60 * 1000,  // 1 hour
  templateId: 'your-template-id',
  envs: {
    NODE_ENV: 'production',
    DEBUG: 'true'
  },
  metadata: {
    owner: 'team-backend',
    purpose: 'integration-tests'
  }
});

// Error handling - missing credentials
try {
  const sandbox = await compute.sandbox.create();
} catch (error) {
  console.error('Failed to create sandbox:', error.message);
}

Notes:

• Configure your provider by importing and initializing a provider package (e.g., @computesdk/e2b) with your credentials
• Each call creates a new sandbox instance with a unique sandboxId
• The timeout option sets maximum sandbox lifetime; sandboxes auto-terminate after this period
• The templateId parameter is provider-specific (refers to templates, images, or runtime environments)
• Environment variables set via envs are available to all commands and code executed in the sandbox
• Throws an error if the provider is missing required credentials (e.g., API key)

---

destroy(sandboxId)

Destroy a sandbox and clean up all associated resources.

Parameters:

• sandboxId (string, required): Unique identifier of the sandbox to destroy

Returns: Promise<void> - Resolves when sandbox is successfully destroyed

⚠️ CAUTION: Destroying a sandbox is a permanent operation. All data, files, and running processes in the sandbox will be irreversibly deleted.

Examples:

import { e2b } from '@computesdk/e2b';

const compute = e2b({ apiKey: process.env.E2B_API_KEY });

// Basic cleanup after use
const sandbox = await compute.sandbox.create();
// ... use sandbox ...
await sandbox.destroy();

// Alternative: destroy by ID
await compute.sandbox.destroy(sandbox.sandboxId);

// Batch cleanup - destroy multiple sandboxes
const sandboxIds = ['sb_123...', 'sb_456...', 'sb_789...'];
await Promise.all(sandboxIds.map(id => compute.sandbox.destroy(id)));

// With error handling
try {
  await sandbox.destroy();
  console.log('Sandbox destroyed successfully');
} catch (error) {
  console.error('Failed to destroy sandbox:', error.message);
}

// Best practice: ensure cleanup with finally block
let sandbox;
try {
  sandbox = await compute.sandbox.create();
  await sandbox.runCommand('echo "Hello"');
} finally {
  if (sandbox) {
    await sandbox.destroy();
  }
}

Notes:

• You can call sandbox.destroy() directly on the sandbox instance, or compute.sandbox.destroy(sandboxId) with the ID
• Destroying a sandbox terminates all running processes and releases all allocated resources
• This operation is idempotent - calling destroy on an already-destroyed sandbox succeeds without error
• Best practice: Use finally blocks or cleanup handlers to ensure sandboxes are destroyed even if errors occur
• All sandbox data and files are permanently lost after destruction

---

getById(sandboxId)

Retrieve an existing sandbox instance by its unique identifier.

Parameters:

• sandboxId (string, required): Unique identifier of the sandbox to retrieve

Returns: Promise<Sandbox | null> - Sandbox instance if found, or null if the sandbox doesn't exist

Sandbox instance properties:

• sandboxId (string): Unique identifier for the sandbox
• provider (string): Provider hosting the sandbox
• filesystem (SandboxFileSystem): File system operations interface
• Core methods: runCommand(), getInfo(), getUrl(), destroy()
• See Sandbox API Reference for complete interface documentation

Examples:

import { e2b } from '@computesdk/e2b';

const compute = e2b({ apiKey: process.env.E2B_API_KEY });

// Reconnect to existing sandbox by ID
const sandboxId = 'sb_abc123...';
const sandbox = await compute.sandbox.getById(sandboxId);

if (sandbox) {
  const result = await sandbox.runCommand('echo "Reconnected!"');
  console.log(result.stdout);  // "Reconnected!"
}

// Store ID and reconnect later
// Step 1: Create and store ID
const newSandbox = await compute.sandbox.create();
const storedId = newSandbox.sandboxId;
// Store storedId in database, config file, etc.

// Step 2: Later, retrieve using stored ID
const retrievedSandbox = await compute.sandbox.getById(storedId);
if (retrievedSandbox) {
  await retrievedSandbox.runCommand('npm install');
}

// Check if sandbox exists before using
const sandbox = await compute.sandbox.getById(sandboxId);

if (sandbox === null) {
  console.log('Sandbox not found - creating new one');
  const newSandbox = await compute.sandbox.create();
} else {
  console.log('Sandbox found - using existing one');
  await sandbox.runCommand('echo "Still active!"');
}

// Graceful handling of missing sandbox
const sandboxId = 'sb_might_not_exist...';
const sandbox = await compute.sandbox.getById(sandboxId);

if (sandbox) {
  // Sandbox exists - use it
  await sandbox.runCommand('npm test');
  console.log('Tests completed on existing sandbox');
} else {
  // Sandbox not found - handle accordingly
  console.log('Sandbox no longer exists');
}

Notes:

• Returns null for non-existent or destroyed sandboxes (does not throw errors)
• Retrieved sandboxes have full functionality identical to newly created sandboxes
• Useful for reconnecting to long-lived sandboxes or implementing persistent sandbox patterns
• Sandbox IDs can be stored and used to reconnect later across application restarts

---

list()

Retrieve a list of your active sandboxes from your provider.

import { e2b } from '@computesdk/e2b';

const compute = e2b({ apiKey: process.env.E2B_API_KEY });

const sandboxes = await compute.sandbox.list();

for (const sandbox of sandboxes) {
  console.log(sandbox.sandboxId);
}

Notes:

• Returns all active sandboxes for the configured provider
• Provider support for listing sandboxes varies — check your provider's documentation for details

---