Quick Start

Welcome to ComputeSDK! This guide will get you up and running with secure, isolated code execution across multiple cloud providers using a unified TypeScript interface.

Installation

Install the provider package for the platform you want to use. This guide uses E2B as an example, but the sandbox API is the same across all providers.

npm install @computesdk/e2b

Then add your provider credentials to a .env file:

E2B_API_KEY=your_e2b_api_key

Basic Usage

A sandbox is an isolated compute environment where you can safely execute code. Each sandbox runs on your chosen cloud provider (E2B, Modal, Vercel, etc.) with a unified interface. The create() method provisions a new sandbox, runCommand() executes shell commands and returns the result, and destroy() tears down the sandbox to free resources.

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

// Create a compute instance for your provider
const compute = e2b({ apiKey: process.env.E2B_API_KEY });

// Create a sandbox
const sandbox = await compute.sandbox.create();

// Run a command
const result = await sandbox.runCommand('echo "Hello World!"');
console.log(result.stdout); // "Hello World!"

// Clean up
await sandbox.destroy();

Filesystem Operations

Each sandbox has its own isolated filesystem. You can read, write, and manage files using absolute paths (starting with /). Files persist for the sandbox lifetime and are destroyed when you call destroy().

// Write file
await sandbox.filesystem.writeFile('/tmp/hello.py', 'print("Hello")');

// Read file
const content = await sandbox.filesystem.readFile('/tmp/hello.py');

// Create directory
await sandbox.filesystem.mkdir('/tmp/mydir');

// List directory
const files = await sandbox.filesystem.readdir('/tmp');

// Check if exists
const exists = await sandbox.filesystem.exists('/tmp/hello.py');

// Remove file/directory
await sandbox.filesystem.remove('/tmp/hello.py');

Shell Commands

Use runCommand() for shell operations, package installation, or system commands. It provides full shell access with detailed execution results including stdout, stderr, exit codes, and execution time.

// Run shell command
const result = await sandbox.runCommand('ls -la');
console.log(result.stdout);

// With different working directory
const result2 = await sandbox.runCommand('pwd', { cwd: '/tmp' });

Error Handling

ComputeSDK methods throw exceptions for API/network failures. For command execution errors, check the exitCode in the result rather than relying on exceptions. Exit code 0 indicates success, non-zero indicates failure.

try {
  const sandbox = await compute.sandbox.create();
  const result = await sandbox.runCommand('some-command');
} catch (error) {
  console.error('Failed:', error.message);
}

Essential Patterns

Resource Cleanup (Critical for Production)

Always destroy sandboxes when done to avoid resource leaks and unnecessary costs. Sandboxes consume resources until explicitly destroyed or they timeout.

// ✅ Recommended: Use try-finally
let sandbox;
try {
  sandbox = await compute.sandbox.create();
  await sandbox.runCommand('echo "Hello"');
} finally {
  await sandbox?.destroy();
}

Error Handling with Exit Codes

Commands return exit codes following Unix conventions: 0 means success, non-zero indicates failure. Always check exitCode rather than catching exceptions for command failures.

const result = await sandbox.runCommand('npm test');
if (result.exitCode !== 0) {
  console.error('Tests failed:', result.stderr);
} else {
  console.log('Tests passed!', result.stdout);
}

Understanding Results

Command Execution Results

When you call runCommand(), you receive:

• stdout: Standard output (normal program output)
• stderr: Standard error (error messages and warnings)
• exitCode: 0 for success, non-zero for failures
• durationMs: Execution time in milliseconds

const result = await sandbox.runCommand('npm install');
console.log(result.stdout);      // Installation logs
console.log(result.stderr);      // Warnings or errors
console.log(result.exitCode);    // 0
console.log(result.durationMs);  // 2341