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-specific template or image identifier
- metadata (Record<string, any>, optional): Custom metadata to attach to the sandbox
- envs (Record<string, string>, optional): Environment variables to set in the sandbox

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: runCode(), 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
  metadata?: Record<string, any>; // Custom metadata
  envs?: Record<string, string>;  // Environment variables
}

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.runCode('console.log("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: runCode(), 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.runCode('console.log("Reconnected!")');
  console.log(result.output);  // "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.runCode('print("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