ComputeSDK Playground

<button 
    on:click={executeCode} 
    disabled={loading || disabled || !code.trim()}
    class="px-4 py-2 bg-blue-500 text-white rounded disabled:opacity-50"
  >
    {loading ? 'Executing...' : 'Execute Code'}
  </button>
</div>
```

## Configuration

[Section titled “Configuration”](#configuration)

### SvelteKit Config

[Section titled “SvelteKit Config”](#sveltekit-config)

```
// vite.config.js
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [sveltekit()],
  define: {
    // Add any global defines here
  }
});
```

```
// svelte.config.js
import adapter from '@sveltejs/adapter-auto';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  kit: {
    adapter: adapter(),
    csrf: {
      checkOrigin: false  // Only for development
    }
  }
};

export default config;
```

### TypeScript Config

[Section titled “TypeScript Config”](#typescript-config)

```
{
  "extends": "./.svelte-kit/tsconfig.json",
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "sourceMap": true,
    "strict": true
  }
}
```

## Deployment

[Section titled “Deployment”](#deployment)

### Environment Variables

[Section titled “Environment Variables”](#environment-variables)

Set your environment variables in your deployment platform:

```
# Production environment variables
E2B_API_KEY=your_production_e2b_key
VERCEL_TOKEN=your_production_vercel_token
VERCEL_TEAM_ID=your_team_id
VERCEL_PROJECT_ID=your_project_id
DAYTONA_API_KEY=your_production_daytona_key
```

### Docker Deployment

[Section titled “Docker Deployment”](#docker-deployment)

```
# Dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json .
RUN npm ci
COPY . .
RUN npm run build
RUN npm prune --production

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/build build/
COPY --from=builder /app/node_modules node_modules/
COPY package.json .
EXPOSE 3000
ENV NODE_ENV=production
CMD ["node", "build"]
```

## Troubleshooting

[Section titled “Troubleshooting”](#troubleshooting)

**Environment variables not loading?**

* Use `$env/static/private` for server-side variables
* Use `$env/static/public` only for public variables (not API keys)
* Restart dev server after changes to `.env`
* Check that variables are properly exported in deployment platform

**Sandbox creation fails?**

* Verify API keys are correct and have proper format
* Check provider-specific setup requirements
* Monitor rate limits and quotas
* Ensure environment variables are available in server context

**Import errors?**

* ComputeSDK can only be imported in server-side routes (+server.ts files)
* Don’t import ComputeSDK in +page.svelte or +layout.svelte files
* Use API routes to bridge between client and ComputeSDK

**Build errors?**

* Ensure all ComputeSDK imports are in server routes only
* Check that environment variables are properly configured
* Verify provider packages are correctly installed

**Form actions not working?**

* Ensure forms have proper method=“POST” and action attributes
* Use `use:enhance` for progressive enhancement
* Handle form validation and error states properly

**Stores not updating?**

* Make sure store updates are reactive ($: syntax)
* Use proper store methods (update, set)
* Handle loading and error states in store logic

# Installation

ComputeSDK provides a unified abstraction layer for executing code in secure, isolated sandboxed environments across multiple cloud providers.

## Core SDK

[Section titled “Core SDK”](#core-sdk)

Install the core ComputeSDK package:

```
npm install computesdk
```

## Provider Packages

[Section titled “Provider Packages”](#provider-packages)

ComputeSDK is modular - install only the providers you need:

```
# E2B provider - Full development environment
npm install @computesdk/e2b

# Vercel provider - Scalable serverless execution  
npm install @computesdk/vercel

# Daytona provider - Development workspaces
npm install @computesdk/daytona

# Modal provider - GPU-accelerated Python workloads
npm install @computesdk/modal

# CodeSandbox provider - Collaborative sandboxes
npm install @computesdk/codesandbox

# Frontend integration (optional)
npm install @computesdk/ui
```

## Provider Setup

[Section titled “Provider Setup”](#provider-setup)

### E2B - Full Development Environment

[Section titled “E2B - Full Development Environment”](#e2b---full-development-environment)

E2B provides full filesystem and terminal support with data science libraries:

```
export E2B_API_KEY=e2b_your_api_key_here
```

### Vercel - Scalable Serverless Execution

[Section titled “Vercel - Scalable Serverless Execution”](#vercel---scalable-serverless-execution)

Vercel provides reliable execution with up to 45 minutes runtime:

```
# Method 1: OIDC Token (Recommended)
vercel env pull  # Downloads VERCEL_OIDC_TOKEN

# Method 2: Traditional
export VERCEL_TOKEN=your_vercel_token_here
export VERCEL_TEAM_ID=your_team_id_here
export VERCEL_PROJECT_ID=your_project_id_here
```

### Daytona - Development Workspaces

[Section titled “Daytona - Development Workspaces”](#daytona---development-workspaces)

Daytona provides development workspace environments:

```
export DAYTONA_API_KEY=your_daytona_api_key_here
```

### Modal - GPU-Accelerated Python Workloads

[Section titled “Modal - GPU-Accelerated Python Workloads”](#modal---gpu-accelerated-python-workloads)

Modal provides serverless cloud compute with GPU support:

```
export MODAL_TOKEN_ID=your_modal_token_id_here
export MODAL_TOKEN_SECRET=your_modal_token_secret_here
```

### CodeSandbox - Collaborative Sandboxes

[Section titled “CodeSandbox - Collaborative Sandboxes”](#codesandbox---collaborative-sandboxes)

CodeSandbox provides collaborative development environments:

```
export CSB_API_KEY=your_codesandbox_api_key_here
```

# Introduction

## What is ComputeSDK?

[Section titled “What is ComputeSDK?”](#what-is-computesdk)

ComputeSDK is a free and open-source toolkit for running other people’s code in your applications. Think of it as the “AI SDK for compute” - providing a consistent TypeScript interface whether you’re using E2B, Vercel, Daytona, Modal, CodeSandbox, or Blaxel.

## Why ComputeSDK?

[Section titled “Why ComputeSDK?”](#why-computesdk)

🔄 **Provider-agnostic** - Switch between E2B, Vercel, Daytona, Modal, CodeSandbox, Blaxel, and more without code changes\
🛡️ **Security-first** - Isolated sandboxes protect your infrastructure\
⚡ **Developer experience** - Simple, TypeScript-native API\
🌍 **Production-ready** - Used by teams building the next generation of developer tools

### Perfect for building:

[Section titled “Perfect for building:”](#perfect-for-building)

* **Code execution platforms** - Run user-submitted code safely
* **Educational tools** - Interactive coding environments
* **Data analysis applications** - Process code with full filesystem access
* **AI-powered development tools** - Let AI agents write and execute code
* **Testing & CI/CD systems** - Isolated test environments

## Features

[Section titled “Features”](#features)

🚀 **Multi-provider support** - E2B, Vercel, Daytona, Modal, CodeSandbox, Blaxel, and more\
📁 **Filesystem operations** - Read, write, create directories across providers\
⚡ **Command execution** - Run shell commands directly\
🛡️ **Type-safe** - Full TypeScript support with comprehensive error handling\
📦 **Modular** - Install only the providers you need\
🔧 **Extensible** - Easy to add custom providers\
🌐 **Web Framework Integration** - Built-in request handlers for Next.js, Nuxt, SvelteKit, etc.\
🎨 **Frontend Integration** - Client-side hooks and utilities via @computesdk/ui

## Quick Example

[Section titled “Quick Example”](#quick-example)

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

// Set default provider
const compute = createCompute({ 
  defaultProvider: e2b({ apiKey: process.env.E2B_API_KEY }) 
});

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

// Execute code
const result = await sandbox.runCode('print("Hello World!")');
console.log(result.stdout); // "Hello World!"

// Clean up
await compute.sandbox.destroy(sandbox.sandboxId);
```

## Next Steps

[Section titled “Next Steps”](#next-steps)

Ready to get started? Check out our [installation guide](./installation.md) or dive into the [quick start](./quick-start.md) to begin building with ComputeSDK.

# 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

[Section titled “Installation”](#installation)

```
# Core SDK
npm install computesdk

# Provider packages (install only what you need)
npm install @computesdk/e2b        # E2B provider
npm install @computesdk/vercel     # Vercel provider  
npm install @computesdk/daytona    # Daytona provider
npm install @computesdk/modal      # Modal provider
npm install @computesdk/codesandbox # CodeSandbox provider

# Frontend integration (optional)
npm install @computesdk/ui         # React hooks and utilities
```

## Basic Usage

[Section titled “Basic Usage”](#basic-usage)

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

// Set default provider
const compute = createCompute({ 
  defaultProvider: e2b({ apiKey: process.env.E2B_API_KEY }) 
});

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

// Get instance
const instance = sandbox.getInstance();

// Execute code
const result = await sandbox.runCode('print("Hello World!")');
console.log(result.stdout); // "Hello World!"

// Clean up
await compute.sandbox.destroy(sandbox.sandboxId);
```

## Provider-Specific Setup

[Section titled “Provider-Specific Setup”](#provider-specific-setup)

### E2B - Full Development Environment

[Section titled “E2B - Full Development Environment”](#e2b---full-development-environment)

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

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

const sandbox = await compute.sandbox.create();

// Get instance
const instance = sandbox.getInstance();

// Execute Python with data science libraries
const result = await sandbox.runCode(`
import pandas as pd
import numpy as np

data = {'A': [1, 2, 3], 'B': [4, 5, 6]}
df = pd.DataFrame(data)
print(df)
print(f"Sum: {df.sum().sum()}")
`);

console.log(result.stdout);
```

### Vercel - Serverless Execution

[Section titled “Vercel - Serverless Execution”](#vercel---serverless-execution)

```
import { createCompute } from 'computesdk';
import { vercel } from '@computesdk/vercel';

const compute = createCompute({ 
  defaultProvider: vercel({ runtime: 'node' }) 
});

const sandbox = await compute.sandbox.create();

// Get instance
const instance = sandbox.getInstance();

// Execute Node.js or Python
const result = await sandbox.runCode(`
console.log('Node.js version:', process.version);
console.log('Hello from Vercel!');
`);

console.log(result.stdout);
```

### Daytona - Development Workspaces

[Section titled “Daytona - Development Workspaces”](#daytona---development-workspaces)

```
import { createCompute } from 'computesdk';
import { daytona } from '@computesdk/daytona';

const compute = createCompute({ 
  defaultProvider: daytona({ apiKey: process.env.DAYTONA_API_KEY }) 
});

const sandbox = await compute.sandbox.create();

// Get instance
const instance = sandbox.getInstance();

// Execute in development workspace
const result = await sandbox.runCode(`
print('Hello from Daytona!')
import sys
print(f'Python version: {sys.version}')
`);

console.log(result.stdout);
```

### Modal - GPU-Accelerated Python Workloads

[Section titled “Modal - GPU-Accelerated Python Workloads”](#modal---gpu-accelerated-python-workloads)

```
import { createCompute } from 'computesdk';
import { modal } from '@computesdk/modal';

const compute = createCompute({ 
  defaultProvider: modal({ 
    tokenId: process.env.MODAL_TOKEN_ID,
    tokenSecret: process.env.MODAL_TOKEN_SECRET 
  }) 
});

const sandbox = await compute.sandbox.create();

// Get instance
const instance = sandbox.getInstance();

// Execute GPU-accelerated Python workloads
const result = await sandbox.runCode(`
import torch
print(f'PyTorch version: {torch.__version__}')
print(f'CUDA available: {torch.cuda.is_available()}')

# Example GPU computation
if torch.cuda.is_available():
    x = torch.rand(1000, 1000).cuda()
    y = torch.mm(x, x)
    print(f'GPU computation result shape: {y.shape}')
else:
    print('Running on CPU')
`);

console.log(result.stdout);
```

### CodeSandbox - Collaborative Sandboxes

[Section titled “CodeSandbox - Collaborative Sandboxes”](#codesandbox---collaborative-sandboxes)

```
import { createCompute } from 'computesdk';
import { codesandbox } from '@computesdk/codesandbox';

const compute = createCompute({ 
  defaultProvider: codesandbox({ 
    apiKey: process.env.CSB_API_KEY 
  }) 
});

const sandbox = await compute.sandbox.create();

// Get instance
const instance = sandbox.getInstance();

// Execute in collaborative environment
const result = await sandbox.runCode(`
const message = "Hello from CodeSandbox!";
console.log(message);

const data = { users: 3, tasks: 15 };
console.log(JSON.stringify(data, null, 2));
`);

console.log(result.stdout);
```

## Filesystem Operations

[Section titled “Filesystem Operations”](#filesystem-operations)

```
// 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

[Section titled “Shell Commands”](#shell-commands)

```
// 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

[Section titled “Error Handling”](#error-handling)

```
try {
  const sandbox = await compute.sandbox.create();
  const result = await sandbox.runCode('invalid code');
} catch (error) {
  console.error('Execution failed:', error.message);
  // Handle specific error types as needed
}
```

# LLM Documentation Files

> AI-optimized documentation files for training large language models

ComputeSDK provides AI-optimized documentation files specifically designed for training large language models (LLMs) and AI assistants. These files contain our complete documentation in a format that’s easy for AI systems to understand and use.

## Available Files

[Section titled “Available Files”](#available-files)

### [llms-small.txt](/llms-small.txt)

[Section titled “llms-small.txt”](#llms-smalltxt)

A minimal version containing essential information about ComputeSDK, perfect for quick AI context.

### [llms-full.txt](/llms-full.txt)

[Section titled “llms-full.txt”](#llms-fulltxt)

The complete documentation including all guides, API references, and provider information. This comprehensive file contains everything an AI needs to help users with ComputeSDK.

# Blaxel

Blaxel provider for ComputeSDK

# @computesdk/blaxel

[Section titled “@computesdk/blaxel”](#computesdkblaxel)

Blaxel provider for ComputeSDK - Execute code in secure Blaxel sandboxes with 25ms cold starts and real-time preview URLs.

## Installation

[Section titled “Installation”](#installation)

```
npm install @computesdk/blaxel
```

## Usage

[Section titled “Usage”](#usage)

### With ComputeSDK

[Section titled “With ComputeSDK”](#with-computesdk)

```
import { compute } from 'computesdk';
import { blaxel } from '@computesdk/blaxel';

// Set as default provider
compute.setConfig({ 
  provider: blaxel({ 
    apiKey: process.env.BLAXEL_API_KEY,
    workspace: process.env.BLAXEL_WORKSPACE 
  }) 
});

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

// Execute code
const result = await sandbox.runCode('console.log("Hello from Blaxel!")');
console.log(result.stdout); // "Hello from Blaxel!"

// Clean up
await sandbox.destroy();
```

### Direct Usage

[Section titled “Direct Usage”](#direct-usage)

```
import { blaxel } from '@computesdk/blaxel';

// Create provider with configuration
const provider = blaxel({ 
  workspace: 'your-workspace',
  apiKey: 'your-api-key',
  image: 'blaxel/prod-py-app:latest',  // Python image
  memory: 8192,                         // 8GB RAM
  ports: [3000, 8080]                  // Exposed ports
});

// Use with compute singleton
const sandbox = await compute.sandbox.create({ 
  provider,
  options: {
    runtime: 'python',  // Runtime specified at creation time
    timeout: 3600000,   // 1 hour timeout
    envs: { 
      DEBUG: 'true' 
    }
  }
});
```

## Configuration

[Section titled “Configuration”](#configuration)

### Environment Variables

[Section titled “Environment Variables”](#environment-variables)

```
export BL_WORKSPACE=your_workspace_id
export BL_API_KEY=your_api_key_here
```

### Configuration Options

[Section titled “Configuration Options”](#configuration-options)

```
interface BlaxelConfig {
  /** Blaxel workspace ID - fallback to BL_WORKSPACE env var */
  workspace?: string;
  /** Blaxel API key - fallback to BL_API_KEY env var */
  apiKey?: string;
  /** Default image for sandboxes */
  image?: string;
  /** Default region for sandbox deployment */
  region?: string;
  /** Default memory allocation in MB (default: 4096) */
  memory?: number;
  /** Default ports for sandbox (default: [3000]) */
  ports?: number[];
}
```

> 💡 **Note:** For persistent storage across sandbox sessions, see [Mounting & using sandbox volumes](https://docs.blaxel.ai/Sandboxes/Volumes)

### Default Images

[Section titled “Default Images”](#default-images)

The provider automatically selects images based on runtime:

* **Python:** `blaxel/prod-py-app:latest`
* **Node.js:** `blaxel/prod-ts-app:latest`
* **Default:** `blaxel/prod-base:latest`

## Features

[Section titled “Features”](#features)

* ✅ **Code Execution** - Python and Node.js runtime support with proper stdout/stderr streaming
* ✅ **Command Execution** - Run shell commands with background support
* ✅ **Filesystem Operations** - Full file system access (read, write, mkdir, ls, rm)
* ✅ **Auto Runtime Detection** - Automatically detects Python vs Node.js from code patterns
* ✅ **Custom Images** - Support for custom Docker images
* ✅ **Memory Configuration** - Configurable memory allocation
* ✅ **Preview URLs** - Public/private preview URLs with TTL, custom domains, and headers
* ✅ **Environment Variables** - Pass custom environment variables to sandboxes
* ✅ **Metadata Labels** - Attach custom metadata to sandboxes
* ✅ **Multi-Port Support** - Configure multiple ports for sandbox access
* ✅ **Status Detection** - Automatic conversion of Blaxel status to standard format

> 📚 For more details, see the [Sandbox technical guide](https://docs.blaxel.ai/Sandboxes/Overview)

## API Reference

[Section titled “API Reference”](#api-reference)

### Code Execution

[Section titled “Code Execution”](#code-execution)

```
// Execute Python code
const result = await sandbox.runCode(`
import json
data = {"message": "Hello from Python"}
print(json.dumps(data))
`, 'python');

// Execute Node.js code  
const result = await sandbox.runCode(`
const data = { message: "Hello from Node.js" };
console.log(JSON.stringify(data));
`, 'node');

// Auto-detection (based on code patterns)
const result = await sandbox.runCode('print("Auto-detected as Python")');
```

### Command Execution

[Section titled “Command Execution”](#command-execution)

```
// List files
const result = await sandbox.runCommand('ls', ['-la']);

// Install packages
const result = await sandbox.runCommand('pip', ['install', 'requests']);

// Run background process
const bgResult = await sandbox.runCommand('npm', ['start'], { background: true });
console.log('Process started in background');
```

### Filesystem Operations

[Section titled “Filesystem Operations”](#filesystem-operations)

> 📚 For detailed filesystem API documentation, see the [Sandbox API reference](https://docs.blaxel.ai/api-reference/filesystem/get-file-or-directory-information)

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

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

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

// List directory contents with metadata
const files = await sandbox.filesystem.readdir('/tmp');
// Returns FileEntry[] with name, path, isDirectory, size, lastModified

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

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

### Sandbox Management

[Section titled “Sandbox Management”](#sandbox-management)

```
// Get sandbox info
const info = await sandbox.getInfo();
console.log(info.id, info.provider, info.status, info.runtime);
// Status: 'running', 'stopped', or 'error'
// Runtime: Automatically detected from image name

// Create with specific configuration
const sandbox = await provider.sandbox.create({
  runtime: 'python',              // Selects appropriate image
  timeout: 1800000,               // 30 minutes in milliseconds (converted to "1800s")
  envs: {                         // Environment variables
    API_KEY: 'secret-key',
    NODE_ENV: 'production'
  },
  metadata: {                     // Custom metadata labels
    labels: {
      project: 'my-project',
      environment: 'staging'
    }
  }
});

// Create with custom memory and region
const customSandbox = await provider.sandbox.create({
  memory: 8192,                   // 8GB RAM
  region: 'us-pdx-1',            // See regions documentation below
  ports: [3000, 8080, 9000]      // Multiple ports
});

> 📚 Learn more: [Deployment regions](https://docs.blaxel.ai/Infrastructure/Regions) | [Specifying region when creating sandboxes](https://docs.blaxel.ai/Sandboxes/Overview#create-a-sandbox)

// Reconnect to existing sandbox
const existing = await provider.sandbox.create({ 
  sandboxId: 'blaxel-1234567890' 
});

// Get sandbox by ID
const sandbox = await provider.sandbox.getById('blaxel-1234567890');

// Destroy sandbox
await provider.sandbox.destroy('blaxel-1234567890');
```

### Preview URLs

[Section titled “Preview URLs”](#preview-urls)

> 📚 For a complete guide, see [Creating preview URLs & custom domains](https://docs.blaxel.ai/Sandboxes/Preview-url)

```
// getUrl options interface
interface GetUrlOptions {
  port: number;                     // Port number to expose
  ttl?: number;                     // Preview TTL in milliseconds
  prefixUrl?: string;               // Custom prefix URL for the preview
  customDomain?: string;            // Custom domain for the preview
  headers?: {
    response?: Record<string, string>;  // Response headers sent to clients
    request?: Record<string, string>;   // Request headers for internal routing
  };
  authentication?: {
    public?: boolean;               // Create public preview (default: true)
    tokenExpiryMinutes?: number;    // Token expiry for private previews (default: 60)
  };
}

// Create a public preview URL (default headers applied)
const publicUrl = await sandbox.getUrl({ port: 3000 });
console.log(publicUrl); // https://tkmu0oj2bf6iuoag6mmlt8.preview.bl.run

// Create a private preview URL with authentication token
const privateUrl = await sandbox.getUrl({ 
  port: 3000,
  authentication: {
    public: false,
    tokenExpiryMinutes: 30  // Token expires in 30 minutes (default: 60)
  }
});
console.log(privateUrl); 
// https://tkmu0oj2bf6iuoag6mmlt8.preview.bl.run?bl_preview_token=<token>

// Create preview with custom TTL (Time To Live)
const shortLivedUrl = await sandbox.getUrl({
  port: 3000,
  ttl: 300000  // Preview expires in 5 minutes (300,000 ms)
});

// Create preview with custom CORS headers (replaces all defaults)
const customUrl = await sandbox.getUrl({
  port: 3000,
  headers: {
    response: {
      "Access-Control-Allow-Origin": "https://mydomain.com",
      "Access-Control-Allow-Methods": "GET, POST",
      "Access-Control-Allow-Credentials": "true",
      "X-Custom-Header": "custom-value"
    },
    request: {
      "X-Internal-Auth": "internal-token"
    }
  }
});

// Create preview with custom domain
const customDomainUrl = await sandbox.getUrl({
  port: 3000,
  customDomain: "app.example.com"
});

// Create preview with custom prefix URL
const prefixedUrl = await sandbox.getUrl({
  port: 3000,
  prefixUrl: "my-preview"
});
// https://my-preview-my-workspace.preview.bl.run

// Full example with all options
const advancedUrl = await sandbox.getUrl({
  port: 3000,
  ttl: 3600000,  // 1 hour TTL
  prefixUrl: "my-preview",
  customDomain: "preview.myapp.com",
  headers: {
    response: {
      "Access-Control-Allow-Origin": "https://myapp.com",
      "X-Frame-Options": "SAMEORIGIN"
    },
    request: {
      "X-API-Version": "v2"
    }
  },
  authentication: {
    public: false,
    tokenExpiryMinutes: 120  // 2 hour token
  }
});

// The token is automatically appended to the URL for private previews
// You can also pass the token as a header: X-Blaxel-Preview-Token
```

### Direct Instance Access

[Section titled “Direct Instance Access”](#direct-instance-access)

> 📚 You can also [connect to sandboxes remotely from a terminal](https://docs.blaxel.ai/Sandboxes/Overview#connect-to-a-sandbox-with-a-terminal) for direct access

```
import { createBlaxelCompute } from '@computesdk/blaxel';

const compute = createBlaxelCompute({ 
  workspace: 'your-workspace',
  apiKey: 'your-key',
  memory: 4096,
  ports: [3000]
});

const sandbox = await compute.sandbox.create();
const instance = sandbox.getInstance(); // Typed as SandboxInstance

// Use Blaxel-specific features directly
const result = await instance.process.exec({ 
  command: 'ls -la'
});

// Stream logs from process
const stream = instance.process.streamLogs(result.name, {
  onStdout(data) { console.log('stdout:', data); },
  onStderr(data) { console.error('stderr:', data); }
});

// Wait for completion
await instance.process.wait(result.name);
stream.close();

// Access Blaxel filesystem API
await instance.fs.write('/tmp/test.txt', 'Hello Blaxel');
const content = await instance.fs.read('/tmp/test.txt');

// Create preview with Blaxel API
const preview = await instance.previews.create({
  spec: {
    port: 3000,
    public: true
  }
});
```

## Runtime Detection

[Section titled “Runtime Detection”](#runtime-detection)

The provider automatically detects the runtime based on code patterns:

**Python indicators:**

* `print(` statements
* `import` statements
* `def` function definitions
* Python-specific syntax (`f"`, `f'`, `__`, `sys.`, `json.`)

**Default:** Node.js for all other cases

## Error Handling

[Section titled “Error Handling”](#error-handling)

```
try {
  const result = await sandbox.runCode('invalid code');
} catch (error) {
  if (error.message.includes('Syntax error')) {
    console.error('Code has syntax errors');
  } else if (error.message.includes('authentication')) {
    console.error('Check your BL_API_KEY');
  } else if (error.message.includes('quota')) {
    console.error('Blaxel usage limits reached');
  }
}
```

### Exit Codes

[Section titled “Exit Codes”](#exit-codes)

* `0` - Success
* `1` - General error or runtime error
* `127` - Command not found

## Web Framework Integration

[Section titled “Web Framework Integration”](#web-framework-integration)

Use with web frameworks via the request handler:

```
import { handleComputeRequest } from 'computesdk';
import { blaxel } from '@computesdk/blaxel';

export async function POST(request: Request) {
  return handleComputeRequest({
    request,
    provider: blaxel({ apiKey: process.env.BL_API_KEY })
  });
}
```

## Examples

[Section titled “Examples”](#examples)

### Data Processing

[Section titled “Data Processing”](#data-processing)

```
const result = await sandbox.runCode(`
import json

# Process data
data = [1, 2, 3, 4, 5]
result = {
    "sum": sum(data),
    "average": sum(data) / len(data),
    "max": max(data)
}

print(json.dumps(result))
`);

const output = JSON.parse(result.stdout);
console.log(output); // { sum: 15, average: 3, max: 5 }
```

### File Processing

[Section titled “File Processing”](#file-processing)

```
// Create data file
await sandbox.filesystem.writeFile('/tmp/data.json', 
  JSON.stringify({ users: ['Alice', 'Bob', 'Charlie'] })
);

// Process file
const result = await sandbox.runCode(`
import json

with open('/tmp/data.json', 'r') as f:
    data = json.load(f)

# Process users
user_count = len(data['users'])
print(f"Found {user_count} users")

# Save result
result = {"user_count": user_count, "processed": True}
with open('/tmp/result.json', 'w') as f:
    json.dump(result, f)
`);

// Read result
const resultData = await sandbox.filesystem.readFile('/tmp/result.json');
console.log(JSON.parse(resultData));
```

### Web Scraping Example

[Section titled “Web Scraping Example”](#web-scraping-example)

```
// Install dependencies
await sandbox.runCommand('pip', ['install', 'requests', 'beautifulsoup4']);

// Scrape website
const result = await sandbox.runCode(`
import requests
from bs4 import BeautifulSoup
import json

# Fetch webpage
response = requests.get('https://example.com')
soup = BeautifulSoup(response.text, 'html.parser')

# Extract title
title = soup.find('title').text if soup.find('title') else 'No title'

# Output result
result = {
    "status_code": response.status_code,
    "title": title,
    "content_length": len(response.text)
}

print(json.dumps(result))
`);

console.log(JSON.parse(result.stdout));
```

### API Development

[Section titled “API Development”](#api-development)

```
// Create a simple API server
await sandbox.filesystem.writeFile('/tmp/server.js', `
const http = require('http');

server.listen(3000, () => {
  console.log('Server running on port 3000');
});
`);

// Start server in background
await sandbox.runCommand('node', ['/tmp/server.js'], { background: true });

// Get the preview URL (public by default)
const url = await sandbox.getUrl({ port: 3000 });
console.log(`API available at: ${url}`);
// Example: https://tkmu0oj2bf6iuoag6mmlt8.preview.bl.run

// Or create a private API endpoint with authentication
const privateUrl = await sandbox.getUrl({ 
  port: 3000,
  authentication: {
    public: false,
    tokenExpiryMinutes: 120  // 2 hour token
  }
});
console.log(`Private API: ${privateUrl}`);
```

## Authentication Methods

[Section titled “Authentication Methods”](#authentication-methods)

1. **Automatic (when running on Blaxel)** - No configuration needed
2. **Via Configuration** - Pass credentials directly
3. **Via Environment Variables** - Set BL\_WORKSPACE and BL\_API\_KEY
4. **Via Blaxel CLI** - Run `bl login` for local development

## Sandbox URLs

[Section titled “Sandbox URLs”](#sandbox-urls)

Blaxel sandboxes are accessible via dynamically generated preview URLs:

```
https://{unique-id}.preview.bl.run or https://{unique-id}.{region}.preview.bl.run
```

Or with custom domain:

```
https://{unique-id}.{custom-domain}
```

> 📚 Learn more about [preview URLs and custom domains](https://docs.blaxel.ai/Sandboxes/Preview-url)

### Public vs Private Previews

[Section titled “Public vs Private Previews”](#public-vs-private-previews)

**Public Previews** (default):

* No authentication required
* Accessible to anyone with the URL
* Suitable for public demos and testing

**Private Previews**:

* Require authentication token
* Token can be passed as `bl_preview_token` query parameter
* Token can also be passed as `X-Blaxel-Preview-Token` header
* Configurable token expiry time

### Preview Configuration Options

[Section titled “Preview Configuration Options”](#preview-configuration-options)

**TTL (Time To Live)**:

* Controls how long the preview URL remains active
* Specified in milliseconds
* Automatically converted to Blaxel’s format (e.g., “300s” for 5 minutes)

**Custom Domain**:

* Use your own domain for preview URLs
* Must be configured in Blaxel settings

**Prefix URL**:

* Add a path prefix to all preview URLs
* Useful for API versioning or routing

**Headers**:

* `response`: Headers sent to clients accessing the preview
* `request`: Headers used for internal routing within Blaxel

**Default Response Headers**:

The provider applies these CORS headers by default when no custom response headers are provided:

```
{
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS, PATCH",
  "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Requested-With, X-Blaxel-Preview-Token, X-Blaxel-Authorization",
  "Access-Control-Allow-Credentials": "true",
  "Access-Control-Expose-Headers": "Content-Length, X-Request-Id",
  "Access-Control-Max-Age": "86400",
  "Vary": "Origin"
}
```

**Note:** If you provide custom response headers, they completely replace the defaults. Make sure to include all necessary CORS headers when providing custom headers.

Example:

```
// Public preview with default headers and settings
const url = await sandbox.getUrl({ port: 3000 });

// Private preview with 2-hour token and 24-hour TTL
const secureUrl = await sandbox.getUrl({ 
  port: 3000,
  ttl: 86400000,  // 24 hours in milliseconds
  authentication: {
    public: false,
    tokenExpiryMinutes: 120
  }
});

// Private preview with complete custom headers (replaces all defaults)
const customSecureUrl = await sandbox.getUrl({
  port: 3000,
  authentication: {
    public: false,
    tokenExpiryMinutes: 60
  },
  headers: {
    response: {
      // Must include all necessary CORS headers when providing custom headers, if you want ot
      "Access-Control-Allow-Origin": "https://app.example.com",
      "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE",
      "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Blaxel-Preview-Token",
      "Access-Control-Allow-Credentials": "true",
      "X-Frame-Options": "SAMEORIGIN"
    },
    request: {
      "X-Service-Name": "preview-service",
      "X-Request-ID": "unique-request-id"
    }
  }
});
```

The provider automatically creates appropriate preview URLs with CORS headers configured for broad compatibility.

## Further Reading

[Section titled “Further Reading”](#further-reading)

### Core Documentation

[Section titled “Core Documentation”](#core-documentation)

* [Sandbox technical guide](https://docs.blaxel.ai/Sandboxes/Overview) - Comprehensive overview of Blaxel sandboxes
* [Sandbox API reference](https://docs.blaxel.ai/api-reference/filesystem/get-file-or-directory-information) - Complete API documentation for filesystem operations
* [ComputeSDK documentation](https://github.com/computesdk/computesdk) - Main SDK documentation

### Guides

[Section titled “Guides”](#guides)

* [Creating preview URLs & custom domains](https://docs.blaxel.ai/Sandboxes/Preview-url) - Detailed guide on preview configuration
* [Connecting to sandboxes remotely](https://docs.blaxel.ai/Sandboxes/Overview#connect-to-a-sandbox-with-a-terminal) - Terminal access to running sandboxes
* [Deployment regions](https://docs.blaxel.ai/Infrastructure/Regions) - Available regions and selection guide
* [Specifying regions for sandboxes](https://docs.blaxel.ai/Sandboxes/Overview#create-a-sandbox) - Region configuration during sandbox creation
* [Mounting & using sandbox volumes](https://docs.blaxel.ai/Sandboxes/Volumes) - Persistent storage with volumes

### Support

[Section titled “Support”](#support)

Feel free to reach out if you have any questions — we’re here to help!

## License

[Section titled “License”](#license)

MIT

# Codesandbox

CodeSandbox provider for ComputeSDK - Execute code in web-based development environments.

## Installation

[Section titled “Installation”](#installation)

```
npm install @computesdk/codesandbox
```

## Usage

[Section titled “Usage”](#usage)

### With ComputeSDK

[Section titled “With ComputeSDK”](#with-computesdk)

```
import { createCompute } from 'computesdk';
import { codesandbox } from '@computesdk/codesandbox';

// Set as default provider
const compute = createCompute({ 
  defaultProvider: codesandbox({ apiKey: process.env.CODESANDBOX_API_KEY }) 
});

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

// Get instance
const instance = sandbox.getInstance();

// Execute code
const result = await sandbox.runCode('console.log("Hello from CodeSandbox!")');
console.log(result.stdout); // "Hello from CodeSandbox!"

// Clean up
await compute.sandbox.destroy(sandbox.sandboxId);
```

### Direct Usage

[Section titled “Direct Usage”](#direct-usage)

```
import { codesandbox } from '@computesdk/codesandbox';

// Create provider
const provider = codesandbox({ 
  apiKey: 'your-api-key',
  template: 'react'
});

// Use with compute singleton
const sandbox = await compute.sandbox.create({ provider });
```

## Configuration

[Section titled “Configuration”](#configuration)

### Environment Variables

[Section titled “Environment Variables”](#environment-variables)

```
export CODESANDBOX_API_KEY=your_codesandbox_api_key_here
```

### Configuration Options

[Section titled “Configuration Options”](#configuration-options)

```
interface CodeSandboxConfig {
  /** CodeSandbox API key - if not provided, will use CODESANDBOX_API_KEY env var */
  apiKey?: string;
  /** Project template to use */
  template?: 'react' | 'vue' | 'angular' | 'nextjs' | 'node' | 'vanilla';
  /** Execution timeout in milliseconds */
  timeout?: number;
  /** Enable public access to sandbox */
  publicAccess?: boolean;
  /** Base URL for CodeSandbox API */
  baseUrl?: string;
}
```

## API Reference

[Section titled “API Reference”](#api-reference)

### Code Execution

[Section titled “Code Execution”](#code-execution)

```
// Execute JavaScript code
const result = await sandbox.runCode(`
const data = { message: "Hello from JavaScript", timestamp: Date.now() };
console.log(JSON.stringify(data));
`, 'javascript');

// Execute TypeScript code  
const result = await sandbox.runCode(`
interface Message {
  text: string;
  timestamp: number;
}

const message: Message = {
  text: "Hello from TypeScript",
  timestamp: Date.now()
};

console.log(JSON.stringify(message));
`, 'typescript');

// Auto-detection (based on code patterns)
const result = await sandbox.runCode('console.log("Auto-detected as JavaScript")');
```

### Command Execution

[Section titled “Command Execution”](#command-execution)

```
// Install npm packages
const result = await sandbox.runCommand('npm', ['install', 'lodash']);

// Run npm scripts
const result = await sandbox.runCommand('npm', ['run', 'build']);

// Start development server
const result = await sandbox.runCommand('npm', ['start']);
```

### Filesystem Operations

[Section titled “Filesystem Operations”](#filesystem-operations)

```
// Write file
await sandbox.filesystem.writeFile('/src/App.js', 'export default function App() { return <h1>Hello</h1>; }');

// Read file
const content = await sandbox.filesystem.readFile('/src/App.js');

// Create directory
await sandbox.filesystem.mkdir('/src/components');

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

// Check if file exists
const exists = await sandbox.filesystem.exists('/src/App.js');

// Remove file or directory
await sandbox.filesystem.remove('/src/App.js');
```

### Sandbox Management

[Section titled “Sandbox Management”](#sandbox-management)

```
// Get sandbox info (including live preview URL)
const info = await sandbox.getInfo();
console.log(info.id, info.provider, info.url);

// List all sandboxes
const sandboxes = await compute.sandbox.list();

// Get existing sandbox
const existing = await compute.sandbox.getById('sandbox-id');

// Destroy sandbox
await compute.sandbox.destroy('sandbox-id');
```

## Runtime Detection

[Section titled “Runtime Detection”](#runtime-detection)

The provider automatically detects the runtime based on code patterns:

**TypeScript indicators:**

* `interface`, `type` declarations
* TypeScript-specific syntax (`:`, `<T>`, etc.)
* `.ts` or `.tsx` file extensions

**Default:** JavaScript for all other cases

## Error Handling

[Section titled “Error Handling”](#error-handling)

```
try {
  const result = await sandbox.runCode('invalid code');
} catch (error) {
  if (error.message.includes('Syntax error')) {
    console.error('Code has syntax errors');
  } else if (error.message.includes('authentication failed')) {
    console.error('Check your CODESANDBOX_API_KEY');
  } else if (error.message.includes('template not found')) {
    console.error('Invalid template specified');
  }
}
```

## Web Framework Integration

[Section titled “Web Framework Integration”](#web-framework-integration)

Use with web frameworks via the request handler:

```
import { handleComputeRequest } from 'computesdk';
import { codesandbox } from '@computesdk/codesandbox';

export async function POST(request: Request) {
  return handleComputeRequest({
    request,
    provider: codesandbox({ apiKey: process.env.CODESANDBOX_API_KEY })
  });
}
```

## Examples

[Section titled “Examples”](#examples)

### React Application

[Section titled “React Application”](#react-application)

```
// Create React sandbox
const sandbox = await compute.sandbox.create({
  options: { template: 'react' }
});

// Create a custom component
await sandbox.filesystem.writeFile('/src/UserCard.js', `
import React from 'react';

function UserCard({ user }) {
  return (
    <div style={{
      border: '1px solid #ddd',
      borderRadius: '8px',
      padding: '16px',
      margin: '8px 0',
      backgroundColor: '#f9f9f9'
    }}>
      <h3>{user.name}</h3>
      <p>Email: {user.email}</p>
      <p>Role: {user.role}</p>
    </div>
  );
}

export default UserCard;
`);

// Update App.js
await sandbox.filesystem.writeFile('/src/App.js', `
import React from 'react';
import UserCard from './UserCard';

const users = [
  { id: 1, name: 'Alice Johnson', email: 'alice@example.com', role: 'Developer' },
  { id: 2, name: 'Bob Smith', email: 'bob@example.com', role: 'Designer' },
  { id: 3, name: 'Charlie Brown', email: 'charlie@example.com', role: 'Manager' }
];

function App() {
  return (
    <div style={{ padding: '20px', fontFamily: 'Arial, sans-serif' }}>
      <h1>Team Directory</h1>
      <p>Built with ComputeSDK + CodeSandbox</p>
      {users.map(user => (
        <UserCard key={user.id} user={user} />
      ))}
    </div>
  );
}

export default App;
`);

// Get the live preview URL
const info = await sandbox.getInfo();
console.log('Live preview:', info.url);
```

### Vue.js Application

[Section titled “Vue.js Application”](#vuejs-application)

```
// Create Vue sandbox
const sandbox = await compute.sandbox.create({
  options: { template: 'vue' }
});

// Create a Vue component
await sandbox.filesystem.writeFile('/src/components/TodoList.vue', `
<template>
  <div class="todo-app">
    <h2>Todo List</h2>
    <div class="add-todo">
      <input 
        v-model="newTodo" 
        @keyup.enter="addTodo"
        placeholder="Add a new todo..."
      />
      <button @click="addTodo">Add</button>
    </div>
    <ul class="todo-list">
      <li 
        v-for="todo in todos" 
        :key="todo.id"
        :class="{ completed: todo.completed }"
      >
        <input 
          type="checkbox" 
          v-model="todo.completed"
        />
        <span>{{ todo.text }}</span>
        <button @click="removeTodo(todo.id)">×</button>
      </li>
    </ul>
    <p>{{ completedCount }}/{{ todos.length }} completed</p>
  </div>
</template>

.add-todo {
  display: flex;
  gap: 10px;
  margin-bottom: 20px;
}

.todo-list {
  list-style: none;
  padding: 0;
}

.todo-list li {
  display: flex;
  align-items: center;
  gap: 10px;
  padding: 8px;
  border-bottom: 1px solid #eee;
}

.completed span {
  text-decoration: line-through;
  color: #888;
}
</style>
`);

// Update main App.vue
await sandbox.filesystem.writeFile('/src/App.vue', `
<template>
  <div id="app">
    <h1>Vue.js + ComputeSDK</h1>
    <TodoList />
  </div>
</template>

export default {
  name: 'App',
  components: {
    TodoList
  }
}
</script>

console.log('Vue.js app created successfully!');
```

### Node.js API

[Section titled “Node.js API”](#nodejs-api)

```
// Create Node.js sandbox
const sandbox = await compute.sandbox.create({
  options: { template: 'node' }
});

// Create Express server
await sandbox.filesystem.writeFile('/index.js', `
const express = require('express');
const cors = require('cors');

const app = express();
const port = process.env.PORT || 3000;

// Middleware
app.use(cors());
app.use(express.json());

// Sample data
const products = [
  { id: 1, name: 'Laptop', price: 999.99, category: 'Electronics' },
  { id: 2, name: 'Mouse', price: 29.99, category: 'Electronics' },
  { id: 3, name: 'Book', price: 19.99, category: 'Education' }
];

// Routes
app.get('/', (req, res) => {
  res.json({ 
    message: 'ComputeSDK API Server',
    endpoints: ['/api/products', '/api/products/:id']
  });
});

app.get('/api/products', (req, res) => {
  const { category } = req.query;
  let result = products;
  
  if (category) {
    result = products.filter(p => p.category.toLowerCase() === category.toLowerCase());
  }
  
  res.json({ products: result, total: result.length });
});

app.get('/api/products/:id', (req, res) => {
  const product = products.find(p => p.id === parseInt(req.params.id));
  
  if (!product) {
    return res.status(404).json({ error: 'Product not found' });
  }
  
  res.json(product);
});

app.listen(port, () => {
  console.log(\`Server running on port \${port}\`);
});
`);

// Update package.json
const packageJson = {
  name: 'computesdk-api',
  version: '1.0.0',
  main: 'index.js',
  scripts: {
    start: 'node index.js'
  },
  dependencies: {
    express: '^4.18.0',
    cors: '^2.8.5'
  }
};

await sandbox.filesystem.writeFile('/package.json', JSON.stringify(packageJson, null, 2));

// Install dependencies
await sandbox.runCommand('npm', ['install']);

console.log('Node.js API server created successfully!');
```

### Package Management

[Section titled “Package Management”](#package-management)

```
// Install popular packages
await sandbox.runCommand('npm', ['install', 'lodash', 'axios', 'date-fns']);

// Install dev dependencies
await sandbox.runCommand('npm', ['install', '--save-dev', 'jest', 'eslint']);

// Test the installed packages
const result = await sandbox.runCode(`
const _ = require('lodash');
const axios = require('axios');

console.log('Lodash version:', _.VERSION);
console.log('Axios available:', typeof axios);

// Test lodash functionality
const numbers = [1, 2, 3, 4, 5];
const doubled = _.map(numbers, n => n * 2);
console.log('Original:', numbers);
console.log('Doubled:', doubled);
console.log('Sum:', _.sum(doubled));
`);

console.log(result.stdout);
```

# Daytona

Daytona provider for ComputeSDK - Execute code in Daytona development workspaces.

## Installation

[Section titled “Installation”](#installation)

```
npm install @computesdk/daytona
```

## Usage

[Section titled “Usage”](#usage)

### With ComputeSDK

[Section titled “With ComputeSDK”](#with-computesdk)

```
import { createCompute } from 'computesdk';
import { daytona } from '@computesdk/daytona';

// Set as default provider
const compute = createCompute({ 
  defaultProvider: daytona({ apiKey: process.env.DAYTONA_API_KEY }) 
});

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

// Get instance
const instance = sandbox.getInstance();

// Execute code
const result = await sandbox.runCode('print("Hello from Daytona!")');
console.log(result.stdout); // "Hello from Daytona!"

// Clean up
await compute.sandbox.destroy(sandbox.sandboxId);
```

### Direct Usage

[Section titled “Direct Usage”](#direct-usage)

```
import { daytona } from '@computesdk/daytona';

// Create provider
const provider = daytona({ 
  apiKey: 'your-api-key',
  runtime: 'python' 
});

// Use with compute singleton
const sandbox = await compute.sandbox.create({ provider });
```

## Configuration

[Section titled “Configuration”](#configuration)

### Environment Variables

[Section titled “Environment Variables”](#environment-variables)

```
export DAYTONA_API_KEY=your_api_key_here
```

### Configuration Options

[Section titled “Configuration Options”](#configuration-options)

```
interface DaytonaConfig {
  /** Daytona API key - if not provided, will use DAYTONA_API_KEY env var */
  apiKey?: string;
  /** Default runtime environment */
  runtime?: 'python' | 'node';
  /** Execution timeout in milliseconds */
  timeout?: number;
  /** Base URL for Daytona API */
  baseUrl?: string;
}
```

## API Reference

[Section titled “API Reference”](#api-reference)

### Code Execution

[Section titled “Code Execution”](#code-execution)

```
// Execute Python code
const result = await sandbox.runCode(`
import json
data = {"message": "Hello from Python"}
print(json.dumps(data))
`, 'python');

// Execute Node.js code  
const result = await sandbox.runCode(`
const data = { message: "Hello from Node.js" };
console.log(JSON.stringify(data));
`, 'node');

// Auto-detection (based on code patterns)
const result = await sandbox.runCode('print("Auto-detected as Python")');
```

### Command Execution

[Section titled “Command Execution”](#command-execution)

```
// List files
const result = await sandbox.runCommand('ls', ['-la']);

// Install packages
const result = await sandbox.runCommand('pip', ['install', 'requests']);

// Run scripts
const result = await sandbox.runCommand('python', ['script.py']);
```

### Filesystem Operations

[Section titled “Filesystem Operations”](#filesystem-operations)

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

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

// Create directory
await sandbox.filesystem.mkdir('/workspace/data');

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

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

// Remove file or directory
await sandbox.filesystem.remove('/workspace/hello.py');
```

### Sandbox Management

[Section titled “Sandbox Management”](#sandbox-management)

```
// Get sandbox info
const info = await sandbox.getInfo();
console.log(info.id, info.provider, info.status);

// List all sandboxes
const sandboxes = await compute.sandbox.list();

// Get existing sandbox
const existing = await compute.sandbox.getById('sandbox-id');

// Destroy sandbox
await compute.sandbox.destroy('sandbox-id');
```

## Runtime Detection

[Section titled “Runtime Detection”](#runtime-detection)

The provider automatically detects the runtime based on code patterns:

**Python indicators:**

* `print(` statements
* `import` statements
* `def` function definitions
* Python-specific syntax (`f"`, `__`, etc.)

**Default:** Node.js for all other cases

## Error Handling

[Section titled “Error Handling”](#error-handling)

```
try {
  const result = await sandbox.runCode('invalid code');
} catch (error) {
  if (error.message.includes('Syntax error')) {
    console.error('Code has syntax errors');
  } else if (error.message.includes('authentication failed')) {
    console.error('Check your DAYTONA_API_KEY');
  } else if (error.message.includes('quota exceeded')) {
    console.error('Daytona usage limits reached');
  }
}
```

## Web Framework Integration

[Section titled “Web Framework Integration”](#web-framework-integration)

Use with web frameworks via the request handler:

```
import { handleComputeRequest } from 'computesdk';
import { daytona } from '@computesdk/daytona';

export async function POST(request: Request) {
  return handleComputeRequest({
    request,
    provider: daytona({ apiKey: process.env.DAYTONA_API_KEY })
  });
}
```

## Examples

[Section titled “Examples”](#examples)

### Data Processing

[Section titled “Data Processing”](#data-processing)

```
const result = await sandbox.runCode(`
import json

# Process data
data = [1, 2, 3, 4, 5]
result = {
    "sum": sum(data),
    "average": sum(data) / len(data),
    "max": max(data)
}

print(json.dumps(result))
`);

const output = JSON.parse(result.stdout);
console.log(output); // { sum: 15, average: 3, max: 5 }
```

### File Processing

[Section titled “File Processing”](#file-processing)

```
// Create data file
await sandbox.filesystem.writeFile('/workspace/data.json', 
  JSON.stringify({ users: ['Alice', 'Bob', 'Charlie'] })
);

// Process file
const result = await sandbox.runCode(`
import json

with open('/workspace/data.json', 'r') as f:
    data = json.load(f)

# Process users
user_count = len(data['users'])
print(f"Found {user_count} users")

# Save result
result = {"user_count": user_count, "processed": True}
with open('/workspace/result.json', 'w') as f:
    json.dump(result, f)
`);

// Read result
const resultData = await sandbox.filesystem.readFile('/workspace/result.json');
console.log(JSON.parse(resultData));
```

### Development Workspace

[Section titled “Development Workspace”](#development-workspace)

```
// Setup project structure
await sandbox.filesystem.mkdir('/workspace/project');
await sandbox.filesystem.mkdir('/workspace/project/src');
await sandbox.filesystem.mkdir('/workspace/project/data');

// Create configuration
const config = {
  name: "Data Analysis Project",
  version: "1.0.0",
  dependencies: ["pandas", "numpy"]
};

await sandbox.filesystem.writeFile(
  '/workspace/project/config.json',
  JSON.stringify(config, null, 2)
);

// Install dependencies
await sandbox.runCommand('pip', ['install'] + config.dependencies);

// Create and run analysis script
const analysisCode = `
import json
import pandas as pd

# Load config
with open('/workspace/project/config.json', 'r') as f:
    config = json.load(f)

print(f"Project: {config['name']}")

# Generate sample data
data = pd.DataFrame({
    'id': range(1, 101),
    'value': [i * 2 for i in range(1, 101)]
})

# Save data
data.to_csv('/workspace/project/data/sample.csv', index=False)
print(f"Generated {len(data)} records")
`;

await sandbox.filesystem.writeFile('/workspace/project/src/analyze.py', analysisCode);

const result = await sandbox.runCode('python /workspace/project/src/analyze.py');
console.log(result.stdout);
```

# E2B

E2B provider for ComputeSDK - Execute code in full development environments with terminal support.

## Installation

[Section titled “Installation”](#installation)

```
npm install @computesdk/e2b
```

## Usage

[Section titled “Usage”](#usage)

### With ComputeSDK

[Section titled “With ComputeSDK”](#with-computesdk)

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

// Set as default provider
const compute = createCompute({ 
  defaultProvider: e2b({ apiKey: process.env.E2B_API_KEY }) 
});

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

// Get instance
const instance = sandbox.getInstance();

// Execute code
const result = await sandbox.runCode('print("Hello from E2B!")');
console.log(result.stdout); // "Hello from E2B!"

// Clean up
await compute.sandbox.destroy(sandbox.sandboxId);
```

### Direct Usage

[Section titled “Direct Usage”](#direct-usage)

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

// Create provider
const provider = e2b({ 
  apiKey: 'your-api-key',
  template: 'base'
});

// Use with compute singleton
const sandbox = await compute.sandbox.create({ provider });
```

## Configuration

[Section titled “Configuration”](#configuration)

### Environment Variables

[Section titled “Environment Variables”](#environment-variables)

```
export E2B_API_KEY=e2b_your_api_key_here
```

### Configuration Options

[Section titled “Configuration Options”](#configuration-options)

```
interface E2BConfig {
  /** E2B API key - if not provided, will use E2B_API_KEY env var */
  apiKey?: string;
  /** Environment template to use */
  template?: string;
  /** Execution timeout in milliseconds */
  timeout?: number;
  /** Custom API URL */
  apiUrl?: string;
}
```

## API Reference

[Section titled “API Reference”](#api-reference)

### Code Execution

[Section titled “Code Execution”](#code-execution)

```
// Execute Python code
const result = await sandbox.runCode(`
import pandas as pd
import numpy as np
data = pd.DataFrame({'x': [1, 2, 3], 'y': [4, 5, 6]})
print(data.to_json())
`, 'python');

// Execute Node.js code  
const result = await sandbox.runCode(`
const data = { message: "Hello from Node.js" };
console.log(JSON.stringify(data));
`, 'node');

// Auto-detection (based on code patterns)
const result = await sandbox.runCode('print("Auto-detected as Python")');
```

### Command Execution

[Section titled “Command Execution”](#command-execution)

```
// List files
const result = await sandbox.runCommand('ls', ['-la']);

// Install packages
const result = await sandbox.runCommand('pip', ['install', 'matplotlib']);

// Run Python scripts
const result = await sandbox.runCommand('python', ['script.py']);
```

### Filesystem Operations

[Section titled “Filesystem Operations”](#filesystem-operations)

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

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

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

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

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

// Remove file or directory
await sandbox.filesystem.remove('/tmp/data.py');
```

### Sandbox Management

[Section titled “Sandbox Management”](#sandbox-management)

```
// Get sandbox info
const info = await sandbox.getInfo();
console.log(info.id, info.provider, info.status);

// List all sandboxes
const sandboxes = await compute.sandbox.list();

// Get existing sandbox
const existing = await compute.sandbox.getById('sandbox-id');

// Destroy sandbox
await compute.sandbox.destroy('sandbox-id');
```

## Runtime Detection

[Section titled “Runtime Detection”](#runtime-detection)

The provider automatically detects the runtime based on code patterns:

**Python indicators:**

* `print(` statements
* `import` statements
* `def` function definitions
* Python-specific syntax (`f"`, `__`, etc.)

**Default:** Node.js for all other cases

## Error Handling

[Section titled “Error Handling”](#error-handling)

```
try {
  const result = await sandbox.runCode('invalid code');
} catch (error) {
  if (error.message.includes('Syntax error')) {
    console.error('Code has syntax errors');
  } else if (error.message.includes('authentication failed')) {
    console.error('Check your E2B_API_KEY');
  } else if (error.message.includes('quota exceeded')) {
    console.error('E2B usage limits reached');
  }
}
```

## Web Framework Integration

[Section titled “Web Framework Integration”](#web-framework-integration)

Use with web frameworks via the request handler:

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

export async function POST(request: Request) {
  return handleComputeRequest({
    request,
    provider: e2b({ apiKey: process.env.E2B_API_KEY })
  });
}
```

## Examples

[Section titled “Examples”](#examples)

### Data Science Analysis

[Section titled “Data Science Analysis”](#data-science-analysis)

```
const result = await sandbox.runCode(`
import pandas as pd
import numpy as np

# Create sample data
data = pd.DataFrame({
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [25, 30, 35],
    'salary': [50000, 75000, 60000]
})

# Basic analysis
print("Dataset Overview:")
print(data)
print(f"\\nAverage salary: ${data['salary'].mean():,.2f}")
print(f"Age range: {data['age'].min()} - {data['age'].max()}")

# Export results
result = {
    "total_records": len(data),
    "avg_salary": float(data['salary'].mean()),
    "age_stats": {
        "min": int(data['age'].min()),
        "max": int(data['age'].max())
    }
}

import json
print("\\nResults:", json.dumps(result))
`);

const output = JSON.parse(result.stdout.split('Results: ')[1]);
console.log(output);
```

### File Processing with Terminal

[Section titled “File Processing with Terminal”](#file-processing-with-terminal)

```
// Create data file
await sandbox.filesystem.writeFile('/tmp/data.csv', 
  'name,value\nAlice,100\nBob,200\nCharlie,150'
);

// Create terminal for interactive work
const terminal = await sandbox.terminal.create({
  command: 'bash',
  cols: 80,
  rows: 24
});

// Use terminal to process file
await terminal.write('cd /tmp\n');
await terminal.write('python3 -c "import pandas as pd; df=pd.read_csv(\\'data.csv\\'); print(df.describe())"\n');
await terminal.write('wc -l data.csv\n');

// Process with Python code
const result = await sandbox.runCode(`
import pandas as pd
df = pd.read_csv('/tmp/data.csv')

# Calculate statistics
stats = {
    "count": len(df),
    "total_value": df['value'].sum(),
    "average": df['value'].mean()
}

# Save processed data
df['processed'] = df['value'] * 1.1
df.to_csv('/tmp/processed_data.csv', index=False)

print(f"Processed {stats['count']} records")
print(f"Total value: {stats['total_value']}")
`);

// Clean up terminal
await terminal.kill();
```

### Machine Learning Workflow

[Section titled “Machine Learning Workflow”](#machine-learning-workflow)

```
const result = await sandbox.runCode(`
import pandas as pd
import numpy as np
from sklearn.model_selection import train_test_split
from sklearn.linear_model import LinearRegression
from sklearn.metrics import mean_squared_error, r2_score

# Generate sample data
np.random.seed(42)
X = np.random.randn(100, 1)
y = 2 * X.flatten() + 1 + np.random.randn(100) * 0.1

# Split data
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

# Train model
model = LinearRegression()
model.fit(X_train, y_train)

# Make predictions
y_pred = model.predict(X_test)

# Evaluate
mse = mean_squared_error(y_test, y_pred)
r2 = r2_score(y_test, y_pred)

print(f"Model Performance:")
print(f"R² Score: {r2:.4f}")
print(f"MSE: {mse:.4f}")
print(f"Coefficient: {model.coef_[0]:.4f}")
print(f"Intercept: {model.intercept_:.4f}")

# Save model results
import json
results = {
    "r2_score": float(r2),
    "mse": float(mse),
    "coefficient": float(model.coef_[0]),
    "intercept": float(model.intercept_)
}
print("\\nModel Results:", json.dumps(results))
`);

console.log(result.stdout);
```

# Modal

Modal provider for ComputeSDK - Execute code with GPU support for machine learning workloads.

## Installation

[Section titled “Installation”](#installation)

```
npm install @computesdk/modal
```

## Usage

[Section titled “Usage”](#usage)

### With ComputeSDK

[Section titled “With ComputeSDK”](#with-computesdk)

```
import { createCompute } from 'computesdk';
import { modal } from '@computesdk/modal';

// Set as default provider
const compute = createCompute({ 
  defaultProvider: modal({ 
    tokenId: process.env.MODAL_TOKEN_ID,
    tokenSecret: process.env.MODAL_TOKEN_SECRET
  }) 
});

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

// Get instance
const instance = sandbox.getInstance();

// Execute code
const result = await sandbox.runCode('print("Hello from Modal!")');
console.log(result.stdout); // "Hello from Modal!"

// Clean up
await compute.sandbox.destroy(sandbox.sandboxId);
```

### Direct Usage

[Section titled “Direct Usage”](#direct-usage)

```
import { modal } from '@computesdk/modal';

// Create provider
const provider = modal({ 
  tokenId: 'your-token-id',
  tokenSecret: 'your-token-secret',
  gpu: 'T4'  // GPU type for ML workloads
});

// Use with compute singleton
const sandbox = await compute.sandbox.create({ provider });
```

## Configuration

[Section titled “Configuration”](#configuration)

### Environment Variables

[Section titled “Environment Variables”](#environment-variables)

```
export MODAL_TOKEN_ID=your_modal_token_id_here
export MODAL_TOKEN_SECRET=your_modal_token_secret_here
```

### Configuration Options

[Section titled “Configuration Options”](#configuration-options)

```
interface ModalConfig {
  /** Modal token ID - if not provided, will use MODAL_TOKEN_ID env var */
  tokenId?: string;
  /** Modal token secret - if not provided, will use MODAL_TOKEN_SECRET env var */
  tokenSecret?: string;
  /** GPU type for ML workloads */
  gpu?: 'T4' | 'A10G' | 'A100';
  /** CPU count */
  cpu?: number;
  /** Memory allocation in GB */
  memory?: number;
  /** Execution timeout in milliseconds */
  timeout?: number;
  /** Custom image for the environment */
  image?: string;
}
```

## API Reference

[Section titled “API Reference”](#api-reference)

### Code Execution

[Section titled “Code Execution”](#code-execution)

```
// Execute Python code with GPU support
const result = await sandbox.runCode(`
import torch
import numpy as np

print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")

if torch.cuda.is_available():
    print(f"GPU device: {torch.cuda.get_device_name()}")
    print(f"GPU memory: {torch.cuda.get_device_properties(0).total_memory / 1e9:.1f} GB")

# Simple tensor operations on GPU
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
x = torch.randn(1000, 1000, device=device)
y = torch.randn(1000, 1000, device=device)
z = torch.matmul(x, y)

print(f"Computed matrix multiplication on {device}")
print(f"Result shape: {z.shape}")
`, 'python');

// Machine learning workflow
const result = await sandbox.runCode(`
import torch
import torch.nn as nn
import numpy as np

# Simple neural network
class SimpleNet(nn.Module):
    def __init__(self):
        super(SimpleNet, self).__init__()
        self.fc1 = nn.Linear(10, 50)
        self.fc2 = nn.Linear(50, 1)
        self.relu = nn.ReLU()
    
    def forward(self, x):
        x = self.relu(self.fc1(x))
        return self.fc2(x)

# Create model and move to GPU if available
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
model = SimpleNet().to(device)

print(f"Model created on {device}")
print(f"Total parameters: {sum(p.numel() for p in model.parameters())}")
`);
```

### Command Execution

[Section titled “Command Execution”](#command-execution)

```
// Install additional packages
const result = await sandbox.runCommand('pip', ['install', 'transformers', 'datasets']);

// Check GPU status
const result = await sandbox.runCommand('nvidia-smi');

// Run Python scripts
const result = await sandbox.runCommand('python', ['train_model.py']);
```

### Filesystem Operations

[Section titled “Filesystem Operations”](#filesystem-operations)

```
// Write training script
await sandbox.filesystem.writeFile('/workspace/train.py', `
import torch
import torch.nn as nn
import torch.optim as optim

# Your ML training code here
print("Training script created")
`);

// Read model file
const modelCode = await sandbox.filesystem.readFile('/workspace/model.py');

// Create directories for ML project
await sandbox.filesystem.mkdir('/workspace/data');
await sandbox.filesystem.mkdir('/workspace/models');
await sandbox.filesystem.mkdir('/workspace/logs');

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

// Check if model exists
const exists = await sandbox.filesystem.exists('/workspace/model.pth');

// Remove temporary files
await sandbox.filesystem.remove('/workspace/temp_data.pkl');
```

### Sandbox Management

[Section titled “Sandbox Management”](#sandbox-management)

```
// Get sandbox info (including GPU allocation)
const info = await sandbox.getInfo();
console.log(info.id, info.provider, info.gpu, info.memory);

// List all sandboxes
const sandboxes = await compute.sandbox.list();

// Get existing sandbox
const existing = await compute.sandbox.getById('sandbox-id');

// Destroy sandbox
await compute.sandbox.destroy('sandbox-id');
```

## Error Handling

[Section titled “Error Handling”](#error-handling)

```
try {
  const result = await sandbox.runCode('invalid code');
} catch (error) {
  if (error.message.includes('CUDA out of memory')) {
    console.error('GPU memory insufficient - reduce batch size');
  } else if (error.message.includes('authentication failed')) {
    console.error('Check your MODAL_TOKEN_ID and MODAL_TOKEN_SECRET');
  } else if (error.message.includes('quota exceeded')) {
    console.error('Modal usage limits reached');
  }
}
```

## Web Framework Integration

[Section titled “Web Framework Integration”](#web-framework-integration)

Use with web frameworks via the request handler:

```
import { handleComputeRequest } from 'computesdk';
import { modal } from '@computesdk/modal';

export async function POST(request: Request) {
  return handleComputeRequest({
    request,
    provider: modal({ 
      tokenId: process.env.MODAL_TOKEN_ID,
      tokenSecret: process.env.MODAL_TOKEN_SECRET,
      gpu: 'T4'
    })
  });
}
```

## Examples

[Section titled “Examples”](#examples)

### Machine Learning Training

[Section titled “Machine Learning Training”](#machine-learning-training)

```
const result = await sandbox.runCode(`
import torch
import torch.nn as nn
import torch.optim as optim
import numpy as np
from torch.utils.data import DataLoader, TensorDataset

print("🤖 Machine Learning Training on GPU")
print("=" * 50)

# Check GPU availability
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
print(f"Using device: {device}")

if torch.cuda.is_available():
    print(f"GPU: {torch.cuda.get_device_name()}")
    print(f"Memory: {torch.cuda.get_device_properties(0).total_memory / 1e9:.1f} GB")

# Generate synthetic dataset
np.random.seed(42)
torch.manual_seed(42)

# Binary classification problem
n_samples = 10000
n_features = 20

X = torch.randn(n_samples, n_features)
# Create non-linear relationship
y = (X[:, 0] * X[:, 1] + X[:, 2]**2 > 0).float().unsqueeze(1)

# Split data
train_size = int(0.8 * n_samples)
X_train, X_test = X[:train_size], X[train_size:]
y_train, y_test = y[:train_size], y[train_size:]

print(f"Training samples: {len(X_train)}")
print(f"Test samples: {len(X_test)}")

# Create data loaders
train_dataset = TensorDataset(X_train, y_train)
test_dataset = TensorDataset(X_test, y_test)
train_loader = DataLoader(train_dataset, batch_size=32, shuffle=True)
test_loader = DataLoader(test_dataset, batch_size=32)

# Define model
class MLPClassifier(nn.Module):
    def __init__(self, input_size, hidden_size=64):
        super(MLPClassifier, self).__init__()
        self.network = nn.Sequential(
            nn.Linear(input_size, hidden_size),
            nn.ReLU(),
            nn.Dropout(0.3),
            nn.Linear(hidden_size, hidden_size),
            nn.ReLU(),
            nn.Dropout(0.3),
            nn.Linear(hidden_size, 1),
            nn.Sigmoid()
        )
    
    def forward(self, x):
        return self.network(x)

# Initialize model
model = MLPClassifier(n_features).to(device)
criterion = nn.BCELoss()
optimizer = optim.Adam(model.parameters(), lr=0.001)

print(f"Model parameters: {sum(p.numel() for p in model.parameters()):,}")

# Training loop
num_epochs = 10
for epoch in range(num_epochs):
    model.train()
    train_loss = 0
    correct = 0
    total = 0
    
    for batch_X, batch_y in train_loader:
        batch_X, batch_y = batch_X.to(device), batch_y.to(device)
        
        optimizer.zero_grad()
        outputs = model(batch_X)
        loss = criterion(outputs, batch_y)
        loss.backward()
        optimizer.step()
        
        train_loss += loss.item()
        predicted = (outputs > 0.5).float()
        total += batch_y.size(0)
        correct += (predicted == batch_y).sum().item()
    
    train_acc = 100 * correct / total
    
    # Evaluation
    model.eval()
    test_correct = 0
    test_total = 0
    
    with torch.no_grad():
        for batch_X, batch_y in test_loader:
            batch_X, batch_y = batch_X.to(device), batch_y.to(device)
            outputs = model(batch_X)
            predicted = (outputs > 0.5).float()
            test_total += batch_y.size(0)
            test_correct += (predicted == batch_y).sum().item()
    
    test_acc = 100 * test_correct / test_total
    
    print(f"Epoch {epoch+1}/{num_epochs}: Train Acc: {train_acc:.2f}%, Test Acc: {test_acc:.2f}%")

print("\\n✅ Training completed!")
print(f"Final test accuracy: {test_acc:.2f}%")

# Save model
torch.save(model.state_dict(), '/workspace/model.pth')
print("Model saved to /workspace/model.pth")
`);

console.log(result.stdout);
```

### Computer Vision with GPU

[Section titled “Computer Vision with GPU”](#computer-vision-with-gpu)

```
const result = await sandbox.runCode(`
import torch
import torchvision
import torchvision.transforms as transforms
import torch.nn as nn
import numpy as np
from PIL import Image

print("🖼️ Computer Vision with GPU")
print("=" * 40)

# Check GPU
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
print(f"Device: {device}")

# Create synthetic image data (since we don't have real dataset)
def create_synthetic_images(num_images=1000, size=(3, 32, 32)):
    """Create synthetic RGB images"""
    images = torch.randn(num_images, *size)
    # Create labels (10 classes like CIFAR-10)
    labels = torch.randint(0, 10, (num_images,))
    return images, labels

# Generate data
print("Generating synthetic image dataset...")
train_images, train_labels = create_synthetic_images(8000)
test_images, test_labels = create_synthetic_images(2000)

print(f"Train images: {train_images.shape}")
print(f"Test images: {test_images.shape}")

# Simple CNN model
class SimpleCNN(nn.Module):
    def __init__(self, num_classes=10):
        super(SimpleCNN, self).__init__()
        self.features = nn.Sequential(
            nn.Conv2d(3, 32, 3, padding=1),
            nn.ReLU(),
            nn.MaxPool2d(2),
            nn.Conv2d(32, 64, 3, padding=1),
            nn.ReLU(),
            nn.MaxPool2d(2),
            nn.Conv2d(64, 128, 3, padding=1),
            nn.ReLU(),
            nn.AdaptiveAvgPool2d((4, 4))
        )
        
        self.classifier = nn.Sequential(
            nn.Flatten(),
            nn.Linear(128 * 4 * 4, 256),
            nn.ReLU(),
            nn.Dropout(0.5),
            nn.Linear(256, num_classes)
        )
    
    def forward(self, x):
        x = self.features(x)
        x = self.classifier(x)
        return x

# Initialize model
model = SimpleCNN().to(device)
criterion = nn.CrossEntropyLoss()
optimizer = torch.optim.Adam(model.parameters(), lr=0.001)

print(f"\\nModel created with {sum(p.numel() for p in model.parameters()):,} parameters")

# Training
num_epochs = 5
batch_size = 64

for epoch in range(num_epochs):
    model.train()
    running_loss = 0.0
    correct = 0
    total = 0
    
    # Mini-batch training
    for i in range(0, len(train_images), batch_size):
        batch_images = train_images[i:i+batch_size].to(device)
        batch_labels = train_labels[i:i+batch_size].to(device)
        
        optimizer.zero_grad()
        outputs = model(batch_images)
        loss = criterion(outputs, batch_labels)
        loss.backward()
        optimizer.step()
        
        running_loss += loss.item()
        _, predicted = torch.max(outputs.data, 1)
        total += batch_labels.size(0)
        correct += (predicted == batch_labels).sum().item()
    
    train_acc = 100 * correct / total
    
    # Test evaluation
    model.eval()
    test_correct = 0
    test_total = 0
    
    with torch.no_grad():
        for i in range(0, len(test_images), batch_size):
            batch_images = test_images[i:i+batch_size].to(device)
            batch_labels = test_labels[i:i+batch_size].to(device)
            
            outputs = model(batch_images)
            _, predicted = torch.max(outputs, 1)
            test_total += batch_labels.size(0)
            test_correct += (predicted == batch_labels).sum().item()
    
    test_acc = 100 * test_correct / test_total
    
    print(f"Epoch {epoch+1}: Train Acc: {train_acc:.2f}%, Test Acc: {test_acc:.2f}%")

print("\\n✅ Computer vision training completed!")

# GPU memory info
if torch.cuda.is_available():
    print(f"\\n📊 GPU Memory Usage:")
    print(f"Allocated: {torch.cuda.memory_allocated() / 1e9:.2f} GB")
    print(f"Cached: {torch.cuda.memory_reserved() / 1e9:.2f} GB")
`);

console.log(result.stdout);
```

### Natural Language Processing

[Section titled “Natural Language Processing”](#natural-language-processing)

```
const result = await sandbox.runCode(`
import torch
import torch.nn as nn
import numpy as np
from collections import Counter
import re

print("🔤 Natural Language Processing with GPU")
print("=" * 50)

device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
print(f"Device: {device}")

# Sample text data
texts = [
    "Natural language processing is fascinating",
    "Machine learning models can understand text",
    "Deep learning transforms how we process language",
    "Neural networks excel at text classification",
    "GPU acceleration makes training faster",
    "Transformers revolutionized NLP applications",
    "Text analysis requires careful preprocessing",
    "Language models learn from vast datasets"
]

labels = [1, 1, 1, 1, 0, 1, 0, 1]  # Binary sentiment: 1=positive, 0=neutral

print(f"Dataset: {len(texts)} texts")

# Simple tokenization and vocabulary
def tokenize(text):
    return re.findall(r'\\b\\w+\\b', text.lower())

# Build vocabulary
all_tokens = []
for text in texts:
    all_tokens.extend(tokenize(text))

vocab = {word: i for i, word in enumerate(set(all_tokens))}
vocab_size = len(vocab)
print(f"Vocabulary size: {vocab_size}")

# Convert texts to sequences
def text_to_sequence(text, vocab, max_len=20):
    tokens = tokenize(text)
    sequence = [vocab.get(token, 0) for token in tokens]
    # Pad or truncate
    if len(sequence) < max_len:
        sequence.extend([0] * (max_len - len(sequence)))
    else:
        sequence = sequence[:max_len]
    return sequence

sequences = [text_to_sequence(text, vocab) for text in texts]
X = torch.tensor(sequences, dtype=torch.long)
y = torch.tensor(labels, dtype=torch.float32)

print(f"Input shape: {X.shape}")

# Simple LSTM model for text classification
class TextLSTM(nn.Module):
    def __init__(self, vocab_size, embed_dim=64, hidden_dim=32):
        super(TextLSTM, self).__init__()
        self.embedding = nn.Embedding(vocab_size, embed_dim)
        self.lstm = nn.LSTM(embed_dim, hidden_dim, batch_first=True)
        self.classifier = nn.Linear(hidden_dim, 1)
        self.sigmoid = nn.Sigmoid()
    
    def forward(self, x):
        embedded = self.embedding(x)  # (batch, seq_len, embed_dim)
        lstm_out, (hidden, _) = self.lstm(embedded)
        # Use last hidden state
        output = self.classifier(hidden[-1])  # (batch, 1)
        return self.sigmoid(output)

# Initialize model
model = TextLSTM(vocab_size + 1).to(device)  # +1 for padding token
criterion = nn.BCELoss()
optimizer = torch.optim.Adam(model.parameters(), lr=0.01)

print(f"Model parameters: {sum(p.numel() for p in model.parameters())}")

# Training (on small dataset, so many epochs)
X, y = X.to(device), y.to(device).unsqueeze(1)

num_epochs = 100
for epoch in range(num_epochs):
    model.train()
    optimizer.zero_grad()
    
    outputs = model(X)
    loss = criterion(outputs, y)
    loss.backward()
    optimizer.step()
    
    if (epoch + 1) % 20 == 0:
        model.eval()
        with torch.no_grad():
            predictions = model(X)
            predicted = (predictions > 0.5).float()
            accuracy = (predicted == y).float().mean()
            print(f"Epoch {epoch+1}: Loss: {loss.item():.4f}, Accuracy: {accuracy.item():.2f}")

print("\\n✅ NLP training completed!")

# Test on new text
test_text = "GPU acceleration improves deep learning performance"
test_sequence = text_to_sequence(test_text, vocab)
test_tensor = torch.tensor([test_sequence], dtype=torch.long).to(device)

model.eval()
with torch.no_grad():
    prediction = model(test_tensor)
    sentiment = "Positive" if prediction.item() > 0.5 else "Neutral"
    
print(f"\\nTest prediction:")
print(f"Text: '{test_text}'")
print(f"Sentiment: {sentiment} (confidence: {prediction.item():.3f})")
`);

console.log(result.stdout);
```

# More

#### Open Source

[Section titled “Open Source”](#open-source)

We welcome contributions to the Compute SDK! If you have a provider you’d like to add, please open a pull request.

### Providers

[Section titled “Providers”](#providers)

* [Daytona](/providers/daytona)
* [E2B](/providers/e2b)
* [Vercel](/providers/vercel)
* [Modal](/providers/modal)
* [CodeSandbox](/providers/codesandbox)
* [Blaxel](/providers/blaxel)
* [More](/providers/more)

# Runloop

Runloop provider for ComputeSDK - Execute code in cloud-based devboxes with full development environments.

## Installation

[Section titled “Installation”](#installation)

```
npm install @computesdk/runloop
```

## Usage

[Section titled “Usage”](#usage)

### With ComputeSDK

[Section titled “With ComputeSDK”](#with-computesdk)

```
import { createCompute } from 'computesdk';
import { runloop } from '@computesdk/runloop';

// Set as default provider
const compute = createCompute({ 
  defaultProvider: runloop({ apiKey: process.env.RUNLOOP_API_KEY }) 
});

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

// Get instance
const instance = sandbox.getInstance();

// Execute commands
const result = await sandbox.runCommand('python', ['-c', 'print("Hello from Runloop!")']);
console.log(result.stdout); // "Hello from Runloop!"

// Clean up
await compute.sandbox.destroy(sandbox.sandboxId);
```

### Direct Usage

[Section titled “Direct Usage”](#direct-usage)

```
import { runloop } from '@computesdk/runloop';

// Create provider
const provider = runloop({ 
  apiKey: 'your-api-key',
  timeout: 300000
});

// Use with compute singleton
const sandbox = await compute.sandbox.create({ provider });
```

## Configuration

[Section titled “Configuration”](#configuration)

### Environment Variables

[Section titled “Environment Variables”](#environment-variables)

```
export RUNLOOP_API_KEY=your_runloop_api_key_here
```

### Configuration Options

[Section titled “Configuration Options”](#configuration-options)

```
interface RunloopConfig {
  /** Runloop API key - if not provided, will use RUNLOOP_API_KEY env var */
  apiKey?: string;
  /** Execution timeout in milliseconds */
  timeout?: number;
}
```

## API Reference

[Section titled “API Reference”](#api-reference)

### Command Execution

[Section titled “Command Execution”](#command-execution)

```
// Execute Python commands
const result = await sandbox.runCommand('python', ['-c', `
import sys
import json

data = {
    "python_version": sys.version,
    "message": "Hello from Python",
    "timestamp": "2023-12-01"
}

print(json.dumps(data, indent=2))
`]);

// Execute Node.js commands  
const result = await sandbox.runCommand('node', ['-e', `
const data = {
  nodeVersion: process.version,
  platform: process.platform,
  message: "Hello from Node.js"
};

console.log(JSON.stringify(data, null, 2));
`]);

// Install packages
const result = await sandbox.runCommand('npm', ['install', 'lodash', 'axios']);

// Run shell commands
const result = await sandbox.runCommand('ls', ['-la']);
```

### Filesystem Operations

[Section titled “Filesystem Operations”](#filesystem-operations)

```
// Write file
await sandbox.filesystem.writeFile('/app/main.py', `
def greet(name):
    return f"Hello, {name}!"

def calculate_fibonacci(n):
    if n <= 1:
        return n
    return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)

# Main execution
if __name__ == "__main__":
    print(greet("Runloop"))
    print(f"Fibonacci(10): {calculate_fibonacci(10)}")
`);

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

// Create directory
await sandbox.filesystem.mkdir('/app/src');

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

// Check if file exists
const exists = await sandbox.filesystem.exists('/app/main.py');

// Remove file or directory
await sandbox.filesystem.remove('/app/main.py');
```

### Sandbox Management

[Section titled “Sandbox Management”](#sandbox-management)

```
// Get sandbox info
const info = await sandbox.getInfo();
console.log(info.id, info.provider, info.status);

// Get tunnel URL for port
const url = await sandbox.getUrl({ port: 8080 });
console.log('Access your app at:', url);

// List all sandboxes
const sandboxes = await compute.sandbox.list();

// Get existing sandbox
const existing = await compute.sandbox.getById('devbox-id');

// Destroy sandbox
await compute.sandbox.destroy('devbox-id');
```

## Blueprint Management

[Section titled “Blueprint Management”](#blueprint-management)

Runloop supports creating custom blueprints (templates) for devboxes:

```
// Create custom blueprint
const blueprint = await compute.template.create({
  name: 'python-ml-environment',
  dockerfile: `
FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \\
    build-essential \\
    curl \\
    git \\
    && rm -rf /var/lib/apt/lists/*

# Install Python packages
RUN pip install numpy pandas scikit-learn matplotlib jupyter

WORKDIR /app
  `,
  systemSetupCommands: [
    'pip install --upgrade pip',
    'pip install tensorflow torch'
  ],
  launchCommands: [
    'echo "ML environment ready!"'
  ],
  fileMounts: {
    '/app/requirements.txt': 'numpy\\npandas\\nscikit-learn\\nmatplotlib\\njupyter',
    '/app/README.md': '# Machine Learning Environment\\nThis devbox comes pre-configured with ML tools.'
  },
  resourceSize: 'LARGE',
  availablePorts: [8888, 8080]
});

// Use blueprint to create devbox
const mlSandbox = await compute.sandbox.create({
  options: { templateId: blueprint.id }
});

// List available blueprints
const blueprints = await compute.template.list();

// Delete blueprint
await compute.template.delete(blueprint.id);
```

## Snapshot Management

[Section titled “Snapshot Management”](#snapshot-management)

Create and restore devbox snapshots:

```
// Create snapshot of current devbox state
const snapshot = await compute.snapshot.create(sandbox.sandboxId, {
  name: 'after-setup',
  metadata: { 
    description: 'Devbox after initial setup and package installation',
    packages: ['numpy', 'pandas', 'flask']
  }
});

// Create new devbox from snapshot
const restoredSandbox = await compute.sandbox.create({
  options: { templateId: snapshot.id }
});

// List all snapshots
const snapshots = await compute.snapshot.list();

// Delete snapshot
await compute.snapshot.delete(snapshot.id);
```

## Error Handling

[Section titled “Error Handling”](#error-handling)

```
try {
  const result = await sandbox.runCommand('invalid-command');
} catch (error) {
  if (error.message.includes('command not found')) {
    console.error('Command does not exist in devbox');
  } else if (error.message.includes('authentication failed')) {
    console.error('Check your RUNLOOP_API_KEY');
  } else if (error.message.includes('execution failed')) {
    console.error('Command execution failed');
  }
}
```

## Web Framework Integration

[Section titled “Web Framework Integration”](#web-framework-integration)

Use with web frameworks via the request handler:

```
import { handleComputeRequest } from 'computesdk';
import { runloop } from '@computesdk/runloop';

export async function POST(request: Request) {
  return handleComputeRequest({
    request,
    provider: runloop({ apiKey: process.env.RUNLOOP_API_KEY })
  });
}
```

## Examples

[Section titled “Examples”](#examples)

### Python Data Science

[Section titled “Python Data Science”](#python-data-science)

```
// Create devbox with Python environment
const sandbox = await compute.sandbox.create();

// Install data science packages
await sandbox.runCommand('pip', ['install', 'pandas', 'numpy', 'matplotlib', 'seaborn']);

// Create data analysis script
await sandbox.filesystem.writeFile('/app/analysis.py', `
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import seaborn as sns

# Create sample dataset
np.random.seed(42)
data = {
    'sales': np.random.normal(1000, 200, 100),
    'marketing_spend': np.random.normal(500, 100, 100),
    'region': np.random.choice(['North', 'South', 'East', 'West'], 100)
}

df = pd.DataFrame(data)

# Basic analysis
print("Dataset Overview:")
print(df.describe())
print("\\nCorrelation between sales and marketing spend:")
print(f"Correlation: {df['sales'].corr(df['marketing_spend']):.3f}")

# Regional analysis
print("\\nSales by Region:")
regional_stats = df.groupby('region')['sales'].agg(['mean', 'std', 'count'])
print(regional_stats)

# Save processed data
df.to_csv('/app/sales_data.csv', index=False)
print("\\nData saved to sales_data.csv")
`);

// Run analysis
const result = await sandbox.runCommand('python', ['/app/analysis.py']);
console.log('Analysis Output:', result.stdout);

// Read the generated CSV
const csvData = await sandbox.filesystem.readFile('/app/sales_data.csv');
console.log('Generated CSV:', csvData.slice(0, 200) + '...');
```

### Node.js Web Server

[Section titled “Node.js Web Server”](#nodejs-web-server)

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

// Create Express server
await sandbox.filesystem.writeFile('/app/server.js', `
const express = require('express');
const cors = require('cors');

const app = express();
const port = process.env.PORT || 8080;

// Middleware
app.use(cors());
app.use(express.json());

// Sample data
const tasks = [
  { id: 1, title: 'Setup Runloop devbox', completed: true, priority: 'high' },
  { id: 2, title: 'Build API endpoints', completed: false, priority: 'medium' },
  { id: 3, title: 'Add authentication', completed: false, priority: 'low' }
];

// Routes
app.get('/', (req, res) => {
  res.json({ 
    message: 'Runloop Task API',
    endpoints: {
      'GET /tasks': 'List all tasks',
      'POST /tasks': 'Create new task',
      'PUT /tasks/:id': 'Update task',
      'DELETE /tasks/:id': 'Delete task'
    }
  });
});

app.get('/tasks', (req, res) => {
  const { priority, completed } = req.query;
  let filteredTasks = tasks;
  
  if (priority) {
    filteredTasks = filteredTasks.filter(t => t.priority === priority);
  }
  
  if (completed !== undefined) {
    const isCompleted = completed === 'true';
    filteredTasks = filteredTasks.filter(t => t.completed === isCompleted);
  }
  
  res.json({ tasks: filteredTasks, total: filteredTasks.length });
});

app.post('/tasks', (req, res) => {
  const { title, priority = 'medium' } = req.body;
  
  if (!title) {
    return res.status(400).json({ error: 'Title is required' });
  }
  
  const newTask = {
    id: Math.max(...tasks.map(t => t.id)) + 1,
    title,
    completed: false,
    priority
  };
  
  tasks.push(newTask);
  res.status(201).json(newTask);
});

app.put('/tasks/:id', (req, res) => {
  const taskId = parseInt(req.params.id);
  const task = tasks.find(t => t.id === taskId);
  
  if (!task) {
    return res.status(404).json({ error: 'Task not found' });
  }
  
  Object.assign(task, req.body);
  res.json(task);
});

app.delete('/tasks/:id', (req, res) => {
  const taskId = parseInt(req.params.id);
  const index = tasks.findIndex(t => t.id === taskId);
  
  if (index === -1) {
    return res.status(404).json({ error: 'Task not found' });
  }
  
  tasks.splice(index, 1);
  res.status(204).send();
});

app.listen(port, () => {
  console.log(\`Task API server running on port \${port}\`);
});
`);

// Create package.json
const packageJson = {
  name: 'runloop-task-api',
  version: '1.0.0',
  main: 'server.js',
  scripts: {
    start: 'node server.js',
    dev: 'node server.js'
  },
  dependencies: {
    express: '^4.18.0',
    cors: '^2.8.5'
  }
};

await sandbox.filesystem.writeFile('/app/package.json', JSON.stringify(packageJson, null, 2));

// Install dependencies
console.log('Installing dependencies...');
await sandbox.runCommand('npm', ['install'], { cwd: '/app' });

// Start server (non-blocking)
console.log('Starting server...');
await sandbox.runCommand('node', ['server.js'], { cwd: '/app', timeout: 5000 });

// Get the public URL
const serverUrl = await sandbox.getUrl({ port: 8080 });
console.log('🚀 Task API available at:', serverUrl);

// Test the API
const testResult = await sandbox.runCommand('curl', ['-s', 'http://localhost:8080/tasks']);
console.log('API Response:', testResult.stdout);
```

### Machine Learning Model Training

[Section titled “Machine Learning Model Training”](#machine-learning-model-training)

```
// Create devbox for ML workload
const sandbox = await compute.sandbox.create();

// Install ML packages
await sandbox.runCommand('pip', [
  'install', 
  'scikit-learn', 
  'pandas', 
  'numpy', 
  'matplotlib', 
  'joblib'
]);

// Create training script
await sandbox.filesystem.writeFile('/app/train_model.py', `
import pandas as pd
import numpy as np
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import classification_report, accuracy_score
import joblib
import json

# Generate synthetic dataset
np.random.seed(42)
n_samples = 1000

# Features: age, income, credit_score, debt_ratio
data = {
    'age': np.random.randint(18, 80, n_samples),
    'income': np.random.lognormal(10.5, 0.5, n_samples),
    'credit_score': np.random.randint(300, 850, n_samples),
    'debt_ratio': np.random.beta(2, 5, n_samples)
}

# Create target (loan approval) based on realistic criteria
df = pd.DataFrame(data)
df['loan_approved'] = (
    (df['credit_score'] > 600) & 
    (df['income'] > 40000) & 
    (df['debt_ratio'] < 0.4) &
    (df['age'] > 21)
).astype(int)

print("Dataset created:")
print(f"Samples: {len(df)}")
print(f"Approval rate: {df['loan_approved'].mean():.2%}")
print("\\nFeature distributions:")
print(df.describe())

# Prepare features
X = df[['age', 'income', 'credit_score', 'debt_ratio']]
y = df['loan_approved']

# Split data
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42, stratify=y
)

# Train model
print("\\nTraining Random Forest model...")
model = RandomForestClassifier(
    n_estimators=100,
    max_depth=10,
    random_state=42,
    class_weight='balanced'
)

model.fit(X_train, y_train)

# Evaluate model
y_pred = model.predict(X_test)
accuracy = accuracy_score(y_test, y_pred)

print(f"\\nModel Performance:")
print(f"Accuracy: {accuracy:.3f}")
print("\\nClassification Report:")
print(classification_report(y_test, y_pred))

# Feature importance
feature_importance = pd.DataFrame({
    'feature': X.columns,
    'importance': model.feature_importances_
}).sort_values('importance', ascending=False)

print("\\nFeature Importance:")
print(feature_importance)

# Save model and metadata
joblib.dump(model, '/app/loan_model.pkl')

model_metadata = {
    'accuracy': float(accuracy),
    'features': list(X.columns),
    'feature_importance': feature_importance.to_dict('records'),
    'training_samples': len(X_train),
    'test_samples': len(X_test)
}

with open('/app/model_metadata.json', 'w') as f:
    json.dump(model_metadata, f, indent=2)

print("\\nModel saved to loan_model.pkl")
print("Metadata saved to model_metadata.json")

# Test prediction
sample_applicant = {
    'age': 35,
    'income': 75000,
    'credit_score': 720,
    'debt_ratio': 0.25
}

sample_features = np.array([[
    sample_applicant['age'],
    sample_applicant['income'],
    sample_applicant['credit_score'],
    sample_applicant['debt_ratio']
]])

prediction = model.predict(sample_features)[0]
probability = model.predict_proba(sample_features)[0][1]

print(f"\\nSample Prediction:")
print(f"Applicant: {sample_applicant}")
print(f"Prediction: {'Approved' if prediction else 'Denied'}")
print(f"Approval Probability: {probability:.3f}")
`);

// Run training
console.log('Training machine learning model...');
const trainingResult = await sandbox.runCommand('python', ['/app/train_model.py']);
console.log('Training Output:', trainingResult.stdout);

// Read model metadata
const metadata = await sandbox.filesystem.readFile('/app/model_metadata.json');
console.log('Model Metadata:', JSON.parse(metadata));

// Create inference script
await sandbox.filesystem.writeFile('/app/predict.py', `
import joblib
import json
import sys

# Load model
model = joblib.load('/app/loan_model.pkl')

# Get input from command line
if len(sys.argv) != 5:
    print("Usage: python predict.py <age> <income> <credit_score> <debt_ratio>")
    sys.exit(1)

age = float(sys.argv[1])
income = float(sys.argv[2])
credit_score = float(sys.argv[3])
debt_ratio = float(sys.argv[4])

# Make prediction
features = [[age, income, credit_score, debt_ratio]]
prediction = model.predict(features)[0]
probability = model.predict_proba(features)[0][1]

result = {
    'applicant': {
        'age': age,
        'income': income,
        'credit_score': credit_score,
        'debt_ratio': debt_ratio
    },
    'prediction': 'approved' if prediction else 'denied',
    'approval_probability': float(probability)
}

print(json.dumps(result, indent=2))
`);

// Test inference
const predictionResult = await sandbox.runCommand('python', [
  '/app/predict.py', '28', '65000', '750', '0.15'
]);
console.log('Prediction Result:', predictionResult.stdout);
```

### Development Environment Setup

[Section titled “Development Environment Setup”](#development-environment-setup)

```
// Create blueprint for full-stack development
const devBlueprint = await compute.template.create({
  name: 'fullstack-dev-environment',
  dockerfile: `
FROM ubuntu:22.04

# Install system dependencies
RUN apt-get update && apt-get install -y \\
    curl \\
    git \\
    build-essential \\
    python3 \\
    python3-pip \\
    postgresql-client \\
    redis-tools \\
    && rm -rf /var/lib/apt/lists/*

# Install Node.js
RUN curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \\
    && apt-get install -y nodejs

# Install global tools
RUN npm install -g pm2 nodemon typescript ts-node
RUN pip3 install poetry black flake8 pytest

WORKDIR /workspace
  `,
  systemSetupCommands: [
    'git config --global init.defaultBranch main',
    'echo "export PATH=$PATH:/usr/local/bin" >> ~/.bashrc'
  ],
  launchCommands: [
    'echo "Full-stack development environment ready!"',
    'echo "Available tools: Node.js, Python, PostgreSQL client, Redis client"'
  ],
  fileMounts: {
    '/workspace/.gitconfig': `[user]
    email = dev@example.com
    name = Developer
[core]
    editor = nano`,
    '/workspace/README.md': `# Full-Stack Development Environment

This devbox includes:
- Node.js 18 with npm and global tools
- Python 3 with pip and poetry
- Git with basic configuration
- PostgreSQL and Redis clients
- Development tools (TypeScript, linting, testing)

## Quick Start

### Node.js Project
\`\`\`bash
npm init -y
npm install express
\`\`\`

### Python Project
\`\`\`bash
poetry init
poetry add fastapi uvicorn
\`\`\`
`
  },
  resourceSize: 'MEDIUM',
  availablePorts: [3000, 8000, 5432, 6379]
});

// Create devbox from blueprint
const devSandbox = await compute.sandbox.create({
  options: { templateId: devBlueprint.id }
});

console.log('Development environment created!');
console.log('Blueprint ID:', devBlueprint.id);
console.log('Devbox ID:', devSandbox.sandboxId);

// Verify tools are available
const toolsCheck = await devSandbox.runCommand('bash', ['-c', `
echo "=== Development Tools Check ==="
echo "Node.js: $(node --version)"
echo "npm: $(npm --version)"
echo "Python: $(python3 --version)"
echo "pip: $(pip3 --version)"
echo "Git: $(git --version)"
echo "TypeScript: $(tsc --version)"
echo "Poetry: $(poetry --version)"
echo "============================="
`]);

console.log('Tools Check:', toolsCheck.stdout);
```

## Resource Management

[Section titled “Resource Management”](#resource-management)

```
// Create devbox with specific resource requirements
const heavyWorkloadSandbox = await compute.sandbox.create({
  provider: runloop({
    apiKey: process.env.RUNLOOP_API_KEY
  }),
  options: {
    templateId: 'bpt_custom_ml',  // Use blueprint with GPU support
    timeout: 3600000,  // 1 hour timeout
    metadata: {
      purpose: 'machine-learning',
      project: 'image-classification',
      team: 'data-science'
    }
  }
});

// Monitor resource usage
const usage = await heavyWorkloadSandbox.runCommand('bash', ['-c', `
echo "=== Resource Usage ==="
echo "CPU Usage:"
top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d'%' -f1
echo "Memory Usage:"
free -h | grep Mem | awk '{print "Used: " $3 "/" $2 " (" $3/$2*100 "%)"}'
echo "Disk Usage:"
df -h / | tail -1 | awk '{print "Used: " $3 "/" $2 " (" $5 ")"}'
echo "===================="
`]);

console.log('Resource Usage:', usage.stdout);
```

This documentation provides comprehensive coverage of the Runloop provider’s capabilities, following the same structure and style as the CodeSandbox documentation while highlighting Runloop’s unique features like blueprint management, snapshots, and development environment capabilities.

# Vercel

Vercel provider for ComputeSDK - Execute code in globally distributed serverless environments.

## Installation

[Section titled “Installation”](#installation)

```
npm install @computesdk/vercel
```

## Usage

[Section titled “Usage”](#usage)

### With ComputeSDK

[Section titled “With ComputeSDK”](#with-computesdk)

```
import { createCompute } from 'computesdk';
import { vercel } from '@computesdk/vercel';

// Set as default provider
const compute = createCompute({ 
  defaultProvider: vercel({ runtime: 'node' }) 
});

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

// Get instance
const instance = sandbox.getInstance();

// Execute code
const result = await sandbox.runCode('console.log("Hello from Vercel!")');
console.log(result.stdout); // "Hello from Vercel!"

// Clean up
await compute.sandbox.destroy(sandbox.sandboxId);
```

### Direct Usage

[Section titled “Direct Usage”](#direct-usage)

```
import { vercel } from '@computesdk/vercel';

// Create provider
const provider = vercel({ 
  runtime: 'python',
  timeout: 1800000  // 30 minutes
});

// Use with compute singleton
const sandbox = await compute.sandbox.create({ provider });
```

## Configuration

[Section titled “Configuration”](#configuration)

### Environment Variables

[Section titled “Environment Variables”](#environment-variables)

```
# Option 1: OIDC Token (Recommended)
export VERCEL_OIDC_TOKEN=your_oidc_token_here

# Option 2: Traditional Token
export VERCEL_TOKEN=your_vercel_token_here
export VERCEL_TEAM_ID=your_team_id_here
export VERCEL_PROJECT_ID=your_project_id_here
```

### Configuration Options

[Section titled “Configuration Options”](#configuration-options)

```
interface VercelConfig {
  /** Runtime environment */
  runtime: 'node' | 'python';
  /** Vercel token - if not provided, will use env vars */
  token?: string;
  /** Team ID for team accounts */
  teamId?: string;
  /** Project ID */
  projectId?: string;
  /** Use OIDC authentication */
  useOIDC?: boolean;
  /** Deployment region */
  region?: string;
  /** Memory allocation in MB */
  memory?: number;
  /** Execution timeout in milliseconds */
  timeout?: number;
}
```

## API Reference

[Section titled “API Reference”](#api-reference)

### Code Execution

[Section titled “Code Execution”](#code-execution)

```
// Execute Node.js code
const result = await sandbox.runCode(`
const data = { message: "Hello from Node.js", timestamp: Date.now() };
console.log(JSON.stringify(data));
`, 'node');

// Execute Python code  
const result = await sandbox.runCode(`
import json
from datetime import datetime
data = {"message": "Hello from Python", "timestamp": datetime.now().isoformat()}
print(json.dumps(data))
`, 'python');

// Auto-detection (based on code patterns)
const result = await sandbox.runCode('print("Auto-detected as Python")');
```

### Command Execution

[Section titled “Command Execution”](#command-execution)

```
// List files
const result = await sandbox.runCommand('ls', ['-la']);

// Install Node.js packages
const result = await sandbox.runCommand('npm', ['install', 'lodash']);

// Install Python packages
const result = await sandbox.runCommand('pip', ['install', 'requests']);

// Run scripts
const result = await sandbox.runCommand('node', ['script.js']);
```

### Filesystem Operations

[Section titled “Filesystem Operations”](#filesystem-operations)

```
// Write file
await sandbox.filesystem.writeFile('/tmp/data.json', '{"hello": "world"}');

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

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

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

// Check if file exists
const exists = await sandbox.filesystem.exists('/tmp/data.json');

// Remove file or directory
await sandbox.filesystem.remove('/tmp/data.json');
```

### Sandbox Management

[Section titled “Sandbox Management”](#sandbox-management)

```
// Get sandbox info
const info = await sandbox.getInfo();
console.log(info.id, info.provider, info.status);

// List all sandboxes
const sandboxes = await compute.sandbox.list();

// Get existing sandbox
const existing = await compute.sandbox.getById('sandbox-id');

// Destroy sandbox
await compute.sandbox.destroy('sandbox-id');
```

## Runtime Detection

[Section titled “Runtime Detection”](#runtime-detection)

The provider automatically detects the runtime based on code patterns:

**Python indicators:**

* `print(` statements
* `import` statements
* `def` function definitions
* Python-specific syntax (`f"`, `__`, etc.)

**Default:** Node.js for all other cases

## Error Handling

[Section titled “Error Handling”](#error-handling)

```
try {
  const result = await sandbox.runCode('invalid code');
} catch (error) {
  if (error.message.includes('Syntax error')) {
    console.error('Code has syntax errors');
  } else if (error.message.includes('authentication failed')) {
    console.error('Check your Vercel credentials');
  } else if (error.message.includes('quota exceeded')) {
    console.error('Vercel usage limits reached');
  } else if (error.message.includes('timeout')) {
    console.error('Execution timed out (max 45 minutes)');
  }
}
```

## Web Framework Integration

[Section titled “Web Framework Integration”](#web-framework-integration)

Use with web frameworks via the request handler:

```
import { handleComputeRequest } from 'computesdk';
import { vercel } from '@computesdk/vercel';

export async function POST(request: Request) {
  return handleComputeRequest({
    request,
    provider: vercel({ runtime: 'node' })
  });
}
```

## Examples

[Section titled “Examples”](#examples)

### API Development

[Section titled “API Development”](#api-development)

```
const result = await sandbox.runCode(`
const http = require('http');
const url = require('url');

// Create a simple API handler
function handleRequest(req, res) {
  const parsedUrl = url.parse(req.url, true);
  
  if (parsedUrl.pathname === '/api/data') {
    const data = {
      message: "Hello from Vercel API",
      timestamp: new Date().toISOString(),
      query: parsedUrl.query
    };
    
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify(data));
  } else {
    res.writeHead(404, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ error: 'Not found' }));
  }
}

// Test the handler
const mockReq = { url: '/api/data?user=alice' };
const mockRes = {
  statusCode: null,
  headers: {},
  data: '',
  writeHead(code, headers) { this.statusCode = code; Object.assign(this.headers, headers); },
  end(data) { this.data = data; }
};

handleRequest(mockReq, mockRes);
console.log('Status:', mockRes.statusCode);
console.log('Response:', mockRes.data);
`, 'node');

console.log(result.stdout);
```

### Data Processing

[Section titled “Data Processing”](#data-processing)

```
const result = await sandbox.runCode(`
import json
import statistics
from datetime import datetime, timedelta

# Generate sample sales data
def generate_sales_data(days=7):
    import random
    random.seed(42)
    
    products = ['Laptop', 'Mouse', 'Keyboard', 'Monitor']
    sales = []
    
    for day in range(days):
        date = (datetime.now() - timedelta(days=days-day-1)).strftime('%Y-%m-%d')
        daily_sales = random.randint(5, 15)
        
        for _ in range(daily_sales):
            sale = {
                'date': date,
                'product': random.choice(products),
                'price': round(random.uniform(20, 500), 2),
                'quantity': random.randint(1, 3)
            }
            sale['total'] = round(sale['price'] * sale['quantity'], 2)
            sales.append(sale)
    
    return sales

# Process data
sales = generate_sales_data(7)
print(f"Generated {len(sales)} sales records")

# Calculate metrics
total_revenue = sum(sale['total'] for sale in sales)
avg_order_value = statistics.mean(sale['total'] for sale in sales)
product_sales = {}

for sale in sales:
    product = sale['product']
    if product not in product_sales:
        product_sales[product] = {'count': 0, 'revenue': 0}
    product_sales[product]['count'] += sale['quantity']
    product_sales[product]['revenue'] += sale['total']

# Results
results = {
    'total_sales': len(sales),
    'total_revenue': round(total_revenue, 2),
    'avg_order_value': round(avg_order_value, 2),
    'top_product': max(product_sales.keys(), key=lambda x: product_sales[x]['revenue']),
    'product_breakdown': product_sales
}

print("Sales Analysis Results:")
print(json.dumps(results, indent=2))
`);

console.log(result.stdout);
```

### Long-Running Task

[Section titled “Long-Running Task”](#long-running-task)

```
// Configure for extended execution (up to 45 minutes)
const sandbox = await compute.sandbox.create({
  options: {
    timeout: 2700000,  // 45 minutes
    memory: 1024       // 1GB memory
  }
});

const result = await sandbox.runCode(`
import time
import json
from datetime import datetime

def long_running_analysis():
    print("Starting long-running data analysis...")
    
    # Simulate processing batches of data
    total_batches = 50
    batch_size = 1000
    results = []
    
    for batch_num in range(total_batches):
        # Simulate data processing
        batch_start = time.time()
        
        # Process batch (simulate work)
        processed_items = []
        for i in range(batch_size):
            # Simple computation
            value = (batch_num * batch_size + i) ** 0.5
            processed_items.append(value)
        
        batch_time = time.time() - batch_start
        
        batch_result = {
            'batch': batch_num + 1,
            'items_processed': len(processed_items),
            'avg_value': sum(processed_items) / len(processed_items),
            'processing_time': round(batch_time, 4)
        }
        
        results.append(batch_result)
        
        # Progress update every 10 batches
        if (batch_num + 1) % 10 == 0:
            print(f"Completed {batch_num + 1}/{total_batches} batches")
        
        # Small delay to simulate real work
        time.sleep(0.1)
    
    # Final summary
    total_items = sum(r['items_processed'] for r in results)
    total_time = sum(r['processing_time'] for r in results)
    
    summary = {
        'total_batches': total_batches,
        'total_items': total_items,
        'total_processing_time': round(total_time, 2),
        'avg_batch_time': round(total_time / total_batches, 4),
        'completed_at': datetime.now().isoformat()
    }
    
    print("\\nAnalysis Complete!")
    print(f"Processed {total_items:,} items in {summary['total_processing_time']} seconds")
    
    return summary

# Run the analysis
result = long_running_analysis()
print("\\nFinal Summary:", json.dumps(result, indent=2))
`);

console.log(result.stdout);
```

### Multi-Region Deployment

[Section titled “Multi-Region Deployment”](#multi-region-deployment)

```
// Deploy to different regions
const regions = ['iad1', 'sfo1', 'fra1'];

// Simple performance test
const start = Date.now();
const data = Array.from({length: 10000}, (_, i) => Math.sin(i));
const sum = data.reduce((a, b) => a + b, 0);
const end = Date.now();

const results = {
  region: '${region}',
  processing_time: end - start,
  data_points: data.length,
  sum: sum.toFixed(4)
};

console.log('Results:', JSON.stringify(results));
    `);
    
    await compute.sandbox.destroy(sandbox.sandboxId);
    return result.stdout;
  })
);

results.forEach((output, index) => {
  console.log(`\nRegion ${regions[index]} output:`, output);
});
```

# API Integration

ComputeSDK provides seamless integration with web frameworks and APIs, enabling you to embed compute capabilities directly into your applications. Build powerful backend services, API endpoints, and serverless functions with compute sandboxes.

## Quick Start

[Section titled “Quick Start”](#quick-start)

```
import { compute } from 'computesdk'
import express from 'express'

const app = express()

app.post('/execute', async (req, res) => {
  const sandbox = await compute('e2b')
  
  try {
    const result = await sandbox.exec(req.body.command)
    res.json({ output: result.stdout, success: true })
  } catch (error) {
    res.status(500).json({ error: error.message, success: false })
  } finally {
    await sandbox.destroy()
  }
})
```

## Express.js Integration

[Section titled “Express.js Integration”](#expressjs-integration)

### Basic API Endpoints

[Section titled “Basic API Endpoints”](#basic-api-endpoints)

```
import express from 'express'
import { compute } from 'computesdk'

const app = express()
app.use(express.json())

// Code execution endpoint
app.post('/api/execute', async (req, res) => {
  const { code, language, provider = 'e2b' } = req.body
  
  try {
    const sandbox = await compute(provider, {
      template: language,
      timeout: 30000
    })
    
    const result = await sandbox[language](code)
    
    res.json({
      success: true,
      output: result.stdout,
      stderr: result.stderr,
      executionTime: result.executionTime
    })
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.message
    })
  }
})

// File operations endpoint
app.post('/api/files', async (req, res) => {
  const { action, path, content } = req.body
  const sandbox = await compute('e2b')
  
  try {
    switch (action) {
      case 'read':
        const fileContent = await sandbox.readFile(path)
        res.json({ content: fileContent })
        break
        
      case 'write':
        await sandbox.writeFile(path, content)
        res.json({ success: true })
        break
        
      case 'list':
        const files = await sandbox.listFiles(path)
        res.json({ files })
        break
        
      default:
        res.status(400).json({ error: 'Invalid action' })
    }
  } catch (error) {
    res.status(500).json({ error: error.message })
  }
})
```

### Middleware Integration

[Section titled “Middleware Integration”](#middleware-integration)

```
// Sandbox middleware
function sandboxMiddleware(provider: string = 'e2b') {
  return async (req: Request, res: Response, next: NextFunction) => {
    try {
      req.sandbox = await compute(provider, {
        keepAlive: true,
        timeout: 60000
      })
      
      // Cleanup on response finish
      res.on('finish', async () => {
        if (req.sandbox) {
          await req.sandbox.destroy()
        }
      })
      
      next()
    } catch (error) {
      res.status(500).json({ error: 'Failed to create sandbox' })
    }
  }
}

// Usage
app.use('/api/compute', sandboxMiddleware('e2b'))

app.post('/api/compute/python', async (req, res) => {
  const result = await req.sandbox.python(req.body.code)
  res.json(result)
})
```

### Error Handling Middleware

[Section titled “Error Handling Middleware”](#error-handling-middleware)

```
// Global error handler for compute operations
function computeErrorHandler(error: any, req: Request, res: Response, next: NextFunction) {
  console.error('Compute error:', error)
  
  if (error.name === 'TimeoutError') {
    res.status(408).json({
      error: 'Operation timed out',
      code: 'TIMEOUT'
    })
  } else if (error.name === 'ExecutionError') {
    res.status(400).json({
      error: 'Code execution failed',
      details: error.stderr,
      code: 'EXECUTION_ERROR'
    })
  } else if (error.name === 'ResourceError') {
    res.status(507).json({
      error: 'Insufficient resources',
      code: 'RESOURCE_ERROR'
    })
  } else {
    res.status(500).json({
      error: 'Internal server error',
      code: 'INTERNAL_ERROR'
    })
  }
}

app.use(computeErrorHandler)
```

## Next.js Integration

[Section titled “Next.js Integration”](#nextjs-integration)

### API Routes

[Section titled “API Routes”](#api-routes)

```
// pages/api/execute.ts
import type { NextApiRequest, NextApiResponse } from 'next'
import { compute } from 'computesdk'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' })
  }
  
  const { code, language } = req.body
  
  try {
    const sandbox = await compute('vercel', {
      template: language,
      region: 'iad1'
    })
    
    const result = await sandbox.exec(`${language} -c "${code}"`)
    
    res.status(200).json({
      output: result.stdout,
      error: result.stderr,
      success: result.exitCode === 0
    })
  } catch (error) {
    res.status(500).json({ error: error.message })
  }
}
```

### App Router (Next.js 13+)

[Section titled “App Router (Next.js 13+)”](#app-router-nextjs-13)

```
// app/api/execute/route.ts
import { compute } from 'computesdk'
import { NextRequest, NextResponse } from 'next/server'

export async function POST(request: NextRequest) {
  try {
    const { code, language } = await request.json()
    
    const sandbox = await compute('vercel', {
      template: language
    })
    
    const result = await sandbox[language](code)
    
    return NextResponse.json({
      output: result.stdout,
      executionTime: result.executionTime
    })
  } catch (error) {
    return NextResponse.json(
      { error: error.message },
      { status: 500 }
    )
  }
}
```

### Server Actions

[Section titled “Server Actions”](#server-actions)

```
// app/actions.ts
'use server'

import { compute } from 'computesdk'

export async function executeCode(formData: FormData) {
  const code = formData.get('code') as string
  const language = formData.get('language') as string
  
  try {
    const sandbox = await compute('vercel')
    const result = await sandbox[language](code)
    
    return {
      success: true,
      output: result.stdout,
      error: result.stderr
    }
  } catch (error) {
    return {
      success: false,
      error: error.message
    }
  }
}
```

## Fastify Integration

[Section titled “Fastify Integration”](#fastify-integration)

```
import Fastify from 'fastify'
import { compute } from 'computesdk'

const fastify = Fastify({ logger: true })

// Plugin for compute functionality
async function computePlugin(fastify: any) {
  fastify.decorate('compute', compute)
  
  fastify.addHook('onRequest', async (request: any) => {
    request.startTime = Date.now()
  })
  
  fastify.addHook('onResponse', async (request: any, reply: any) => {
    const duration = Date.now() - request.startTime
    fastify.log.info(`Request completed in ${duration}ms`)
  })
}

fastify.register(computePlugin)

// Execute code endpoint
fastify.post('/execute', {
  schema: {
    body: {
      type: 'object',
      required: ['code', 'language'],
      properties: {
        code: { type: 'string' },
        language: { type: 'string' },
        provider: { type: 'string' }
      }
    }
  }
}, async (request, reply) => {
  const { code, language, provider = 'e2b' } = request.body
  
  const sandbox = await fastify.compute(provider, {
    template: language
  })
  
  try {
    const result = await sandbox[language](code)
    return { success: true, output: result.stdout }
  } catch (error) {
    reply.status(500)
    return { success: false, error: error.message }
  }
})
```

## GraphQL Integration

[Section titled “GraphQL Integration”](#graphql-integration)

### Apollo Server

[Section titled “Apollo Server”](#apollo-server)

```
import { ApolloServer, gql } from 'apollo-server-express'
import { compute } from 'computesdk'

const typeDefs = gql`
  type ExecutionResult {
    output: String!
    stderr: String
    executionTime: Int!
    success: Boolean!
  }
  
  type FileContent {
    path: String!
    content: String!
    size: Int!
  }
  
  type Query {
    listFiles(path: String!): [String!]!
    readFile(path: String!): FileContent
  }
  
  type Mutation {
    executeCode(
      code: String!
      language: String!
      provider: String = "e2b"
    ): ExecutionResult!
    
    writeFile(
      path: String!
      content: String!
    ): Boolean!
  }
`

const resolvers = {
  Query: {
    listFiles: async (_, { path }) => {
      const sandbox = await compute('e2b')
      try {
        const files = await sandbox.listFiles(path)
        return files.map(f => f.name)
      } finally {
        await sandbox.destroy()
      }
    },
    
    readFile: async (_, { path }) => {
      const sandbox = await compute('e2b')
      try {
        const content = await sandbox.readFile(path)
        const stats = await sandbox.stat(path)
        return {
          path,
          content,
          size: stats.size
        }
      } finally {
        await sandbox.destroy()
      }
    }
  },
  
  Mutation: {
    executeCode: async (_, { code, language, provider }) => {
      const sandbox = await compute(provider, {
        template: language,
        timeout: 30000
      })
      
      try {
        const result = await sandbox[language](code)
        return {
          output: result.stdout,
          stderr: result.stderr,
          executionTime: result.executionTime,
          success: result.exitCode === 0
        }
      } catch (error) {
        return {
          output: '',
          stderr: error.message,
          executionTime: 0,
          success: false
        }
      } finally {
        await sandbox.destroy()
      }
    },
    
    writeFile: async (_, { path, content }) => {
      const sandbox = await compute('e2b')
      try {
        await sandbox.writeFile(path, content)
        return true
      } catch (error) {
        return false
      } finally {
        await sandbox.destroy()
      }
    }
  }
}

const server = new ApolloServer({ typeDefs, resolvers })
```

## WebSocket Integration

[Section titled “WebSocket Integration”](#websocket-integration)

### Real-time Code Execution

[Section titled “Real-time Code Execution”](#real-time-code-execution)

```
import { WebSocketServer } from 'ws'
import { compute } from 'computesdk'

const wss = new WebSocketServer({ port: 8080 })

interface Client {
  ws: WebSocket
  sandbox?: Sandbox
  id: string
}

const clients = new Map<string, Client>()

wss.on('connection', (ws) => {
  const clientId = generateId()
  const client: Client = { ws, id: clientId }
  clients.set(clientId, client)
  
  ws.on('message', async (data) => {
    try {
      const message = JSON.parse(data.toString())
      
      switch (message.type) {
        case 'create-sandbox':
          client.sandbox = await compute(message.provider || 'e2b', {
            template: message.template
          })
          
          ws.send(JSON.stringify({
            type: 'sandbox-ready',
            sandboxId: client.sandbox.id
          }))
          break
          
        case 'execute':
          if (!client.sandbox) {
            ws.send(JSON.stringify({
              type: 'error',
              message: 'No active sandbox'
            }))
            return
          }
          
          // Stream execution output
          const stream = client.sandbox.execStream(message.command)
          
          stream.stdout.on('data', (chunk) => {
            ws.send(JSON.stringify({
              type: 'output',
              stream: 'stdout',
              data: chunk.toString()
            }))
          })
          
          stream.stderr.on('data', (chunk) => {
            ws.send(JSON.stringify({
              type: 'output',
              stream: 'stderr',
              data: chunk.toString()
            }))
          })
          
          stream.on('exit', (code) => {
            ws.send(JSON.stringify({
              type: 'execution-complete',
              exitCode: code
            }))
          })
          break
          
        case 'destroy-sandbox':
          if (client.sandbox) {
            await client.sandbox.destroy()
            client.sandbox = undefined
          }
          break
      }
    } catch (error) {
      ws.send(JSON.stringify({
        type: 'error',
        message: error.message
      }))
    }
  })
  
  ws.on('close', async () => {
    if (client.sandbox) {
      await client.sandbox.destroy()
    }
    clients.delete(clientId)
  })
})
```

### Socket.IO Integration

[Section titled “Socket.IO Integration”](#socketio-integration)

```
import { Server } from 'socket.io'
import { compute } from 'computesdk'

const io = new Server(server, {
  cors: { origin: "*" }
})

interface SessionData {
  sandbox?: Sandbox
  userId: string
}

io.on('connection', (socket) => {
  const session: SessionData = {
    userId: socket.handshake.auth.userId
  }
  
  socket.on('start-session', async (config) => {
    try {
      session.sandbox = await compute(config.provider, {
        template: config.template,
        metadata: { userId: session.userId }
      })
      
      socket.emit('session-started', {
        sandboxId: session.sandbox.id
      })
    } catch (error) {
      socket.emit('error', { message: error.message })
    }
  })
  
  socket.on('execute-code', async (data) => {
    if (!session.sandbox) {
      socket.emit('error', { message: 'No active session' })
      return
    }
    
    try {
      const result = await session.sandbox[data.language](data.code)
      socket.emit('execution-result', {
        output: result.stdout,
        stderr: result.stderr,
        success: result.exitCode === 0
      })
    } catch (error) {
      socket.emit('execution-error', {
        message: error.message
      })
    }
  })
  
  socket.on('terminal-input', async (data) => {
    if (session.sandbox?.terminal) {
      await session.sandbox.terminal.write(data)
    }
  })
  
  socket.on('disconnect', async () => {
    if (session.sandbox) {
      await session.sandbox.destroy()
    }
  })
})
```

## Serverless Function Integration

[Section titled “Serverless Function Integration”](#serverless-function-integration)

### Vercel Functions

[Section titled “Vercel Functions”](#vercel-functions)

```
// api/compute.ts
import type { VercelRequest, VercelResponse } from '@vercel/node'
import { compute } from 'computesdk'

export default async function handler(
  req: VercelRequest,
  res: VercelResponse
) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' })
  }
  
  const { code, language } = req.body
  
  try {
    const sandbox = await compute('vercel', {
      template: language,
      region: process.env.VERCEL_REGION || 'iad1'
    })
    
    const result = await sandbox[language](code, {
      timeout: 10000 // 10 second limit for serverless
    })
    
    res.json({
      output: result.stdout,
      executionTime: result.executionTime
    })
  } catch (error) {
    res.status(500).json({ error: error.message })
  }
}
```

### AWS Lambda

[Section titled “AWS Lambda”](#aws-lambda)

```
import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda'
import { compute } from 'computesdk'

export const handler = async (
  event: APIGatewayProxyEvent
): Promise<APIGatewayProxyResult> => {
  try {
    const { code, language } = JSON.parse(event.body || '{}')
    
    const sandbox = await compute('modal', {
      template: language,
      resources: {
        memoryMB: 1024,
        timeoutMs: 30000
      }
    })
    
    const result = await sandbox[language](code)
    
    return {
      statusCode: 200,
      headers: {
        'Content-Type': 'application/json',
        'Access-Control-Allow-Origin': '*'
      },
      body: JSON.stringify({
        output: result.stdout,
        stderr: result.stderr,
        executionTime: result.executionTime
      })
    }
  } catch (error) {
    return {
      statusCode: 500,
      headers: {
        'Content-Type': 'application/json',
        'Access-Control-Allow-Origin': '*'
      },
      body: JSON.stringify({
        error: error.message
      })
    }
  }
}
```

### Cloudflare Workers

[Section titled “Cloudflare Workers”](#cloudflare-workers)

```
// worker.ts
import { compute } from 'computesdk'

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method !== 'POST') {
      return new Response('Method not allowed', { status: 405 })
    }
    
    try {
      const { code, language } = await request.json()
      
      const sandbox = await compute('cloudflare', {
        template: language,
        region: 'auto'
      })
      
      const result = await sandbox[language](code, {
        timeout: 10000
      })
      
      return new Response(JSON.stringify({
        output: result.stdout,
        success: result.exitCode === 0
      }), {
        headers: {
          'Content-Type': 'application/json',
          'Access-Control-Allow-Origin': '*'
        }
      })
    } catch (error) {
      return new Response(JSON.stringify({
        error: error.message
      }), {
        status: 500,
        headers: {
          'Content-Type': 'application/json'
        }
      })
    }
  }
}
```

## Authentication and Authorization

[Section titled “Authentication and Authorization”](#authentication-and-authorization)

### JWT-based Authentication

[Section titled “JWT-based Authentication”](#jwt-based-authentication)

```
import jwt from 'jsonwebtoken'
import { compute } from 'computesdk'

// JWT middleware
function authenticateToken(req: Request, res: Response, next: NextFunction) {
  const authHeader = req.headers['authorization']
  const token = authHeader && authHeader.split(' ')[1]
  
  if (!token) {
    return res.sendStatus(401)
  }
  
  jwt.verify(token, process.env.ACCESS_TOKEN_SECRET, (err, user) => {
    if (err) return res.sendStatus(403)
    req.user = user
    next()
  })
}

// Protected compute endpoint
app.post('/api/secure/execute', authenticateToken, async (req, res) => {
  const user = req.user
  
  const sandbox = await compute('e2b', {
    metadata: {
      userId: user.id,
      userPlan: user.plan
    },
    resources: getUserResourceLimits(user.plan)
  })
  
  try {
    const result = await sandbox.exec(req.body.command)
    
    // Log usage for billing
    await logUsage(user.id, {
      executionTime: result.executionTime,
      resourceUsage: await sandbox.getResourceUsage()
    })
    
    res.json(result)
  } catch (error) {
    res.status(500).json({ error: error.message })
  }
})
```

### Role-based Access Control

[Section titled “Role-based Access Control”](#role-based-access-control)

```
interface UserPermissions {
  canExecuteCode: boolean
  canAccessFiles: boolean
  canCreateSandbox: boolean
  allowedProviders: string[]
  resourceLimits: {
    maxCpuCores: number
    maxMemoryMB: number
    maxExecutionTime: number
  }
}

function checkPermissions(permission: keyof UserPermissions) {
  return (req: Request, res: Response, next: NextFunction) => {
    const user = req.user
    const permissions = getUserPermissions(user.role)
    
    if (!permissions[permission]) {
      return res.status(403).json({ error: 'Insufficient permissions' })
    }
    
    req.permissions = permissions
    next()
  }
}

// Usage
app.post('/api/execute',
  authenticateToken,
  checkPermissions('canExecuteCode'),
  async (req, res) => {
    const { provider } = req.body
    const permissions = req.permissions
    
    if (!permissions.allowedProviders.includes(provider)) {
      return res.status(403).json({ error: 'Provider not allowed' })
    }
    
    const sandbox = await compute(provider, {
      resources: permissions.resourceLimits,
      timeout: permissions.resourceLimits.maxExecutionTime
    })
    
    // ... execute code
  }
)
```

## Rate Limiting and Quotas

[Section titled “Rate Limiting and Quotas”](#rate-limiting-and-quotas)

### Rate Limiting Middleware

[Section titled “Rate Limiting Middleware”](#rate-limiting-middleware)

```
import rateLimit from 'express-rate-limit'
import { compute } from 'computesdk'

// Basic rate limiting
const createRateLimit = (windowMs: number, max: number) => 
  rateLimit({
    windowMs,
    max,
    message: 'Too many requests, please try again later',
    standardHeaders: true,
    legacyHeaders: false
  })

// Different limits for different endpoints
app.use('/api/execute', createRateLimit(15 * 60 * 1000, 100)) // 100 requests per 15 minutes
app.use('/api/files', createRateLimit(15 * 60 * 1000, 500))   // 500 requests per 15 minutes

// Advanced rate limiting with user tiers
const userBasedRateLimit = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: (req) => {
    const userTier = req.user?.tier || 'free'
    const limits = {
      free: 10,
      pro: 100,
      enterprise: 1000
    }
    return limits[userTier] || 10
  },
  keyGenerator: (req) => req.user?.id || req.ip
})
```

### Usage Tracking and Quotas

[Section titled “Usage Tracking and Quotas”](#usage-tracking-and-quotas)

```
class UsageTracker {
  private usage = new Map<string, UserUsage>()
  
  async trackExecution(userId: string, metrics: ExecutionMetrics) {
    const current = this.usage.get(userId) || { 
      executions: 0, 
      cpuSeconds: 0, 
      memoryMBSeconds: 0 
    }
    
    current.executions++
    current.cpuSeconds += metrics.cpuTime
    current.memoryMBSeconds += metrics.memoryMB * (metrics.duration / 1000)
    
    this.usage.set(userId, current)
    
    // Persist to database
    await this.saveUsage(userId, current)
  }
  
  async checkQuota(userId: string): Promise<boolean> {
    const usage = this.usage.get(userId)
    const limits = await this.getUserLimits(userId)
    
    return !usage || (
      usage.executions < limits.maxExecutions &&
      usage.cpuSeconds < limits.maxCpuSeconds &&
      usage.memoryMBSeconds < limits.maxMemoryMBSeconds
    )
  }
}

const usageTracker = new UsageTracker()

// Quota checking middleware
async function checkQuota(req: Request, res: Response, next: NextFunction) {
  const userId = req.user?.id
  
  if (!userId) {
    return res.status(401).json({ error: 'Unauthorized' })
  }
  
  const hasQuota = await usageTracker.checkQuota(userId)
  
  if (!hasQuota) {
    return res.status(429).json({ 
      error: 'Quota exceeded',
      code: 'QUOTA_EXCEEDED'
    })
  }
  
  next()
}
```

## Monitoring and Observability

[Section titled “Monitoring and Observability”](#monitoring-and-observability)

### Metrics Collection

[Section titled “Metrics Collection”](#metrics-collection)

```
import prometheus from 'prom-client'

// Create metrics
const executionCounter = new prometheus.Counter({
  name: 'compute_executions_total',
  help: 'Total number of code executions',
  labelNames: ['provider', 'language', 'status']
})

const executionDuration = new prometheus.Histogram({
  name: 'compute_execution_duration_seconds',
  help: 'Duration of code executions',
  labelNames: ['provider', 'language']
})

const activeConnections = new prometheus.Gauge({
  name: 'compute_active_connections',
  help: 'Number of active sandbox connections'
})

// Middleware to collect metrics
function metricsMiddleware(req: Request, res: Response, next: NextFunction) {
  const startTime = Date.now()
  
  res.on('finish', () => {
    const duration = (Date.now() - startTime) / 1000
    const status = res.statusCode >= 400 ? 'error' : 'success'
    
    executionCounter.inc({
      provider: req.body.provider || 'unknown',
      language: req.body.language || 'unknown',
      status
    })
    
    executionDuration.observe({
      provider: req.body.provider || 'unknown',
      language: req.body.language || 'unknown'
    }, duration)
  })
  
  next()
}

// Metrics endpoint
app.get('/metrics', async (req, res) => {
  res.set('Content-Type', prometheus.register.contentType)
  res.end(await prometheus.register.metrics())
})
```

### Health Checks

[Section titled “Health Checks”](#health-checks)

```
app.get('/health', async (req, res) => {
  const health = {
    status: 'healthy',
    timestamp: new Date().toISOString(),
    services: {}
  }
  
  // Check sandbox connectivity
  try {
    const testSandbox = await compute('e2b', { timeout: 5000 })
    await testSandbox.exec('echo "health check"')
    await testSandbox.destroy()
    health.services.e2b = 'healthy'
  } catch (error) {
    health.services.e2b = 'unhealthy'
    health.status = 'degraded'
  }
  
  // Check other providers...
  
  const statusCode = health.status === 'healthy' ? 200 : 503
  res.status(statusCode).json(health)
})
```

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Resource Management**: Always clean up sandboxes and close connections
2. **Error Handling**: Implement comprehensive error handling and user-friendly messages
3. **Security**: Validate all inputs and implement proper authentication/authorization
4. **Rate Limiting**: Protect your API with appropriate rate limits and quotas
5. **Monitoring**: Track usage, performance, and errors for operational insights
6. **Caching**: Cache sandbox instances where appropriate to improve performance
7. **Timeouts**: Set reasonable timeouts to prevent hanging requests
8. **Documentation**: Provide clear API documentation for consumers

## Related Documentation

[Section titled “Related Documentation”](#related-documentation)

* [Overview](./overview.md) - SDK architecture and concepts
* [Configuration](./configuration.md) - Configuration options for different environments
* [Code Execution](./code-execution.md) - Running code and commands
* [UI Package](./ui-package.md) - Frontend integration components
* [Frameworks](../frameworks/) - Framework-specific integration guides

# Code Execution

ComputeSDK provides powerful code execution capabilities across multiple languages and environments. Execute scripts, run commands, manage processes, and handle input/output streams with ease.

## Quick Start

[Section titled “Quick Start”](#quick-start)

```
import { compute } from 'computesdk'

const sandbox = await compute('e2b')

// Execute a simple command
const result = await sandbox.exec('python -c "print(\"Hello, World!\")"')
console.log(result.stdout) // "Hello, World!"

// Run a script file
const output = await sandbox.run('main.py')
```

## Basic Code Execution

[Section titled “Basic Code Execution”](#basic-code-execution)

### exec() Method

[Section titled “exec() Method”](#exec-method)

Execute shell commands directly:

```
// Simple command execution
const result = await sandbox.exec('ls -la')
console.log(result.stdout)

// Command with arguments
const result = await sandbox.exec('python', ['-c', 'print("Hello")'])

// With options
const result = await sandbox.exec('npm install', {
  cwd: '/app',
  timeout: 30000,
  env: { NODE_ENV: 'development' }
})
```

### run() Method

[Section titled “run() Method”](#run-method)

Execute script files:

```
// Run a Python script
const result = await sandbox.run('script.py')

// Run with arguments
const result = await sandbox.run('script.py', ['arg1', 'arg2'])

// Run with custom interpreter
const result = await sandbox.run('script.js', [], {
  interpreter: 'node',
  cwd: '/app/src'
})
```

## Execution Result Interface

[Section titled “Execution Result Interface”](#execution-result-interface)

```
interface ExecutionResult {
  // Standard output
  stdout: string
  
  // Standard error
  stderr: string
  
  // Exit code (0 = success)
  exitCode: number
  
  // Execution time in milliseconds
  executionTime: number
  
  // Process ID
  pid?: number
  
  // Resource usage
  usage?: {
    cpuTime: number
    memoryMB: number
    diskIO: number
  }
}
```

## Language-Specific Execution

[Section titled “Language-Specific Execution”](#language-specific-execution)

### Python

[Section titled “Python”](#python)

```
// Execute Python code directly
const result = await sandbox.python(`
import math
result = math.sqrt(16)
print(f"Square root of 16 is {result}")
`)

// With virtual environment
const result = await sandbox.python('import pandas as pd', {
  venv: '/opt/venv',
  requirements: ['pandas', 'numpy']
})

// Jupyter notebook style execution
const result = await sandbox.python(`
import matplotlib.pyplot as plt
plt.plot([1, 2, 3, 4])
plt.savefig('plot.png')
`, {
  returnFiles: ['plot.png']
})
```

### Node.js

[Section titled “Node.js”](#nodejs)

```
// Execute JavaScript/Node.js code
const result = await sandbox.node(`
const fs = require('fs')
const data = { message: 'Hello from Node.js' }
fs.writeFileSync('output.json', JSON.stringify(data))
console.log('File written successfully')
`)

// With npm packages
const result = await sandbox.node(`
const axios = require('axios')
const response = await axios.get('https://api.github.com/users/octocat')
console.log(response.data.name)
`, {
  packages: ['axios']
})

// TypeScript execution
const result = await sandbox.typescript(`
interface User {
  name: string
  age: number
}

const user: User = { name: 'John', age: 30 }
console.log(user)
`)
```

### Shell Scripts

[Section titled “Shell Scripts”](#shell-scripts)

```
// Bash script execution
const result = await sandbox.bash(`
#!/bin/bash
echo "Starting deployment..."
git pull origin main
npm install
npm run build
echo "Deployment complete"
`)

// With environment variables
const result = await sandbox.bash(`
export API_URL=$1
export API_KEY=$2
curl -H "Authorization: Bearer $API_KEY" $API_URL/health
`, ['https://api.example.com', 'secret-key'])
```

### Other Languages

[Section titled “Other Languages”](#other-languages)

```
// Go
const result = await sandbox.go(`
package main
import "fmt"
func main() {
    fmt.Println("Hello from Go!")
}
`)

// Rust
const result = await sandbox.rust(`
fn main() {
    println!("Hello from Rust!");
}
`)

// Java
const result = await sandbox.java(`
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello from Java!");
    }
}
`)
```

## Async and Streaming Execution

[Section titled “Async and Streaming Execution”](#async-and-streaming-execution)

### Stream Output

[Section titled “Stream Output”](#stream-output)

Stream output in real-time:

```
// Stream stdout/stderr
const stream = sandbox.execStream('python long_running_script.py')

stream.stdout.on('data', (chunk) => {
  console.log('STDOUT:', chunk.toString())
})

stream.stderr.on('data', (chunk) => {
  console.error('STDERR:', chunk.toString())
})

stream.on('exit', (code) => {
  console.log('Process exited with code:', code)
})

// Send input to the process
stream.stdin.write('user input\n')
```

### Interactive Execution

[Section titled “Interactive Execution”](#interactive-execution)

Handle interactive programs:

```
// Interactive Python session
const session = await sandbox.startInteractiveSession('python')

// Send commands and receive responses
await session.send('x = 10')
await session.send('y = 20')
const result = await session.send('print(x + y)')
console.log(result.output) // "30"

// End the session
await session.close()
```

### Background Processes

[Section titled “Background Processes”](#background-processes)

Run long-running processes in the background:

```
// Start a background process
const process = await sandbox.startBackground('python -m http.server 8000')

// Check if process is running
const isRunning = await process.isAlive()

// Get process info
const info = await process.getInfo()
console.log('PID:', info.pid)
console.log('CPU usage:', info.cpuPercent)

// Stop the process
await process.kill()
```

## Execution Options

[Section titled “Execution Options”](#execution-options)

### Timeout and Cancellation

[Section titled “Timeout and Cancellation”](#timeout-and-cancellation)

```
// Set timeout
const result = await sandbox.exec('sleep 10', {
  timeout: 5000 // 5 seconds
})

// Manual cancellation
const controller = new AbortController()
const execution = sandbox.exec('long_command', {
  signal: controller.signal
})

// Cancel after 3 seconds
setTimeout(() => controller.abort(), 3000)

try {
  const result = await execution
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Execution was cancelled')
  }
}
```

### Environment Variables

[Section titled “Environment Variables”](#environment-variables)

```
// Set environment variables for execution
const result = await sandbox.exec('printenv', {
  env: {
    NODE_ENV: 'production',
    API_KEY: 'secret',
    DEBUG: 'true'
  }
})

// Inherit from sandbox environment
const result = await sandbox.exec('node app.js', {
  env: {
    ...await sandbox.getEnv(),
    ADDITIONAL_VAR: 'value'
  }
})
```

### Working Directory

[Section titled “Working Directory”](#working-directory)

```
// Execute in specific directory
const result = await sandbox.exec('ls', {
  cwd: '/app/src'
})

// Change directory and execute
await sandbox.cd('/app')
const result = await sandbox.exec('npm start')
```

### Input/Output Handling

[Section titled “Input/Output Handling”](#inputoutput-handling)

```
// Provide input to command
const result = await sandbox.exec('python -c "print(input())"', {
  input: 'Hello from input!'
})

// Capture binary output
const result = await sandbox.exec('cat image.png', {
  encoding: 'binary'
})

// Limit output size
const result = await sandbox.exec('cat large_file.txt', {
  maxOutputSize: 1024 * 1024 // 1MB limit
})
```

## Process Management

[Section titled “Process Management”](#process-management)

### List Running Processes

[Section titled “List Running Processes”](#list-running-processes)

```
// Get all running processes
const processes = await sandbox.ps()

processes.forEach(proc => {
  console.log(`PID: ${proc.pid}, Command: ${proc.command}`)
})

// Filter processes
const pythonProcs = await sandbox.ps({ 
  filter: (proc) => proc.command.includes('python') 
})
```

### Kill Processes

[Section titled “Kill Processes”](#kill-processes)

```
// Kill specific process
await sandbox.kill(1234) // Kill by PID

// Kill by pattern
await sandbox.killall('python')

// Graceful shutdown with timeout
await sandbox.kill(1234, { signal: 'SIGTERM', timeout: 5000 })
```

### Process Monitoring

[Section titled “Process Monitoring”](#process-monitoring)

```
// Monitor process resource usage
const monitor = await sandbox.monitor(1234)

monitor.on('stats', (stats) => {
  console.log('CPU:', stats.cpuPercent)
  console.log('Memory:', stats.memoryMB)
})

// Stop monitoring
await monitor.stop()
```

## Error Handling

[Section titled “Error Handling”](#error-handling)

### Execution Errors

[Section titled “Execution Errors”](#execution-errors)

```
try {
  const result = await sandbox.exec('invalid_command')
} catch (error) {
  if (error instanceof ExecutionError) {
    console.log('Command failed with exit code:', error.exitCode)
    console.log('Error output:', error.stderr)
    console.log('Standard output:', error.stdout)
  }
}

// Handle timeout errors
try {
  const result = await sandbox.exec('sleep 60', { timeout: 5000 })
} catch (error) {
  if (error instanceof TimeoutError) {
    console.log('Command timed out after 5 seconds')
  }
}
```

### Graceful Error Recovery

[Section titled “Graceful Error Recovery”](#graceful-error-recovery)

```
// Retry failed executions
async function executeWithRetry(command: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await sandbox.exec(command)
    } catch (error) {
      if (i === maxRetries - 1) throw error
      console.log(`Attempt ${i + 1} failed, retrying...`)
      await new Promise(resolve => setTimeout(resolve, 1000))
    }
  }
}

// Fallback commands
async function executeWithFallback(commands: string[]) {
  for (const command of commands) {
    try {
      return await sandbox.exec(command)
    } catch (error) {
      console.log(`Command "${command}" failed, trying next...`)
    }
  }
  throw new Error('All commands failed')
}
```

## Performance Optimization

[Section titled “Performance Optimization”](#performance-optimization)

### Batch Execution

[Section titled “Batch Execution”](#batch-execution)

```
// Execute multiple commands in parallel
const results = await Promise.all([
  sandbox.exec('ls /app'),
  sandbox.exec('ps aux'),
  sandbox.exec('df -h')
])

// Sequential execution with shared context
const session = await sandbox.startSession()
await session.exec('cd /app')
await session.exec('export NODE_ENV=production')
const result = await session.exec('npm start')
await session.close()
```

### Caching

[Section titled “Caching”](#caching)

```
// Cache execution results
const cache = new Map()

async function cachedExec(command: string) {
  if (cache.has(command)) {
    return cache.get(command)
  }
  
  const result = await sandbox.exec(command)
  cache.set(command, result)
  return result
}
```

### Resource Management

[Section titled “Resource Management”](#resource-management)

```
// Limit concurrent executions
const semaphore = new Semaphore(3) // Max 3 concurrent executions

async function executeWithLimit(command: string) {
  await semaphore.acquire()
  try {
    return await sandbox.exec(command)
  } finally {
    semaphore.release()
  }
}
```

## Advanced Features

[Section titled “Advanced Features”](#advanced-features)

### Code Analysis

[Section titled “Code Analysis”](#code-analysis)

```
// Analyze code before execution
const analysis = await sandbox.analyzeCode(`
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

print(fibonacci(10))
`, {
  language: 'python',
  checks: ['syntax', 'security', 'performance']
})

if (analysis.safe) {
  const result = await sandbox.python(analysis.code)
}
```

### Debugging

[Section titled “Debugging”](#debugging)

```
// Execute with debugging enabled
const result = await sandbox.exec('python script.py', {
  debug: true,
  breakpoints: ['script.py:10', 'script.py:25']
})

// Step through execution
const debugger = await sandbox.startDebugger('python script.py')
await debugger.setBreakpoint('script.py', 10)
await debugger.continue()
const variables = await debugger.getVariables()
```

### Profiling

[Section titled “Profiling”](#profiling)

```
// Profile code execution
const profile = await sandbox.profile('python -c "sum(range(1000000))"')

console.log('Function calls:', profile.functionCalls)
console.log('Memory usage:', profile.memoryUsage)
console.log('CPU time:', profile.cpuTime)
```

## Integration Examples

[Section titled “Integration Examples”](#integration-examples)

### Web Framework Integration

[Section titled “Web Framework Integration”](#web-framework-integration)

```
// Express.js endpoint
app.post('/execute', async (req, res) => {
  try {
    const { code, language } = req.body
    
    const sandbox = await compute('e2b')
    const result = await sandbox[language](code, {
      timeout: 30000,
      maxOutputSize: 1024 * 1024
    })
    
    res.json({
      success: true,
      output: result.stdout,
      executionTime: result.executionTime
    })
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.message
    })
  }
})
```

### Real-time Code Execution

[Section titled “Real-time Code Execution”](#real-time-code-execution)

```
// WebSocket-based code execution
io.on('connection', (socket) => {
  let sandbox: Sandbox
  
  socket.on('start-session', async () => {
    sandbox = await compute('e2b')
    socket.emit('session-ready')
  })
  
  socket.on('execute', async (data) => {
    try {
      const stream = sandbox.execStream(data.code)
      
      stream.stdout.on('data', (chunk) => {
        socket.emit('output', { type: 'stdout', data: chunk.toString() })
      })
      
      stream.stderr.on('data', (chunk) => {
        socket.emit('output', { type: 'stderr', data: chunk.toString() })
      })
      
      stream.on('exit', (code) => {
        socket.emit('execution-complete', { exitCode: code })
      })
    } catch (error) {
      socket.emit('execution-error', { error: error.message })
    }
  })
})
```

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Always set timeouts** to prevent hanging executions
2. **Validate input** before executing user-provided code
3. **Use streaming** for long-running processes
4. **Handle errors gracefully** with proper error types
5. **Monitor resource usage** to prevent overconsumption
6. **Clean up processes** when done to free resources
7. **Use sessions** for related commands to maintain context
8. **Cache results** when appropriate to improve performance

## Security Considerations

[Section titled “Security Considerations”](#security-considerations)

1. **Sandbox isolation**: Always run untrusted code in isolated environments
2. **Input validation**: Sanitize and validate all user inputs
3. **Resource limits**: Set appropriate CPU, memory, and time limits
4. **Network restrictions**: Limit network access when not needed
5. **File system access**: Restrict file system operations to safe directories
6. **Environment variables**: Don’t expose sensitive environment variables

## Related Documentation

[Section titled “Related Documentation”](#related-documentation)

* [Overview](./overview.md) - SDK architecture and concepts
* [Sandbox Management](./sandbox-management.md) - Creating and managing sandboxes
* [Terminal](./terminal.md) - Interactive terminal sessions
* [Filesystem](./filesystem.md) - File operations and management
* [Configuration](./configuration.md) - Execution configuration options

# Configuration

ComputeSDK provides flexible configuration options for customizing sandbox behavior, performance settings, and provider-specific options. Configuration can be set globally, per-instance, or dynamically at runtime.

## Quick Start

[Section titled “Quick Start”](#quick-start)

```
import { compute } from 'computesdk'

// Basic configuration
const sandbox = await compute('e2b', {
  template: 'python',
  timeoutMs: 30000,
  metadata: { project: 'my-app' }
})
```

## Configuration Hierarchy

[Section titled “Configuration Hierarchy”](#configuration-hierarchy)

Configuration is applied in the following order (later takes precedence):

1. **Provider defaults** - Built-in provider settings
2. **Global configuration** - Set via `setGlobalConfig()`
3. **Instance configuration** - Passed to `compute()` function
4. **Runtime configuration** - Dynamic updates during execution

## Global Configuration

[Section titled “Global Configuration”](#global-configuration)

### Setting Global Config

[Section titled “Setting Global Config”](#setting-global-config)

```
import { setGlobalConfig } from 'computesdk'

setGlobalConfig({
  // Default provider when none specified
  defaultProvider: 'e2b',
  
  // Global timeout for all operations
  timeoutMs: 60000,
  
  // Retry configuration
  retries: {
    maxAttempts: 3,
    delayMs: 1000,
    backoff: 'exponential'
  },
  
  // Logging configuration
  logging: {
    level: 'info',
    includeTimestamps: true,
    includeProviderLogs: false
  },
  
  // Resource limits
  resources: {
    maxConcurrentSandboxes: 5,
    maxMemoryMB: 2048,
    maxCpuCores: 2
  }
})
```

### Getting Global Config

[Section titled “Getting Global Config”](#getting-global-config)

```
import { getGlobalConfig } from 'computesdk'

const config = getGlobalConfig()
console.log('Current config:', config)
```

## Instance Configuration

[Section titled “Instance Configuration”](#instance-configuration)

### Basic Options

[Section titled “Basic Options”](#basic-options)

```
interface ComputeConfig {
  // Provider-specific template or image
  template?: string
  
  // Custom metadata for the sandbox
  metadata?: Record<string, any>
  
  // Timeout for operations (ms)
  timeoutMs?: number
  
  // Keep sandbox alive after script completion
  keepAlive?: boolean
  
  // Environment variables
  env?: Record<string, string>
  
  // Working directory
  workingDirectory?: string
  
  // Resource limits
  resources?: ResourceConfig
  
  // Networking configuration
  network?: NetworkConfig
  
  // File system configuration
  filesystem?: FilesystemConfig
}
```

### Resource Configuration

[Section titled “Resource Configuration”](#resource-configuration)

```
interface ResourceConfig {
  // Memory limit in MB
  memoryMB?: number
  
  // CPU cores (may be fractional)
  cpuCores?: number
  
  // Disk space in MB
  diskMB?: number
  
  // GPU configuration
  gpu?: {
    enabled: boolean
    type?: 'nvidia-t4' | 'nvidia-a100' | 'amd-mi50'
    memory?: number
  }
}

const sandbox = await compute('modal', {
  resources: {
    memoryMB: 4096,
    cpuCores: 4,
    gpu: {
      enabled: true,
      type: 'nvidia-a100',
      memory: 16384
    }
  }
})
```

### Network Configuration

[Section titled “Network Configuration”](#network-configuration)

```
interface NetworkConfig {
  // Enable internet access
  internetAccess?: boolean
  
  // Custom DNS servers
  dns?: string[]
  
  // Port forwarding
  ports?: {
    internal: number
    external?: number
    protocol?: 'tcp' | 'udp'
  }[]
  
  // Proxy configuration
  proxy?: {
    http?: string
    https?: string
    noProxy?: string[]
  }
}

const sandbox = await compute('e2b', {
  network: {
    internetAccess: true,
    ports: [
      { internal: 3000, external: 8080 },
      { internal: 5432, protocol: 'tcp' }
    ],
    dns: ['8.8.8.8', '1.1.1.1']
  }
})
```

### Filesystem Configuration

[Section titled “Filesystem Configuration”](#filesystem-configuration)

```
interface FilesystemConfig {
  // Mount points
  mounts?: {
    source: string
    target: string
    readOnly?: boolean
  }[]
  
  // Initial files to copy
  files?: {
    path: string
    content: string | Buffer
    mode?: number
  }[]
  
  // Workspace initialization
  workspace?: {
    // Git repository to clone
    git?: {
      url: string
      branch?: string
      token?: string
    }
    
    // Template to use
    template?: string
    
    // Files to ignore
    ignore?: string[]
  }
}

const sandbox = await compute('daytona', {
  filesystem: {
    workspace: {
      git: {
        url: 'https://github.com/user/repo.git',
        branch: 'main'
      }
    },
    files: [
      {
        path: '.env',
        content: 'NODE_ENV=development\nAPI_KEY=secret',
        mode: 0o600
      }
    ]
  }
})
```

## Provider-Specific Configuration

[Section titled “Provider-Specific Configuration”](#provider-specific-configuration)

### E2B Configuration

[Section titled “E2B Configuration”](#e2b-configuration)

```
const sandbox = await compute('e2b', {
  // E2B template ID
  template: 'python-3.11',
  
  // E2B-specific options
  e2b: {
    // Sandbox lifetime in minutes
    lifetimeMinutes: 60,
    
    // Team ID for organization sandboxes
    teamId: 'team-123',
    
    // Custom domain
    domain: 'custom.e2b.dev'
  }
})
```

### Vercel Configuration

[Section titled “Vercel Configuration”](#vercel-configuration)

```
const sandbox = await compute('vercel', {
  // Vercel runtime
  template: 'nodejs18.x',
  
  // Vercel-specific options
  vercel: {
    // Region for execution
    region: 'iad1',
    
    // Project ID
    projectId: 'prj_123',
    
    // Team ID
    teamId: 'team_456'
  }
})
```

### Modal Configuration

[Section titled “Modal Configuration”](#modal-configuration)

```
const sandbox = await compute('modal', {
  // Modal image
  template: 'modal-labs/transformers:latest',
  
  // Modal-specific options
  modal: {
    // Workspace name
    workspace: 'my-workspace',
    
    // Secrets to mount
    secrets: ['huggingface-token', 'aws-credentials'],
    
    // Shared volumes
    volumes: ['/data', '/models']
  }
})
```

### CodeSandbox Configuration

[Section titled “CodeSandbox Configuration”](#codesandbox-configuration)

```
const sandbox = await compute('codesandbox', {
  // CodeSandbox template
  template: 'node',
  
  // CodeSandbox-specific options
  codesandbox: {
    // Team ID
    teamId: 'team-789',
    
    // Privacy setting
    privacy: 'public' | 'private' | 'unlisted',
    
    // Editor preferences
    editor: {
      theme: 'dark',
      fontSize: 14,
      tabSize: 2
    }
  }
})
```

## Dynamic Configuration

[Section titled “Dynamic Configuration”](#dynamic-configuration)

### Runtime Updates

[Section titled “Runtime Updates”](#runtime-updates)

```
const sandbox = await compute('e2b', { template: 'python' })

// Update configuration at runtime
await sandbox.updateConfig({
  timeoutMs: 90000,
  env: {
    ...sandbox.config.env,
    NEW_VAR: 'value'
  }
})
```

### Environment Variables

[Section titled “Environment Variables”](#environment-variables)

```
// Set environment variables
await sandbox.setEnv({
  'NODE_ENV': 'production',
  'API_URL': 'https://api.example.com'
})

// Get environment variable
const nodeEnv = await sandbox.getEnv('NODE_ENV')

// Remove environment variable
await sandbox.unsetEnv('DEBUG')
```

### Working Directory

[Section titled “Working Directory”](#working-directory)

```
// Change working directory
await sandbox.cd('/app/src')

// Get current working directory
const cwd = await sandbox.pwd()
console.log('Current directory:', cwd)
```

## Configuration Validation

[Section titled “Configuration Validation”](#configuration-validation)

### Schema Validation

[Section titled “Schema Validation”](#schema-validation)

ComputeSDK validates configuration using JSON Schema:

```
import { validateConfig } from 'computesdk'

const config = {
  template: 'python',
  timeoutMs: 30000,
  resources: {
    memoryMB: 1024
  }
}

try {
  validateConfig(config)
  console.log('Configuration is valid')
} catch (error) {
  console.error('Invalid configuration:', error.message)
}
```

### Custom Validation

[Section titled “Custom Validation”](#custom-validation)

```
import { addConfigValidator } from 'computesdk'

// Add custom validation rule
addConfigValidator('memoryLimit', (config) => {
  if (config.resources?.memoryMB > 8192) {
    throw new Error('Memory limit cannot exceed 8GB')
  }
})
```

## Configuration Templates

[Section titled “Configuration Templates”](#configuration-templates)

### Predefined Templates

[Section titled “Predefined Templates”](#predefined-templates)

```
import { configTemplates } from 'computesdk'

// Development template
const devConfig = configTemplates.development({
  provider: 'e2b',
  template: 'nodejs18'
})

// Production template
const prodConfig = configTemplates.production({
  provider: 'vercel',
  region: 'iad1'
})

// ML/AI template
const mlConfig = configTemplates.ml({
  provider: 'modal',
  gpu: 'nvidia-a100'
})
```

### Custom Templates

[Section titled “Custom Templates”](#custom-templates)

```
import { createConfigTemplate } from 'computesdk'

const myTemplate = createConfigTemplate('web-dev', {
  template: 'nodejs18',
  timeoutMs: 60000,
  resources: {
    memoryMB: 2048,
    cpuCores: 2
  },
  network: {
    internetAccess: true,
    ports: [{ internal: 3000 }]
  },
  env: {
    NODE_ENV: 'development'
  }
})

// Use the template
const sandbox = await compute('e2b', myTemplate)
```

## Environment-Based Configuration

[Section titled “Environment-Based Configuration”](#environment-based-configuration)

### Configuration Files

[Section titled “Configuration Files”](#configuration-files)

```
// compute.config.js
export default {
  development: {
    provider: 'e2b',
    template: 'nodejs18',
    timeoutMs: 30000,
    logging: { level: 'debug' }
  },
  
  staging: {
    provider: 'vercel',
    template: 'nodejs18.x',
    timeoutMs: 60000,
    logging: { level: 'info' }
  },
  
  production: {
    provider: 'vercel',
    template: 'nodejs18.x',
    timeoutMs: 120000,
    logging: { level: 'error' },
    retries: { maxAttempts: 5 }
  }
}
```

```
import { loadConfig } from 'computesdk'

// Load environment-specific configuration
const config = await loadConfig('./compute.config.js', process.env.NODE_ENV)
const sandbox = await compute(config.provider, config)
```

### Environment Variables

[Section titled “Environment Variables”](#environment-variables-1)

```
# .env
COMPUTE_PROVIDER=e2b
COMPUTE_TEMPLATE=python
COMPUTE_TIMEOUT_MS=60000
COMPUTE_LOG_LEVEL=info
E2B_API_KEY=your-api-key
```

```
import { loadConfigFromEnv } from 'computesdk'

// Load configuration from environment variables
const config = loadConfigFromEnv({
  prefix: 'COMPUTE_',
  provider: process.env.COMPUTE_PROVIDER,
  apiKey: process.env[`${process.env.COMPUTE_PROVIDER?.toUpperCase()}_API_KEY`]
})
```

## Performance Optimization

[Section titled “Performance Optimization”](#performance-optimization)

### Connection Pooling

[Section titled “Connection Pooling”](#connection-pooling)

```
setGlobalConfig({
  connectionPool: {
    // Maximum concurrent connections per provider
    maxConnections: 10,
    
    // Keep connections alive
    keepAlive: true,
    
    // Connection timeout
    connectTimeoutMs: 10000,
    
    // Idle timeout
    idleTimeoutMs: 300000
  }
})
```

### Caching

[Section titled “Caching”](#caching)

```
setGlobalConfig({
  cache: {
    // Cache sandbox instances
    enabled: true,
    
    // Cache TTL in milliseconds
    ttlMs: 300000,
    
    // Maximum cache size
    maxSize: 100,
    
    // Cache key strategy
    keyStrategy: 'provider-template-config'
  }
})
```

## Error Handling Configuration

[Section titled “Error Handling Configuration”](#error-handling-configuration)

```
setGlobalConfig({
  errorHandling: {
    // Retry configuration
    retries: {
      maxAttempts: 3,
      delayMs: 1000,
      backoff: 'exponential',
      retryableErrors: ['TIMEOUT', 'NETWORK_ERROR']
    },
    
    // Error reporting
    reporting: {
      enabled: true,
      endpoint: 'https://errors.example.com',
      includeStack: true
    }
  }
})
```

## Configuration Best Practices

[Section titled “Configuration Best Practices”](#configuration-best-practices)

1. **Use Environment Variables**: Store sensitive data like API keys in environment variables
2. **Validate Configuration**: Always validate configuration before use
3. **Use Templates**: Create reusable configuration templates for common scenarios
4. **Monitor Resources**: Set appropriate resource limits to avoid unexpected costs
5. **Environment Separation**: Use different configurations for development, staging, and production
6. **Documentation**: Document custom configuration options for your team

## Troubleshooting

[Section titled “Troubleshooting”](#troubleshooting)

### Common Configuration Issues

[Section titled “Common Configuration Issues”](#common-configuration-issues)

```
// Issue: Invalid template name
const sandbox = await compute('e2b', { template: 'invalid-template' })
// Solution: Check available templates
const templates = await getAvailableTemplates('e2b')

// Issue: Insufficient resources
const sandbox = await compute('modal', { 
  resources: { memoryMB: 32000 } // Too much memory
})
// Solution: Check provider limits
const limits = await getProviderLimits('modal')

// Issue: Configuration not taking effect
setGlobalConfig({ timeoutMs: 60000 })
const sandbox = await compute('e2b', { timeoutMs: 30000 }) // Instance config overrides global
```

### Debugging Configuration

[Section titled “Debugging Configuration”](#debugging-configuration)

```
import { debugConfig } from 'computesdk'

// Enable configuration debugging
debugConfig(true)

// This will log detailed configuration information
const sandbox = await compute('e2b', config)
```

## Related Documentation

[Section titled “Related Documentation”](#related-documentation)

* [Overview](./overview.md) - SDK architecture and concepts
* [Sandbox Management](./sandbox-management.md) - Creating and managing sandboxes
* [Providers](../providers/) - Provider-specific configuration options
* [Getting Started](../getting-started/installation.md) - Initial setup and configuration

# Filesystem

ComputeSDK provides comprehensive filesystem operations for managing files and directories within sandboxes. Perform file I/O, manage permissions, sync files, and handle large datasets across different providers.

## Quick Start

[Section titled “Quick Start”](#quick-start)

```
import { compute } from 'computesdk'

const sandbox = await compute('e2b')

// Write a file
await sandbox.writeFile('/app/config.json', JSON.stringify({ debug: true }))

// Read a file
const content = await sandbox.readFile('/app/config.json')

// List directory contents
const files = await sandbox.listFiles('/app')
```

## Basic File Operations

[Section titled “Basic File Operations”](#basic-file-operations)

### Reading Files

[Section titled “Reading Files”](#reading-files)

```
// Read text file
const content = await sandbox.readFile('/path/to/file.txt')
console.log(content)

// Read binary file
const buffer = await sandbox.readFile('/path/to/image.png', { encoding: 'binary' })

// Read with options
const content = await sandbox.readFile('/large-file.txt', {
  encoding: 'utf8',
  maxSize: 1024 * 1024, // 1MB limit
  offset: 1000,         // Start from byte 1000
  length: 5000          // Read 5000 bytes
})

// Stream read for large files
const stream = await sandbox.readFileStream('/large-dataset.csv')
stream.on('data', (chunk) => {
  console.log('Chunk:', chunk.toString())
})
```

### Writing Files

[Section titled “Writing Files”](#writing-files)

```
// Write text file
await sandbox.writeFile('/path/to/output.txt', 'Hello, World!')

// Write JSON
await sandbox.writeFile('/config.json', JSON.stringify({ env: 'production' }))

// Write binary data
const imageBuffer = Buffer.from(base64Image, 'base64')
await sandbox.writeFile('/images/photo.jpg', imageBuffer)

// Write with options
await sandbox.writeFile('/secure.txt', 'secret data', {
  mode: 0o600,          // Read/write for owner only
  createDirs: true,     // Create parent directories
  backup: true          // Create backup of existing file
})

// Append to file
await sandbox.appendFile('/logs/app.log', `${new Date().toISOString()} - Event logged\n`)

// Stream write for large files
const writeStream = await sandbox.writeFileStream('/output/large-data.json')
writeStream.write('{"data": [')
// ... write data in chunks
writeStream.end(']}')
```

### File Information

[Section titled “File Information”](#file-information)

```
// Get file stats
const stats = await sandbox.stat('/path/to/file.txt')
console.log('Size:', stats.size)
console.log('Modified:', stats.mtime)
console.log('Is directory:', stats.isDirectory())
console.log('Permissions:', stats.mode.toString(8))

// Check if file exists
const exists = await sandbox.exists('/path/to/file.txt')

// Get file type
const type = await sandbox.getFileType('/path/to/file')
console.log('MIME type:', type.mime)
console.log('Extension:', type.extension)
```

## Directory Operations

[Section titled “Directory Operations”](#directory-operations)

### Creating Directories

[Section titled “Creating Directories”](#creating-directories)

```
// Create single directory
await sandbox.mkdir('/new/directory')

// Create nested directories
await sandbox.mkdir('/deep/nested/path', { recursive: true })

// Create with specific permissions
await sandbox.mkdir('/secure-dir', { mode: 0o755 })

// Create temporary directory
const tempDir = await sandbox.mkdtemp('/tmp/myapp-')
console.log('Temp directory:', tempDir)
```

### Listing Directories

[Section titled “Listing Directories”](#listing-directories)

```
// List files in directory
const files = await sandbox.listFiles('/app')
files.forEach(file => {
  console.log(`${file.name} (${file.type}) - ${file.size} bytes`)
})

// List with detailed information
const files = await sandbox.listFiles('/app', {
  detailed: true,
  includeHidden: true,
  recursive: false
})

// Recursive listing
const allFiles = await sandbox.listFiles('/project', { recursive: true })

// Filter files
const pythonFiles = await sandbox.listFiles('/src', {
  filter: (file) => file.name.endsWith('.py')
})

// Sort files
const sortedFiles = await sandbox.listFiles('/docs', {
  sort: 'modified', // 'name', 'size', 'modified'
  order: 'desc'     // 'asc', 'desc'
})
```

### Directory Tree

[Section titled “Directory Tree”](#directory-tree)

```
// Get directory tree structure
const tree = await sandbox.getDirectoryTree('/project')
console.log(JSON.stringify(tree, null, 2))

// Tree with file contents
const treeWithContent = await sandbox.getDirectoryTree('/config', {
  includeContent: true,
  maxDepth: 3,
  exclude: ['node_modules', '.git']
})
```

## File Operations

[Section titled “File Operations”](#file-operations)

### Copying and Moving

[Section titled “Copying and Moving”](#copying-and-moving)

```
// Copy file
await sandbox.copyFile('/source.txt', '/destination.txt')

// Copy directory recursively
await sandbox.copyDirectory('/src', '/backup/src')

// Move/rename file
await sandbox.moveFile('/old-name.txt', '/new-name.txt')

// Move directory
await sandbox.moveDirectory('/old-location', '/new-location')

// Copy with options
await sandbox.copyFile('/source.txt', '/dest.txt', {
  overwrite: true,
  preserveTimestamps: true,
  createDirs: true
})
```

### Deleting Files

[Section titled “Deleting Files”](#deleting-files)

```
// Delete file
await sandbox.deleteFile('/path/to/file.txt')

// Delete directory
await sandbox.deleteDirectory('/path/to/directory')

// Delete recursively
await sandbox.deleteDirectory('/path/to/directory', { recursive: true })

// Safe delete with confirmation
await sandbox.deleteFile('/important.txt', { 
  confirm: true,
  backup: true 
})

// Bulk delete
await sandbox.deleteFiles([
  '/temp/file1.txt',
  '/temp/file2.txt',
  '/temp/file3.txt'
])
```

### File Permissions

[Section titled “File Permissions”](#file-permissions)

```
// Change file permissions
await sandbox.chmod('/script.sh', 0o755) // rwxr-xr-x

// Change ownership (if supported)
await sandbox.chown('/file.txt', 'user', 'group')

// Get permissions
const permissions = await sandbox.getPermissions('/file.txt')
console.log('Permissions:', permissions.mode.toString(8))
console.log('Owner:', permissions.owner)
console.log('Group:', permissions.group)
```

## File Watching

[Section titled “File Watching”](#file-watching)

### Watch for Changes

[Section titled “Watch for Changes”](#watch-for-changes)

```
// Watch single file
const watcher = sandbox.watchFile('/config.json')

watcher.on('change', (event) => {
  console.log('File changed:', event.path)
  console.log('Change type:', event.type) // 'modified', 'created', 'deleted'
})

watcher.on('error', (error) => {
  console.error('Watch error:', error)
})

// Stop watching
watcher.close()
```

### Watch Directory

[Section titled “Watch Directory”](#watch-directory)

```
// Watch directory for changes
const dirWatcher = sandbox.watchDirectory('/src', {
  recursive: true,
  ignore: ['node_modules', '*.tmp']
})

dirWatcher.on('change', (event) => {
  console.log(`${event.type}: ${event.path}`)
  
  if (event.type === 'created' && event.path.endsWith('.js')) {
    console.log('New JavaScript file created')
  }
})

// Watch with debouncing
const debouncedWatcher = sandbox.watchDirectory('/src', {
  debounce: 1000 // Wait 1 second before emitting events
})
```

## File Transfer

[Section titled “File Transfer”](#file-transfer)

### Upload Files

[Section titled “Upload Files”](#upload-files)

```
// Upload single file from local machine
await sandbox.uploadFile('./local-file.txt', '/remote/path/file.txt')

// Upload directory
await sandbox.uploadDirectory('./local-dir', '/remote/dir')

// Upload with progress tracking
await sandbox.uploadFile('./large-file.zip', '/remote/file.zip', {
  onProgress: (progress) => {
    console.log(`Upload progress: ${progress.percent}%`)
  }
})

// Upload multiple files
await sandbox.uploadFiles([
  { local: './file1.txt', remote: '/app/file1.txt' },
  { local: './file2.txt', remote: '/app/file2.txt' }
])

// Upload from URL
await sandbox.uploadFromUrl('https://example.com/file.zip', '/downloads/file.zip')
```

### Download Files

[Section titled “Download Files”](#download-files)

```
// Download single file
await sandbox.downloadFile('/remote/file.txt', './local-file.txt')

// Download directory
await sandbox.downloadDirectory('/remote/dir', './local-dir')

// Download with compression
await sandbox.downloadFile('/large-file.txt', './file.txt.gz', {
  compress: true
})

// Download multiple files as archive
await sandbox.downloadFiles([
  '/app/config.json',
  '/app/package.json',
  '/app/README.md'
], './app-files.tar.gz')

// Download to memory
const content = await sandbox.downloadToBuffer('/remote/file.txt')
```

### Sync Operations

[Section titled “Sync Operations”](#sync-operations)

```
// Sync local directory to sandbox
await sandbox.syncTo('./local-project', '/remote/project', {
  exclude: ['node_modules', '.git'],
  delete: true, // Delete files not in source
  preserveTimestamps: true
})

// Sync sandbox directory to local
await sandbox.syncFrom('/remote/project', './local-backup', {
  includeHidden: false,
  overwrite: true
})

// Two-way sync
await sandbox.syncBidirectional('./local-dir', '/remote/dir', {
  conflict: 'newer', // 'newer', 'local', 'remote', 'prompt'
  backup: true
})
```

## Advanced File Operations

[Section titled “Advanced File Operations”](#advanced-file-operations)

### File Search

[Section titled “File Search”](#file-search)

```
// Find files by name
const files = await sandbox.findFiles('/project', {
  name: '*.py',
  type: 'file'
})

// Find files by content
const matches = await sandbox.grep('/src', 'TODO:', {
  recursive: true,
  include: '*.js',
  exclude: 'node_modules'
})

// Advanced search
const results = await sandbox.search('/project', {
  name: /test.*\.js$/,
  size: { min: 1024, max: 1024 * 1024 },
  modified: { after: new Date('2023-01-01') },
  content: 'import.*react'
})
```

### File Compression

[Section titled “File Compression”](#file-compression)

```
// Create archive
await sandbox.createArchive('/backup.tar.gz', [
  '/app',
  '/config',
  '/data'
], {
  compression: 'gzip',
  exclude: ['*.tmp', 'node_modules']
})

// Extract archive
await sandbox.extractArchive('/backup.tar.gz', '/restore', {
  overwrite: true,
  preservePermissions: true
})

// Compress single file
await sandbox.compressFile('/large-file.txt', '/large-file.txt.gz')

// Decompress file
await sandbox.decompressFile('/file.gz', '/file.txt')
```

### File Encryption

[Section titled “File Encryption”](#file-encryption)

```
// Encrypt file
await sandbox.encryptFile('/sensitive.txt', '/sensitive.txt.enc', {
  algorithm: 'aes-256-gcm',
  password: 'secret-password'
})

// Decrypt file
await sandbox.decryptFile('/sensitive.txt.enc', '/sensitive.txt', {
  password: 'secret-password'
})

// Encrypt directory
await sandbox.encryptDirectory('/secrets', '/secrets.enc', {
  recursive: true,
  password: 'directory-password'
})
```

### File Checksums

[Section titled “File Checksums”](#file-checksums)

```
// Calculate file checksum
const checksum = await sandbox.checksum('/file.txt', 'sha256')
console.log('SHA256:', checksum)

// Verify file integrity
const isValid = await sandbox.verifyChecksum('/file.txt', expectedChecksum)

// Calculate checksums for directory
const checksums = await sandbox.checksumDirectory('/project', {
  algorithm: 'md5',
  recursive: true
})
```

## Working with Large Files

[Section titled “Working with Large Files”](#working-with-large-files)

### Streaming Operations

[Section titled “Streaming Operations”](#streaming-operations)

```
// Process large file in chunks
const processor = await sandbox.processFileStream('/huge-dataset.csv')

processor.on('chunk', (chunk, index) => {
  console.log(`Processing chunk ${index}:`, chunk.length, 'bytes')
  // Process chunk data
})

processor.on('complete', (stats) => {
  console.log('Processing complete:', stats)
})

// Transform file while streaming
const transformer = sandbox.transformFile('/input.csv', '/output.json', {
  transform: (line) => {
    const data = line.split(',')
    return JSON.stringify({ id: data[0], name: data[1] }) + '\n'
  }
})
```

### Partial File Operations

[Section titled “Partial File Operations”](#partial-file-operations)

```
// Read part of file
const chunk = await sandbox.readFileChunk('/large-file.txt', {
  start: 1000000,  // Start at 1MB
  size: 1024       // Read 1KB
})

// Write to specific position
await sandbox.writeFileChunk('/file.txt', 'inserted text', {
  position: 500
})

// Truncate file
await sandbox.truncateFile('/file.txt', 1024) // Keep first 1KB
```

## File Metadata and Extended Attributes

[Section titled “File Metadata and Extended Attributes”](#file-metadata-and-extended-attributes)

### Metadata Operations

[Section titled “Metadata Operations”](#metadata-operations)

```
// Set custom metadata
await sandbox.setMetadata('/file.txt', {
  author: 'John Doe',
  project: 'my-app',
  version: '1.0.0'
})

// Get metadata
const metadata = await sandbox.getMetadata('/file.txt')
console.log('Custom metadata:', metadata)

// Set extended attributes (if supported)
await sandbox.setExtendedAttribute('/file.txt', 'user.category', 'document')

// Get extended attributes
const attrs = await sandbox.getExtendedAttributes('/file.txt')
```

### File Tags and Labels

[Section titled “File Tags and Labels”](#file-tags-and-labels)

```
// Add tags to file
await sandbox.addTags('/file.txt', ['important', 'config', 'production'])

// Search files by tags
const taggedFiles = await sandbox.findFilesByTags(['important'])

// Remove tags
await sandbox.removeTags('/file.txt', ['production'])

// List all tags
const allTags = await sandbox.getAllTags()
```

## Error Handling

[Section titled “Error Handling”](#error-handling)

### File Operation Errors

[Section titled “File Operation Errors”](#file-operation-errors)

```
try {
  await sandbox.readFile('/nonexistent.txt')
} catch (error) {
  if (error.code === 'ENOENT') {
    console.log('File not found')
  } else if (error.code === 'EACCES') {
    console.log('Permission denied')
  } else if (error.code === 'ENOSPC') {
    console.log('No space left on device')
  }
}

// Retry with exponential backoff
async function retryFileOperation(operation: () => Promise<any>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation()
    } catch (error) {
      if (i === maxRetries - 1) throw error
      
      const delay = Math.pow(2, i) * 1000
      await new Promise(resolve => setTimeout(resolve, delay))
    }
  }
}
```

### Safe File Operations

[Section titled “Safe File Operations”](#safe-file-operations)

```
// Atomic file write
async function atomicWrite(sandbox: Sandbox, path: string, content: string) {
  const tempPath = `${path}.tmp.${Date.now()}`
  
  try {
    await sandbox.writeFile(tempPath, content)
    await sandbox.moveFile(tempPath, path)
  } catch (error) {
    // Clean up temp file if it exists
    if (await sandbox.exists(tempPath)) {
      await sandbox.deleteFile(tempPath)
    }
    throw error
  }
}

// File locking
async function withFileLock(sandbox: Sandbox, path: string, operation: () => Promise<void>) {
  const lockPath = `${path}.lock`
  
  // Acquire lock
  if (await sandbox.exists(lockPath)) {
    throw new Error('File is locked')
  }
  
  await sandbox.writeFile(lockPath, process.pid.toString())
  
  try {
    await operation()
  } finally {
    // Release lock
    await sandbox.deleteFile(lockPath)
  }
}
```

## Performance Optimization

[Section titled “Performance Optimization”](#performance-optimization)

### Batch Operations

[Section titled “Batch Operations”](#batch-operations)

```
// Batch file operations
const operations = [
  { type: 'write', path: '/file1.txt', content: 'content1' },
  { type: 'write', path: '/file2.txt', content: 'content2' },
  { type: 'mkdir', path: '/new-dir' },
  { type: 'copy', source: '/src.txt', dest: '/dest.txt' }
]

await sandbox.batchFileOperations(operations)

// Parallel uploads
const uploadPromises = files.map(file => 
  sandbox.uploadFile(file.local, file.remote)
)
await Promise.all(uploadPromises)
```

### Caching and Optimization

[Section titled “Caching and Optimization”](#caching-and-optimization)

```
// Enable file system caching
sandbox.enableFsCache({
  maxSize: 100 * 1024 * 1024, // 100MB cache
  ttl: 300000                 // 5 minute TTL
})

// Optimize for sequential access
await sandbox.optimizeForSequentialAccess('/large-file.dat')

// Preload frequently accessed files
await sandbox.preloadFiles([
  '/config/app.json',
  '/templates/main.html'
])
```

## Integration Examples

[Section titled “Integration Examples”](#integration-examples)

### Version Control Integration

[Section titled “Version Control Integration”](#version-control-integration)

```
// Git integration
class GitFileManager {
  constructor(private sandbox: Sandbox) {}

async initRepo(path: string) {
    await this.sandbox.exec(`git init ${path}`)
  }

async addFiles(files: string[]) {
    await this.sandbox.exec(`git add ${files.join(' ')}`)
  }

async commit(message: string) {
    await this.sandbox.exec(`git commit -m "${message}"`)
  }

async getChangedFiles() {
    const result = await this.sandbox.exec('git diff --name-only')
    return result.stdout.split('\n').filter(Boolean)
  }
}
```

### Database Integration

[Section titled “Database Integration”](#database-integration)

```
// File-based database operations
class FileDatabase {
  constructor(private sandbox: Sandbox, private dbPath: string) {}

async insert(collection: string, data: any) {
    const filePath = `${this.dbPath}/${collection}.json`
    
    let records = []
    if (await this.sandbox.exists(filePath)) {
      const content = await this.sandbox.readFile(filePath)
      records = JSON.parse(content)
    }
    
    records.push({ ...data, _id: Date.now() })
    await this.sandbox.writeFile(filePath, JSON.stringify(records, null, 2))
  }

async find(collection: string, query: any = {}) {
    const filePath = `${this.dbPath}/${collection}.json`
    
    if (!await this.sandbox.exists(filePath)) {
      return []
    }
    
    const content = await this.sandbox.readFile(filePath)
    const records = JSON.parse(content)
    
    return records.filter(record => 
      Object.entries(query).every(([key, value]) => record[key] === value)
    )
  }
}
```

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Error Handling**: Always handle file operation errors gracefully
2. **Resource Cleanup**: Close file streams and watchers when done
3. **Path Validation**: Validate file paths to prevent directory traversal
4. **Atomic Operations**: Use atomic operations for critical file updates
5. **Backup Strategy**: Create backups before destructive operations
6. **Performance**: Use streaming for large files to avoid memory issues
7. **Security**: Validate file permissions and sanitize file paths
8. **Monitoring**: Monitor disk usage and file operation performance

## Related Documentation

[Section titled “Related Documentation”](#related-documentation)

* [Overview](./overview.md) - SDK architecture and concepts
* [Code Execution](./code-execution.md) - Running code and commands
* [Sandbox Management](./sandbox-management.md) - Managing sandbox lifecycle
* [Terminal](./terminal.md) - Interactive terminal operations
* [Configuration](./configuration.md) - Filesystem configuration options

# Overview

Complete reference documentation for ComputeSDK’s APIs and interfaces.

## What is ComputeSDK?

[Section titled “What is ComputeSDK?”](#what-is-computesdk)

ComputeSDK provides a unified abstraction layer for executing code in secure, isolated sandboxed environments across multiple cloud providers. The API is designed to be consistent across all providers while allowing for provider-specific features.

## Architecture

[Section titled “Architecture”](#architecture)

ComputeSDK follows a clean provider/sandbox separation architecture:

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Your App      │ → │   ComputeSDK     │ → │   Provider      │
│                 │    │   Core API       │    │   (E2B, etc.)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                       ┌──────────────────┐
                       │    Sandbox       │
                       │   - Code Exec    │
                       │   - Filesystem   │
                       │   - Terminal     │
                       └──────────────────┘
```

## Basic Usage Pattern

[Section titled “Basic Usage Pattern”](#basic-usage-pattern)

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

// 1. Configure provider
compute.setConfig({ 
  provider: e2b({ apiKey: process.env.E2B_API_KEY }) 
});

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

// 3. Execute operations
const result = await sandbox.runCode('print("Hello World!")');
console.log(result.stdout);

// 4. Clean up
await compute.sandbox.destroy(sandbox.sandboxId);
```

## Core Components

[Section titled “Core Components”](#core-components)

### Configuration Management

[Section titled “Configuration Management”](#configuration-management)

Global configuration and provider setup:

* `compute.setConfig(config)` - Set global configuration
* `compute.getConfig()` - Get current configuration
* `compute.clearConfig()` - Clear configuration

### Sandbox Management

[Section titled “Sandbox Management”](#sandbox-management)

Create and manage isolated execution environments:

* `compute.sandbox.create(options)` - Create new sandbox
* `compute.sandbox.getById(id)` - Get existing sandbox
* `compute.sandbox.list()` - List all sandboxes
* `compute.sandbox.destroy(id)` - Destroy sandbox

### Code Execution

[Section titled “Code Execution”](#code-execution)

Execute code and shell commands:

* `sandbox.runCode(code, runtime?)` - Execute code
* `sandbox.runCommand(command, args?)` - Run shell command

### Filesystem Operations

[Section titled “Filesystem Operations”](#filesystem-operations)

File and directory management:

* `sandbox.filesystem.writeFile(path, content)` - Write file
* `sandbox.filesystem.readFile(path)` - Read file
* `sandbox.filesystem.mkdir(path)` - Create directory
* `sandbox.filesystem.readdir(path)` - List directory
* `sandbox.filesystem.exists(path)` - Check if exists
* `sandbox.filesystem.remove(path)` - Remove file/directory

### Terminal Operations

[Section titled “Terminal Operations”](#terminal-operations)

Interactive terminal sessions (E2B only):

* `sandbox.terminal.create(options)` - Create terminal
* `sandbox.terminal.list()` - List terminals
* `sandbox.terminal.getById(id)` - Get terminal by ID
* `terminal.write(data)` - Write to terminal
* `terminal.resize(cols, rows)` - Resize terminal
* `terminal.kill()` - Kill terminal

### Web Integration

[Section titled “Web Integration”](#web-integration)

Built-in request handler for web frameworks:

* `handleComputeRequest(options)` - Process web requests

## Supported Runtimes

[Section titled “Supported Runtimes”](#supported-runtimes)

ComputeSDK supports multiple runtime environments with automatic detection:

* **Python** - Python 3.x with data science libraries (pandas, numpy, etc.)
* **Node.js** - Node.js runtime with npm package support
* **Auto-detection** - Runtime automatically detected based on code patterns

### Runtime Detection

[Section titled “Runtime Detection”](#runtime-detection)

The SDK automatically detects the appropriate runtime:

**Python indicators:**

* `print(` statements
* `import` statements
* `def` function definitions
* Python-specific syntax (`f"`, `__`, etc.)

**Default:** Node.js for all other cases

## Provider Support Matrix

[Section titled “Provider Support Matrix”](#provider-support-matrix)

Different providers support different features:

| Feature                | E2B     | Vercel | Blaxel | Daytona | CodeSandbox | Modal |
| ---------------------- | ------- | ------ | ------ | ------- | ----------- | ----- |
| **Code Execution**     | ✅       | ✅      | ✅      | ✅       | ✅           | ✅     |
| **Filesystem**         | ✅       | ✅      | ✅      | ✅       | ✅           | ✅     |
| **Terminal**           | ✅       | ❌      | ❌      | ❌       | ❌           | ❌     |
| **GPU Support**        | Limited | ❌      | ❌      | ❌       | ❌           | ✅     |
| **Persistent Storage** | ❌       | ❌      | ✅      | ❌       | ❌           | ❌     |

## Error Handling

[Section titled “Error Handling”](#error-handling)

All ComputeSDK methods can throw errors. Always wrap calls in try-catch blocks:

```
try {
  const result = await sandbox.runCode('invalid code');
  
  if (result.exitCode !== 0) {
    console.error('Code execution failed:', result.stderr);
  } else {
    console.log('Success:', result.stdout);
  }
} catch (error: any) {
  console.error('Execution failed:', error.message);
  
  // Handle specific error types
  if (error.message.includes('authentication')) {
    console.error('Check your API key configuration');
  } else if (error.message.includes('quota')) {
    console.error('Provider usage limits exceeded');
  } else if (error.message.includes('timeout')) {
    console.error('Operation timed out');
  }
}
```

## TypeScript Support

[Section titled “TypeScript Support”](#typescript-support)

ComputeSDK is fully typed with comprehensive TypeScript definitions:

```
import type { 
  Sandbox, 
  Provider, 
  ExecutionResult,
  ComputeConfig,
  Runtime,
  FilesystemAPI,
  TerminalAPI 
} from 'computesdk';

// All methods are properly typed
const sandbox: Sandbox = await compute.sandbox.create();
const result: ExecutionResult = await sandbox.runCode('print("Hello")', 'python');
```

## Best Practices

[Section titled “Best Practices”](#best-practices)

### 1. Resource Management

[Section titled “1. Resource Management”](#1-resource-management)

Always clean up sandboxes to avoid resource leaks:

```
const withSandbox = async <T>(
  callback: (sandbox: Sandbox) => Promise<T>
): Promise<T> => {
  const sandbox = await compute.sandbox.create();
  
  try {
    return await callback(sandbox);
  } finally {
    await compute.sandbox.destroy(sandbox.sandboxId);
  }
};

// Usage
const result = await withSandbox(async (sandbox) => {
  return await sandbox.runCode('print("Hello World!")');
});
```

### 2. Error Handling

[Section titled “2. Error Handling”](#2-error-handling)

Implement comprehensive error handling:

```
const executeCode = async (code: string) => {
  try {
    const sandbox = await compute.sandbox.create();
    
    try {
      const result = await sandbox.runCode(code);
      
      if (result.exitCode !== 0) {
        throw new Error(`Code execution failed: ${result.stderr}`);
      }
      
      return result.stdout;
    } finally {
      await compute.sandbox.destroy(sandbox.sandboxId);
    }
  } catch (error: any) {
    console.error('Code execution error:', error.message);
    throw error;
  }
};
```

### 3. Provider Configuration

[Section titled “3. Provider Configuration”](#3-provider-configuration)

Configure providers based on your needs:

```
import { e2b } from '@computesdk/e2b';
import { vercel } from '@computesdk/vercel';
import { blaxel } from '@computesdk/blaxel';

// For data science and interactive development
compute.setConfig({ 
  provider: e2b({ apiKey: process.env.E2B_API_KEY }) 
});

// For serverless execution with long runtimes
compute.setConfig({ 
  provider: vercel({ runtime: 'python' })
});

// For AI-powered development with fast boot times
compute.setConfig({ 
  provider: blaxel({ 
    apiKey: process.env.BLAXEL_API_KEY,
    workspace: process.env.BLAXEL_WORKSPACE
  })
});
```

## Common Patterns

[Section titled “Common Patterns”](#common-patterns)

### Code Execution with Result Processing

[Section titled “Code Execution with Result Processing”](#code-execution-with-result-processing)

```
const processCode = async (code: string, runtime?: 'python' | 'node') => {
  const sandbox = await compute.sandbox.create();
  
  try {
    const result = await sandbox.runCode(code, runtime);
    
    return {
      success: result.exitCode === 0,
      output: result.stdout,
      error: result.stderr,
      executionTime: result.executionTime
    };
  } finally {
    await compute.sandbox.destroy(sandbox.sandboxId);
  }
};

// Usage
const result = await processCode('print("Hello World!")', 'python');
if (result.success) {
  console.log('Output:', result.output);
} else {
  console.error('Error:', result.error);
}
```

### File Processing Workflow

[Section titled “File Processing Workflow”](#file-processing-workflow)

```
const processFile = async (inputData: string, processScript: string) => {
  const sandbox = await compute.sandbox.create();
  
  try {
    // Write input data
    await sandbox.filesystem.writeFile('/tmp/input.txt', inputData);
    
    // Write processing script
    await sandbox.filesystem.writeFile('/tmp/process.py', processScript);
    
    // Execute processing
    const result = await sandbox.runCommand('python', ['/tmp/process.py']);
    
    // Read output
    const output = await sandbox.filesystem.readFile('/tmp/output.txt');
    
    return {
      success: result.exitCode === 0,
      output,
      logs: result.stdout,
      error: result.stderr
    };
  } finally {
    await compute.sandbox.destroy(sandbox.sandboxId);
  }
};
```

## Next Steps

[Section titled “Next Steps”](#next-steps)

Explore the detailed API documentation:

* **[Configuration](./configuration.md)** - Provider setup and global config
* **[Sandbox Management](./sandbox-management.md)** - Creating and managing sandboxes
* **[Code Execution](./code-execution.md)** - Running code and commands
* **[Filesystem](./filesystem.md)** - File and directory operations
* **[Terminal](./terminal.md)** - Interactive terminal sessions
* **[UI Package](./ui-package.md)** - Frontend integration
* **[API Integration](./api-integration.md)** - Web framework integration

For provider-specific features, see:

* **[Provider Documentation](../providers/)** - Detailed provider guides
* **[Framework Integration](../frameworks/)** - Web framework examples

# Sandbox Management

ComputeSDK provides comprehensive sandbox lifecycle management, including creation, configuration, monitoring, and cleanup. Learn how to effectively manage compute resources across different providers.

## Quick Start

[Section titled “Quick Start”](#quick-start)

```
import { compute } from 'computesdk'

// Create a new sandbox
const sandbox = await compute('e2b', {
  template: 'python',
  metadata: { project: 'my-app' }
})

// Use the sandbox
await sandbox.exec('python --version')

// Clean up when done
await sandbox.destroy()
```

## Sandbox Creation

[Section titled “Sandbox Creation”](#sandbox-creation)

### Basic Creation

[Section titled “Basic Creation”](#basic-creation)

```
// Simple sandbox creation
const sandbox = await compute('e2b')

// With configuration
const sandbox = await compute('e2b', {
  template: 'nodejs18',
  timeoutMs: 60000,
  keepAlive: true
})

// With provider-specific options
const sandbox = await compute('modal', {
  template: 'python:3.11',
  resources: {
    cpuCores: 4,
    memoryMB: 8192,
    gpu: { enabled: true, type: 'nvidia-a100' }
  }
})
```

### Template-Based Creation

[Section titled “Template-Based Creation”](#template-based-creation)

```
// Use predefined templates
const webSandbox = await compute('vercel', {
  template: 'nextjs'
})

const mlSandbox = await compute('modal', {
  template: 'pytorch-gpu'
})

const devSandbox = await compute('daytona', {
  template: 'full-stack-dev'
})

// Custom template creation
const customTemplate = {
  name: 'my-python-env',
  baseImage: 'python:3.11-slim',
  packages: ['numpy', 'pandas', 'scikit-learn'],
  env: {
    PYTHONPATH: '/app',
    NODE_ENV: 'development'
  }
}

const sandbox = await compute('e2b', {
  template: customTemplate
})
```

### Batch Creation

[Section titled “Batch Creation”](#batch-creation)

```
// Create multiple sandboxes
const sandboxes = await Promise.all([
  compute('e2b', { template: 'python' }),
  compute('vercel', { template: 'nodejs' }),
  compute('modal', { template: 'gpu-ml' })
])

// Create sandbox pool
class SandboxPool {
  private available: Sandbox[] = []
  private inUse: Set<Sandbox> = new Set()

async acquire(provider: string, config?: any): Promise<Sandbox> {
    let sandbox = this.available.pop()
    
    if (!sandbox) {
      sandbox = await compute(provider, config)
    }
    
    this.inUse.add(sandbox)
    return sandbox
  }

async release(sandbox: Sandbox) {
    this.inUse.delete(sandbox)
    
    // Reset sandbox state
    await sandbox.reset()
    this.available.push(sandbox)
  }

async cleanup() {
    const allSandboxes = [...this.available, ...this.inUse]
    await Promise.all(allSandboxes.map(sb => sb.destroy()))
  }
}
```

## Sandbox Lifecycle

[Section titled “Sandbox Lifecycle”](#sandbox-lifecycle)

### Lifecycle Events

[Section titled “Lifecycle Events”](#lifecycle-events)

```
// Listen to lifecycle events
sandbox.on('created', () => {
  console.log('Sandbox created successfully')
})

sandbox.on('ready', () => {
  console.log('Sandbox is ready for execution')
})

sandbox.on('error', (error) => {
  console.error('Sandbox error:', error)
})

sandbox.on('destroyed', () => {
  console.log('Sandbox has been destroyed')
})

// Connection events
sandbox.on('connected', () => {
  console.log('Connected to sandbox')
})

sandbox.on('disconnected', () => {
  console.log('Disconnected from sandbox')
})

sandbox.on('reconnecting', () => {
  console.log('Attempting to reconnect...')
})
```

### Status Monitoring

[Section titled “Status Monitoring”](#status-monitoring)

```
// Check sandbox status
const status = await sandbox.getStatus()
console.log('Status:', status.state) // 'creating', 'running', 'stopped', 'error'
console.log('Uptime:', status.uptimeMs)
console.log('Resource usage:', status.resources)

// Continuous monitoring
const monitor = sandbox.monitor({
  interval: 5000, // Check every 5 seconds
  metrics: ['cpu', 'memory', 'disk', 'network']
})

monitor.on('metrics', (metrics) => {
  console.log('CPU usage:', metrics.cpu.percent)
  console.log('Memory usage:', metrics.memory.usedMB)
  console.log('Disk usage:', metrics.disk.usedMB)
})

// Stop monitoring
await monitor.stop()
```

### Health Checks

[Section titled “Health Checks”](#health-checks)

```
// Built-in health check
const isHealthy = await sandbox.healthCheck()

// Custom health checks
const healthChecks = {
  python: () => sandbox.exec('python --version'),
  node: () => sandbox.exec('node --version'),
  disk: () => sandbox.exec('df -h'),
  network: () => sandbox.exec('ping -c 1 google.com')
}

async function runHealthChecks(sandbox: Sandbox) {
  const results = {}
  
  for (const [name, check] of Object.entries(healthChecks)) {
    try {
      await check()
      results[name] = 'healthy'
    } catch (error) {
      results[name] = 'unhealthy'
    }
  }
  
  return results
}
```

## Resource Management

[Section titled “Resource Management”](#resource-management)

### Resource Monitoring

[Section titled “Resource Monitoring”](#resource-monitoring)

```
// Get current resource usage
const usage = await sandbox.getResourceUsage()
console.log('CPU:', usage.cpu.percent)
console.log('Memory:', usage.memory.usedMB, '/', usage.memory.totalMB)
console.log('Disk:', usage.disk.usedMB, '/', usage.disk.totalMB)

// Set resource limits
await sandbox.setResourceLimits({
  cpuPercent: 80,
  memoryMB: 2048,
  diskMB: 5120
})

// Resource alerts
sandbox.on('resourceAlert', (alert) => {
  console.warn(`Resource alert: ${alert.type} usage is ${alert.current}%`)
  
  if (alert.type === 'memory' && alert.current > 90) {
    // Take action to free memory
    sandbox.exec('python -c "import gc; gc.collect()"')
  }
})
```

### Auto-scaling

[Section titled “Auto-scaling”](#auto-scaling)

```
// Configure auto-scaling
await sandbox.configureAutoScaling({
  enabled: true,
  metrics: {
    cpu: { threshold: 80, action: 'scale-up' },
    memory: { threshold: 85, action: 'scale-up' }
  },
  limits: {
    maxCpuCores: 8,
    maxMemoryMB: 16384
  }
})

// Manual scaling
await sandbox.scale({
  cpuCores: 4,
  memoryMB: 8192
})
```

## Persistence and State

[Section titled “Persistence and State”](#persistence-and-state)

### Persistent Storage

[Section titled “Persistent Storage”](#persistent-storage)

```
// Create sandbox with persistent volumes
const sandbox = await compute('e2b', {
  volumes: [
    {
      name: 'workspace',
      path: '/workspace',
      size: '10GB',
      persistent: true
    },
    {
      name: 'cache',
      path: '/cache',
      size: '5GB',
      persistent: false
    }
  ]
})

// Mount existing volume
const sandbox2 = await compute('e2b', {
  volumes: [
    {
      name: 'workspace', // Same volume as above
      path: '/workspace',
      mountExisting: true
    }
  ]
})
```

### State Snapshots

[Section titled “State Snapshots”](#state-snapshots)

```
// Create a snapshot of current state
const snapshotId = await sandbox.createSnapshot({
  name: 'before-deployment',
  description: 'State before deploying new version'
})

// List snapshots
const snapshots = await sandbox.listSnapshots()

// Restore from snapshot
await sandbox.restoreSnapshot(snapshotId)

// Delete snapshot
await sandbox.deleteSnapshot(snapshotId)
```

### State Persistence

[Section titled “State Persistence”](#state-persistence)

```
// Save sandbox state
const state = await sandbox.saveState()

// Create new sandbox from saved state
const newSandbox = await compute('e2b', {
  restoreFrom: state
})

// Export/import state
const stateData = await sandbox.exportState()
const importedSandbox = await compute('e2b', {
  importState: stateData
})
```

## Sandbox Operations

[Section titled “Sandbox Operations”](#sandbox-operations)

### Reset and Restart

[Section titled “Reset and Restart”](#reset-and-restart)

```
// Soft reset (clear processes, keep files)
await sandbox.reset()

// Hard reset (restore to initial state)
await sandbox.reset({ hard: true })

// Restart sandbox
await sandbox.restart()

// Restart with new configuration
await sandbox.restart({
  template: 'python:3.11',
  env: { DEBUG: 'true' }
})
```

### Cloning

[Section titled “Cloning”](#cloning)

```
// Clone existing sandbox
const clonedSandbox = await sandbox.clone()

// Clone with modifications
const clonedSandbox = await sandbox.clone({
  template: 'different-template',
  env: { NODE_ENV: 'production' }
})

// Clone to different provider
const clonedSandbox = await sandbox.clone({
  provider: 'vercel',
  template: 'nodejs18.x'
})
```

### Migration

[Section titled “Migration”](#migration)

```
// Migrate to different provider
const migratedSandbox = await sandbox.migrate('modal', {
  template: 'python-gpu',
  preserveFiles: true,
  preserveEnv: true
})

// Migration with custom mapping
const migratedSandbox = await sandbox.migrate('vercel', {
  templateMapping: {
    'python:3.11': 'python3.11.x'
  },
  envMapping: {
    'DEBUG': 'VERCEL_DEBUG'
  }
})
```

## Multi-Sandbox Coordination

[Section titled “Multi-Sandbox Coordination”](#multi-sandbox-coordination)

### Sandbox Groups

[Section titled “Sandbox Groups”](#sandbox-groups)

```
// Create a group of related sandboxes
class SandboxGroup {
  private sandboxes: Map<string, Sandbox> = new Map()

async add(name: string, provider: string, config?: any) {
    const sandbox = await compute(provider, config)
    this.sandboxes.set(name, sandbox)
    return sandbox
  }

async broadcast(command: string) {
    const results = new Map()
    
    for (const [name, sandbox] of this.sandboxes) {
      try {
        const result = await sandbox.exec(command)
        results.set(name, result)
      } catch (error) {
        results.set(name, { error: error.message })
      }
    }
    
    return results
  }

async destroyAll() {
    await Promise.all(
      Array.from(this.sandboxes.values()).map(sb => sb.destroy())
    )
  }
}

// Usage
const group = new SandboxGroup()
await group.add('web', 'vercel', { template: 'nextjs' })
await group.add('api', 'e2b', { template: 'nodejs' })
await group.add('ml', 'modal', { template: 'pytorch' })

// Execute command on all sandboxes
const results = await group.broadcast('npm --version')
```

### Inter-Sandbox Communication

[Section titled “Inter-Sandbox Communication”](#inter-sandbox-communication)

```
// Set up communication between sandboxes
const webSandbox = await compute('vercel')
const apiSandbox = await compute('e2b')

// Create shared network
const network = await createSharedNetwork([webSandbox, apiSandbox])

// Configure service discovery
await webSandbox.setEnv('API_URL', network.getServiceUrl('api'))
await apiSandbox.setEnv('SERVICE_NAME', 'api')

// Set up message passing
const messageQueue = new MessageQueue()
await messageQueue.connect([webSandbox, apiSandbox])

// Send message from web to api
await messageQueue.send('web', 'api', { action: 'process-data' })
```

## Error Handling and Recovery

[Section titled “Error Handling and Recovery”](#error-handling-and-recovery)

### Error Recovery

[Section titled “Error Recovery”](#error-recovery)

```
// Automatic error recovery
sandbox.on('error', async (error) => {
  console.error('Sandbox error:', error)
  
  if (error.type === 'connection-lost') {
    // Attempt reconnection
    await sandbox.reconnect()
  } else if (error.type === 'out-of-memory') {
    // Restart with more memory
    await sandbox.restart({
      resources: { memoryMB: sandbox.config.resources.memoryMB * 2 }
    })
  } else if (error.type === 'corruption') {
    // Restore from last snapshot
    const snapshots = await sandbox.listSnapshots()
    if (snapshots.length > 0) {
      await sandbox.restoreSnapshot(snapshots[0].id)
    }
  }
})

// Circuit breaker pattern
class SandboxCircuitBreaker {
  private failures = 0
  private lastFailure = 0
  private state = 'closed' // closed, open, half-open

async execute(operation: () => Promise<any>) {
    if (this.state === 'open') {
      if (Date.now() - this.lastFailure < 60000) {
        throw new Error('Circuit breaker is open')
      }
      this.state = 'half-open'
    }

try {
      const result = await operation()
      this.onSuccess()
      return result
    } catch (error) {
      this.onFailure()
      throw error
    }
  }

private onSuccess() {
    this.failures = 0
    this.state = 'closed'
  }

private onFailure() {
    this.failures++
    this.lastFailure = Date.now()
    
    if (this.failures >= 5) {
      this.state = 'open'
    }
  }
}
```

### Graceful Shutdown

[Section titled “Graceful Shutdown”](#graceful-shutdown)

```
// Graceful shutdown handler
process.on('SIGINT', async () => {
  console.log('Shutting down gracefully...')
  
  // Stop accepting new requests
  // Finish current operations
  
  // Clean up sandboxes
  const activeSandboxes = await listActiveSandboxes()
  await Promise.all(
    activeSandboxes.map(async (sandbox) => {
      try {
        // Save important state
        await sandbox.createSnapshot({ name: 'shutdown-backup' })
        
        // Clean shutdown
        await sandbox.destroy({ graceful: true, timeoutMs: 30000 })
      } catch (error) {
        console.error('Error during sandbox cleanup:', error)
      }
    })
  )
  
  process.exit(0)
})
```

## Performance Optimization

[Section titled “Performance Optimization”](#performance-optimization)

### Connection Pooling

[Section titled “Connection Pooling”](#connection-pooling)

```
// Implement connection pooling
class SandboxPool {
  private pools = new Map<string, Sandbox[]>()
  private maxSize = 10
  private minSize = 2

async acquire(provider: string, config?: any): Promise<Sandbox> {
    const key = this.getPoolKey(provider, config)
    const pool = this.pools.get(key) || []
    
    if (pool.length > 0) {
      return pool.pop()!
    }
    
    return await compute(provider, config)
  }

async release(sandbox: Sandbox, provider: string, config?: any) {
    const key = this.getPoolKey(provider, config)
    const pool = this.pools.get(key) || []
    
    if (pool.length < this.maxSize) {
      // Reset sandbox state before returning to pool
      await sandbox.reset()
      pool.push(sandbox)
      this.pools.set(key, pool)
    } else {
      await sandbox.destroy()
    }
  }

private getPoolKey(provider: string, config?: any): string {
    return `${provider}-${JSON.stringify(config || {})}`
  }
}
```

### Caching and Reuse

[Section titled “Caching and Reuse”](#caching-and-reuse)

```
// Cache sandbox configurations
const configCache = new Map()

async function createOptimizedSandbox(provider: string, config: any) {
  const cacheKey = `${provider}-${JSON.stringify(config)}`
  
  if (configCache.has(cacheKey)) {
    const cached = configCache.get(cacheKey)
    // Clone from cached sandbox
    return await cached.clone()
  }
  
  const sandbox = await compute(provider, config)
  configCache.set(cacheKey, sandbox)
  return sandbox
}
```

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Resource Cleanup**: Always call `destroy()` when done with a sandbox
2. **Error Handling**: Implement proper error handling and recovery
3. **Resource Monitoring**: Monitor resource usage to prevent overconsumption
4. **State Management**: Use snapshots for important state preservation
5. **Connection Pooling**: Reuse sandboxes when possible to improve performance
6. **Graceful Shutdown**: Implement proper cleanup during application shutdown
7. **Security**: Isolate untrusted code in separate sandboxes
8. **Monitoring**: Set up proper logging and monitoring for production use

## Related Documentation

[Section titled “Related Documentation”](#related-documentation)

* [Overview](./overview.md) - SDK architecture and concepts
* [Configuration](./configuration.md) - Sandbox configuration options
* [Code Execution](./code-execution.md) - Running code in sandboxes
* [Filesystem](./filesystem.md) - File operations and management
* [Providers](../providers/) - Provider-specific management features

# Terminal

ComputeSDK provides full terminal access for interactive shell sessions, command execution, and process management. Create persistent terminal sessions, handle input/output streams, and manage multiple shell environments.

## Quick Start

[Section titled “Quick Start”](#quick-start)

```
import { compute } from 'computesdk'

const sandbox = await compute('e2b')

// Create a terminal session
const terminal = await sandbox.createTerminal()

// Execute commands interactively
await terminal.write('python --version\n')
const output = await terminal.read()
console.log(output)

// Close the terminal
await terminal.close()
```

## Creating Terminal Sessions

[Section titled “Creating Terminal Sessions”](#creating-terminal-sessions)

### Basic Terminal Creation

[Section titled “Basic Terminal Creation”](#basic-terminal-creation)

```
// Create default terminal (usually bash)
const terminal = await sandbox.createTerminal()

// Create with specific shell
const bashTerminal = await sandbox.createTerminal({
  shell: '/bin/bash'
})

const zshTerminal = await sandbox.createTerminal({
  shell: '/bin/zsh',
  args: ['--login']
})

// Create with custom environment
const terminal = await sandbox.createTerminal({
  env: {
    NODE_ENV: 'development',
    DEBUG: 'true',
    PATH: '/custom/bin:' + process.env.PATH
  }
})

// Create with specific working directory
const terminal = await sandbox.createTerminal({
  cwd: '/app/src',
  shell: '/bin/bash'
})
```

### Terminal Configuration

[Section titled “Terminal Configuration”](#terminal-configuration)

```
interface TerminalConfig {
  // Shell to use
  shell?: string
  
  // Shell arguments
  args?: string[]
  
  // Working directory
  cwd?: string
  
  // Environment variables
  env?: Record<string, string>
  
  // Terminal size
  cols?: number
  rows?: number
  
  // Encoding
  encoding?: 'utf8' | 'ascii' | 'binary'
  
  // Timeout for operations
  timeout?: number
  
  // Keep alive settings
  keepAlive?: boolean
  idleTimeout?: number
}

const terminal = await sandbox.createTerminal({
  shell: '/bin/bash',
  cols: 120,
  rows: 30,
  env: { TERM: 'xterm-256color' },
  timeout: 30000,
  keepAlive: true
})
```

## Interactive Terminal Operations

[Section titled “Interactive Terminal Operations”](#interactive-terminal-operations)

### Writing to Terminal

[Section titled “Writing to Terminal”](#writing-to-terminal)

```
// Execute a command
await terminal.write('ls -la\n')

// Send input to interactive program
await terminal.write('python\n')
await terminal.write('print("Hello, World!")\n')
await terminal.write('exit()\n')

// Send special characters
await terminal.write('\u0003') // Ctrl+C
await terminal.write('\u0004') // Ctrl+D
await terminal.write('\u001b[A') // Up arrow

// Send multiple commands
await terminal.writeLines([
  'cd /app',
  'npm install',
  'npm start'
])
```

### Reading from Terminal

[Section titled “Reading from Terminal”](#reading-from-terminal)

```
// Read all available output
const output = await terminal.read()
console.log(output)

// Read with timeout
const output = await terminal.read({ timeout: 5000 })

// Read until specific pattern
const output = await terminal.readUntil('$ ') // Read until shell prompt

// Read line by line
const line = await terminal.readLine()

// Read specific number of bytes
const chunk = await terminal.read({ bytes: 1024 })
```

### Streaming Operations

[Section titled “Streaming Operations”](#streaming-operations)

```
// Stream terminal output
terminal.onData((data) => {
  console.log('Terminal output:', data)
})

// Handle specific output patterns
terminal.onData((data) => {
  if (data.includes('Error:')) {
    console.error('Command failed:', data)
  } else if (data.includes('Warning:')) {
    console.warn('Warning detected:', data)
  }
})

// Stream input to terminal
const inputStream = new PassThrough()
inputStream.pipe(terminal.stdin)

// Write to input stream
inputStream.write('echo "Hello"\n')
```

## Advanced Terminal Features

[Section titled “Advanced Terminal Features”](#advanced-terminal-features)

### Multiple Terminal Sessions

[Section titled “Multiple Terminal Sessions”](#multiple-terminal-sessions)

```
// Create multiple terminals
const terminals = await Promise.all([
  sandbox.createTerminal({ name: 'main' }),
  sandbox.createTerminal({ name: 'logs' }),
  sandbox.createTerminal({ name: 'tests' })
])

// Run different tasks in each terminal
terminals[0].write('npm run dev\n')     // Development server
terminals[1].write('tail -f app.log\n') // Log monitoring
terminals[2].write('npm test -- --watch\n') // Test watcher

// Switch between terminals
const activeTerminal = terminals[0]
await activeTerminal.focus()
```

### Terminal Multiplexing

[Section titled “Terminal Multiplexing”](#terminal-multiplexing)

```
// Create tmux session
const tmux = await sandbox.createTmux({
  sessionName: 'development'
})

// Create multiple panes
await tmux.newWindow('editor')
await tmux.newWindow('server')
await tmux.newWindow('logs')

// Send commands to specific windows
await tmux.sendCommand('editor', 'vim src/app.js')
await tmux.sendCommand('server', 'npm start')
await tmux.sendCommand('logs', 'tail -f /var/log/app.log')

// Switch between windows
await tmux.selectWindow('editor')
```

### Screen Sessions

[Section titled “Screen Sessions”](#screen-sessions)

```
// Create screen session
const screen = await sandbox.createScreen({
  sessionName: 'background-tasks'
})

// Create multiple screens
await screen.newScreen('worker1')
await screen.newScreen('worker2')

// Run background tasks
await screen.sendCommand('worker1', 'python worker.py')
await screen.sendCommand('worker2', 'node background-job.js')

// Detach and reattach
await screen.detach()
const sessions = await screen.list()
await screen.reattach('background-tasks')
```

## Process Management

[Section titled “Process Management”](#process-management)

### Running Background Processes

[Section titled “Running Background Processes”](#running-background-processes)

```
// Start process in background
const process = await terminal.startBackground('python server.py')

// Check if process is running
const isRunning = await process.isAlive()
console.log('Process running:', isRunning)

// Get process information
const info = await process.getInfo()
console.log('PID:', info.pid)
console.log('CPU usage:', info.cpu)
console.log('Memory usage:', info.memory)

// Stop the process
await process.kill('SIGTERM')
```

### Process Monitoring

[Section titled “Process Monitoring”](#process-monitoring)

```
// Monitor all processes
const monitor = terminal.createProcessMonitor()

monitor.on('processStart', (proc) => {
  console.log('Process started:', proc.pid, proc.command)
})

monitor.on('processExit', (proc) => {
  console.log('Process exited:', proc.pid, 'code:', proc.exitCode)
})

monitor.on('processError', (proc, error) => {
  console.error('Process error:', proc.pid, error)
})

// Monitor specific process
const processMonitor = await terminal.monitorProcess(1234)
processMonitor.on('stats', (stats) => {
  console.log('CPU:', stats.cpu, 'Memory:', stats.memory)
})
```

### Job Control

[Section titled “Job Control”](#job-control)

```
// List running jobs
const jobs = await terminal.getJobs()
jobs.forEach(job => {
  console.log(`Job ${job.id}: ${job.command} [${job.status}]`)
})

// Send job to background
await terminal.background(jobId)

// Bring job to foreground
await terminal.foreground(jobId)

// Kill job
await terminal.killJob(jobId)

// Suspend/resume job
await terminal.suspend(jobId)
await terminal.resume(jobId)
```

## Command Execution Patterns

[Section titled “Command Execution Patterns”](#command-execution-patterns)

### Execute and Wait

[Section titled “Execute and Wait”](#execute-and-wait)

```
// Execute command and wait for completion
const result = await terminal.exec('npm install')
console.log('Exit code:', result.exitCode)
console.log('Output:', result.output)

// Execute with timeout
const result = await terminal.exec('long-running-command', {
  timeout: 60000
})

// Execute multiple commands sequentially
const results = await terminal.execSequence([
  'git pull',
  'npm install',
  'npm run build',
  'npm test'
])
```

### Interactive Command Handling

[Section titled “Interactive Command Handling”](#interactive-command-handling)

```
// Handle interactive prompts
await terminal.write('npm init\n')

// Respond to prompts
await terminal.expectPrompt('name:')
await terminal.write('my-package\n')

await terminal.expectPrompt('version:')
await terminal.write('1.0.0\n')

await terminal.expectPrompt('description:')
await terminal.write('My awesome package\n')

// Automated interactive session
const automation = terminal.createAutomation()
automation.expect('Password:').respond('secret123')
automation.expect('Continue? (y/n)').respond('y')
automation.expect('$ ').complete()

await terminal.write('sudo apt update\n')
await automation.run()
```

### Command Pipelining

[Section titled “Command Pipelining”](#command-pipelining)

```
// Create command pipeline
const pipeline = terminal.createPipeline()

pipeline
  .command('cat /var/log/app.log')
  .pipe('grep ERROR')
  .pipe('tail -10')
  .pipe('sort')

const result = await pipeline.execute()
console.log('Pipeline output:', result.output)

// Complex pipeline with error handling
const pipeline = terminal.createPipeline()
  .command('find /app -name "*.js"')
  .pipe('xargs grep -l "TODO"')
  .onError((error, command) => {
    console.error(`Command failed: ${command}`, error)
    return 'continue' // or 'stop'
  })

await pipeline.execute()
```

## Terminal UI Features

[Section titled “Terminal UI Features”](#terminal-ui-features)

### Cursor and Screen Control

[Section titled “Cursor and Screen Control”](#cursor-and-screen-control)

```
// Move cursor
await terminal.moveCursor(10, 5) // column 10, row 5
await terminal.moveCursorUp(3)
await terminal.moveCursorDown(2)
await terminal.moveCursorLeft(5)
await terminal.moveCursorRight(5)

// Clear screen operations
await terminal.clearScreen()
await terminal.clearLine()
await terminal.clearFromCursor()
await terminal.clearToCursor()

// Scroll operations
await terminal.scrollUp(5)
await terminal.scrollDown(3)
```

### Text Formatting

[Section titled “Text Formatting”](#text-formatting)

```
// Set text colors and styles
await terminal.setForegroundColor('red')
await terminal.setBackgroundColor('yellow')
await terminal.setBold(true)
await terminal.setUnderline(true)

// Write formatted text
await terminal.writeFormatted('Error: ', { color: 'red', bold: true })
await terminal.writeFormatted('Operation failed\n', { color: 'white' })

// Reset formatting
await terminal.resetFormat()
```

### Terminal Size Management

[Section titled “Terminal Size Management”](#terminal-size-management)

```
// Get current terminal size
const size = await terminal.getSize()
console.log(`Terminal size: ${size.cols}x${size.rows}`)

// Resize terminal
await terminal.resize(120, 40)

// Handle resize events
terminal.on('resize', (size) => {
  console.log(`Terminal resized to: ${size.cols}x${size.rows}`)
})

// Fit content to terminal
await terminal.fitToContent()
```

## Session Management

[Section titled “Session Management”](#session-management)

### Session Persistence

[Section titled “Session Persistence”](#session-persistence)

```
// Create persistent session
const session = await sandbox.createTerminalSession({
  persistent: true,
  sessionId: 'my-dev-session'
})

// Save session state
await session.save()

// Restore session later
const restoredSession = await sandbox.restoreTerminalSession('my-dev-session')

// List saved sessions
const sessions = await sandbox.listTerminalSessions()
```

### Session Sharing

[Section titled “Session Sharing”](#session-sharing)

```
// Create shareable session
const session = await sandbox.createTerminalSession({
  shareable: true,
  permissions: ['read', 'write']
})

// Get session URL for sharing
const shareUrl = await session.getShareUrl()

// Connect to shared session
const sharedSession = await sandbox.connectToSharedSession(shareUrl)

// Control session permissions
await session.setPermissions('user123', ['read'])
await session.revokeAccess('user456')
```

### Session Recording

[Section titled “Session Recording”](#session-recording)

```
// Start recording session
const recording = await terminal.startRecording({
  format: 'asciicast', // or 'text', 'html'
  includeTimings: true
})

// ... perform terminal operations ...

// Stop recording and save
const recordingData = await recording.stop()
await sandbox.writeFile('/recordings/session.cast', recordingData)

// Replay recording
const player = await terminal.createPlayer()
await player.load('/recordings/session.cast')
await player.play()
```

## Error Handling

[Section titled “Error Handling”](#error-handling)

### Terminal Error Management

[Section titled “Terminal Error Management”](#terminal-error-management)

```
// Handle terminal errors
terminal.on('error', (error) => {
  console.error('Terminal error:', error.message)
  
  if (error.code === 'CONNECTION_LOST') {
    // Attempt reconnection
    terminal.reconnect()
  } else if (error.code === 'COMMAND_TIMEOUT') {
    // Kill hanging process
    terminal.interrupt()
  }
})

// Graceful error recovery
async function executeWithRetry(terminal: Terminal, command: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await terminal.exec(command)
    } catch (error) {
      if (i === maxRetries - 1) throw error
      
      console.log(`Attempt ${i + 1} failed, retrying...`)
      await terminal.reset()
      await new Promise(resolve => setTimeout(resolve, 1000))
    }
  }
}
```

### Connection Management

[Section titled “Connection Management”](#connection-management)

```
// Handle connection issues
terminal.on('disconnect', () => {
  console.log('Terminal disconnected')
})

terminal.on('reconnect', () => {
  console.log('Terminal reconnected')
})

// Configure automatic reconnection
const terminal = await sandbox.createTerminal({
  reconnect: {
    enabled: true,
    maxAttempts: 5,
    delay: 1000,
    backoff: 'exponential'
  }
})

// Manual reconnection
if (!terminal.isConnected()) {
  await terminal.reconnect()
}
```

## Performance Optimization

[Section titled “Performance Optimization”](#performance-optimization)

### Terminal Buffering

[Section titled “Terminal Buffering”](#terminal-buffering)

```
// Configure output buffering
const terminal = await sandbox.createTerminal({
  buffering: {
    enabled: true,
    size: 8192,        // Buffer size in bytes
    flushInterval: 100  // Flush every 100ms
  }
})

// Manual buffer control
await terminal.flushBuffer()
await terminal.clearBuffer()
```

### Batch Operations

[Section titled “Batch Operations”](#batch-operations)

```
// Batch multiple commands
const batch = terminal.createBatch()
batch.add('cd /app')
batch.add('export NODE_ENV=production')
batch.add('npm start')

const results = await batch.execute()

// Parallel command execution in multiple terminals
const commands = [
  'npm run lint',
  'npm run test',
  'npm run build'
]

const results = await Promise.all(
  commands.map(cmd => {
    const terminal = await sandbox.createTerminal()
    return terminal.exec(cmd)
  })
)
```

## Integration Examples

[Section titled “Integration Examples”](#integration-examples)

### Web-based Terminal

[Section titled “Web-based Terminal”](#web-based-terminal)

```
// WebSocket-based terminal
io.on('connection', (socket) => {
  let terminal: Terminal
  
  socket.on('create-terminal', async (config) => {
    terminal = await sandbox.createTerminal(config)
    
    terminal.onData((data) => {
      socket.emit('terminal-output', data)
    })
    
    socket.emit('terminal-ready')
  })
  
  socket.on('terminal-input', (data) => {
    if (terminal) {
      terminal.write(data)
    }
  })
  
  socket.on('resize', (size) => {
    if (terminal) {
      terminal.resize(size.cols, size.rows)
    }
  })
  
  socket.on('disconnect', () => {
    if (terminal) {
      terminal.close()
    }
  })
})
```

### Command-line Interface

[Section titled “Command-line Interface”](#command-line-interface)

```
// CLI tool using terminal
class CLI {
  private terminal: Terminal
  
  constructor(terminal: Terminal) {
    this.terminal = terminal
  }
  
  async run() {
    console.log('Welcome to the interactive CLI')
    
    while (true) {
      const command = await this.prompt('> ')
      
      if (command === 'exit') {
        break
      }
      
      try {
        const result = await this.terminal.exec(command)
        console.log(result.output)
      } catch (error) {
        console.error('Error:', error.message)
      }
    }
  }
  
  async prompt(text: string): Promise<string> {
    return new Promise((resolve) => {
      process.stdout.write(text)
      process.stdin.once('data', (data) => {
        resolve(data.toString().trim())
      })
    })
  }
}
```

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Resource Management**: Always close terminals when done to free resources
2. **Error Handling**: Implement proper error handling and recovery mechanisms
3. **Session Management**: Use persistent sessions for long-running operations
4. **Security**: Validate and sanitize all user inputs before execution
5. **Performance**: Use buffering and batch operations for better performance
6. **Monitoring**: Monitor terminal sessions for errors and resource usage
7. **Cleanup**: Implement proper cleanup procedures for background processes
8. **User Experience**: Provide responsive feedback for terminal operations

## Security Considerations

[Section titled “Security Considerations”](#security-considerations)

1. **Input Validation**: Always validate and sanitize terminal inputs
2. **Command Injection**: Prevent command injection attacks
3. **Access Control**: Implement proper access controls for shared sessions
4. **Resource Limits**: Set appropriate limits on terminal resources
5. **Audit Logging**: Log all terminal activities for security auditing
6. **Session Isolation**: Ensure proper isolation between terminal sessions

## Related Documentation

[Section titled “Related Documentation”](#related-documentation)

* [Overview](./overview.md) - SDK architecture and concepts
* [Code Execution](./code-execution.md) - Running code and commands
* [Sandbox Management](./sandbox-management.md) - Managing sandbox lifecycle
* [Filesystem](./filesystem.md) - File operations and management
* [Configuration](./configuration.md) - Terminal configuration options

# UI Package

The `@computesdk/ui` package provides React components and utilities for integrating ComputeSDK into your frontend applications. It offers both UI components for user interaction and headless hooks for building custom interfaces.

## Installation

[Section titled “Installation”](#installation)

```
npm install @computesdk/ui
# or
pnpm add @computesdk/ui
# or
yarn add @computesdk/ui
```

## Quick Start

[Section titled “Quick Start”](#quick-start)

```
import { ComputeProvider, Terminal } from '@computesdk/ui'

export default function App() {
  return (
    <ComputeProvider provider="e2b" apiKey="your-api-key">
      <Terminal />
    </ComputeProvider>
  )
}
```

## Core Components

[Section titled “Core Components”](#core-components)

### ComputeProvider

[Section titled “ComputeProvider”](#computeprovider)

The root provider component that manages the ComputeSDK instance and provides context to child components.

```
import { ComputeProvider } from '@computesdk/ui'

interface ComputeProviderProps {
  provider: 'e2b' | 'vercel' | 'codesandbox' | 'blaxel' | 'daytona' | 'modal'
  apiKey?: string
  config?: ComputeConfig
  children: React.ReactNode
}

function App() {
  return (
    <ComputeProvider 
      provider="e2b" 
      apiKey={process.env.E2B_API_KEY}
      config={{
        template: 'base',
        metadata: { project: 'my-app' }
      }}
    >
      <YourApp />
    </ComputeProvider>
  )
}
```

### Terminal

[Section titled “Terminal”](#terminal)

Interactive terminal component with full shell access.

```
import { Terminal } from '@computesdk/ui'

function CodeEditor() {
  return (
    <div className="h-96">
      <Terminal 
        onCommand={(command) => console.log('Executed:', command)}
        onOutput={(output) => console.log('Output:', output)}
        className="h-full"
      />
    </div>
  )
}
```

#### Terminal Props

[Section titled “Terminal Props”](#terminal-props)

```
interface TerminalProps {
  onCommand?: (command: string) => void
  onOutput?: (output: string) => void
  onError?: (error: string) => void
  className?: string
  placeholder?: string
  disabled?: boolean
  autoFocus?: boolean
}
```

### FileExplorer

[Section titled “FileExplorer”](#fileexplorer)

File tree component for browsing and managing sandbox files.

```
import { FileExplorer } from '@computesdk/ui'

function IDE() {
  return (
    <div className="flex h-screen">
      <div className="w-64 border-r">
        <FileExplorer 
          onFileSelect={(path) => console.log('Selected:', path)}
          onFileCreate={(path) => console.log('Created:', path)}
          onFileDelete={(path) => console.log('Deleted:', path)}
        />
      </div>
      <div className="flex-1">
        {/* Code editor */}
      </div>
    </div>
  )
}
```

#### FileExplorer Props

[Section titled “FileExplorer Props”](#fileexplorer-props)

```
interface FileExplorerProps {
  onFileSelect?: (path: string) => void
  onFileCreate?: (path: string) => void
  onFileDelete?: (path: string) => void
  onFolderToggle?: (path: string, expanded: boolean) => void
  allowCreate?: boolean
  allowDelete?: boolean
  className?: string
}
```

### CodeRunner

[Section titled “CodeRunner”](#coderunner)

Component for executing code with output display.

```
import { CodeRunner } from '@computesdk/ui'

function Playground() {
  return (
    <CodeRunner
      language="python"
      initialCode="print('Hello, World!')"
      onExecute={(code) => console.log('Executing:', code)}
      onResult={(result) => console.log('Result:', result)}
      showLineNumbers
      theme="dark"
    />
  )
}
```

#### CodeRunner Props

[Section titled “CodeRunner Props”](#coderunner-props)

```
interface CodeRunnerProps {
  language?: string
  initialCode?: string
  onExecute?: (code: string) => void
  onResult?: (result: ExecutionResult) => void
  showLineNumbers?: boolean
  theme?: 'light' | 'dark'
  className?: string
  readOnly?: boolean
}
```

## Hooks

[Section titled “Hooks”](#hooks)

### useCompute

[Section titled “useCompute”](#usecompute)

Core hook for accessing the ComputeSDK instance.

```
import { useCompute } from '@computesdk/ui'

function CustomComponent() {
  const { 
    compute,
    connected,
    connecting,
    error,
    connect,
    disconnect
  } = useCompute()

React.useEffect(() => {
    if (!connected) {
      connect()
    }
  }, [connected, connect])

if (connecting) return <div>Connecting...</div>
  if (error) return <div>Error: {error.message}</div>

return (
    <button onClick={() => compute.exec('ls -la')}>
      List Files
    </button>
  )
}
```

### useTerminal

[Section titled “useTerminal”](#useterminal)

Hook for terminal functionality without the UI component.

```
import { useTerminal } from '@computesdk/ui'

function CustomTerminal() {
  const {
    output,
    input,
    setInput,
    execute,
    clear,
    history
  } = useTerminal()

const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault()
    execute(input)
    setInput('')
  }

return (
    <div>
      <pre>{output}</pre>
      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Enter command..."
        />
      </form>
    </div>
  )
}
```

### useFileSystem

[Section titled “useFileSystem”](#usefilesystem)

Hook for file operations.

```
import { useFileSystem } from '@computesdk/ui'

function FileManager() {
  const {
    files,
    currentPath,
    readFile,
    writeFile,
    deleteFile,
    createFolder,
    navigate
  } = useFileSystem()

const handleFileRead = async (path: string) => {
    const content = await readFile(path)
    console.log(content)
  }

return (
    <div>
      <div>Current: {currentPath}</div>
      {files.map(file => (
        <div key={file.path}>
          <span onClick={() => handleFileRead(file.path)}>
            {file.name}
          </span>
        </div>
      ))}
    </div>
  )
}
```

### useCodeExecution

[Section titled “useCodeExecution”](#usecodeexecution)

Hook for running code with execution state management.

```
import { useCodeExecution } from '@computesdk/ui'

function CodePlayground() {
  const {
    execute,
    result,
    loading,
    error,
    history
  } = useCodeExecution()

const runCode = async () => {
    await execute('python', 'print("Hello from Python!")')
  }

return (
    <div>
      <button onClick={runCode} disabled={loading}>
        {loading ? 'Running...' : 'Run Code'}
      </button>
      {result && (
        <pre>{result.stdout}</pre>
      )}
      {error && (
        <div style={{ color: 'red' }}>{error.message}</div>
      )}
    </div>
  )
}
```

## TypeScript Interfaces

[Section titled “TypeScript Interfaces”](#typescript-interfaces)

```
interface ComputeConfig {
  template?: string
  metadata?: Record<string, any>
  timeoutMs?: number
  keepAlive?: boolean
}

interface ExecutionResult {
  stdout: string
  stderr: string
  exitCode: number
  executionTime: number
}

interface FileSystemItem {
  name: string
  path: string
  type: 'file' | 'directory'
  size?: number
  modified?: Date
}

interface TerminalSession {
  id: string
  output: string[]
  history: string[]
  workingDirectory: string
}
```

## Styling

[Section titled “Styling”](#styling)

### Default Styles

[Section titled “Default Styles”](#default-styles)

The UI components come with minimal default styling. Import the base styles:

```
import '@computesdk/ui/styles.css'
```

### Custom Styling

[Section titled “Custom Styling”](#custom-styling)

All components accept `className` props for custom styling:

```
<Terminal 
  className="border rounded-lg p-4 bg-black text-green-400 font-mono"
/>

<FileExplorer 
  className="bg-gray-100 dark:bg-gray-800"
/>
```

### Theme Support

[Section titled “Theme Support”](#theme-support)

Components support light/dark themes:

```
<ComputeProvider theme="dark">
  <Terminal />
</ComputeProvider>
```

## Error Handling

[Section titled “Error Handling”](#error-handling)

```
import { ComputeErrorBoundary } from '@computesdk/ui'

function App() {
  return (
    <ComputeErrorBoundary
      fallback={({ error, retry }) => (
        <div>
          <h2>Something went wrong</h2>
          <p>{error.message}</p>
          <button onClick={retry}>Try Again</button>
        </div>
      )}
    >
      <ComputeProvider provider="e2b">
        <YourApp />
      </ComputeProvider>
    </ComputeErrorBoundary>
  )
}
```

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Provider Placement**: Place `ComputeProvider` at the root of your compute-enabled components
2. **Connection Management**: Use the `useCompute` hook to manage connection state
3. **Error Boundaries**: Always wrap compute components with error boundaries
4. **Resource Cleanup**: Components automatically handle cleanup on unmount
5. **Performance**: Use React.memo for components that render frequently

## Framework Integration

[Section titled “Framework Integration”](#framework-integration)

### Next.js

[Section titled “Next.js”](#nextjs)

```
// pages/_app.tsx
import { ComputeProvider } from '@computesdk/ui'
import '@computesdk/ui/styles.css'

export default function App({ Component, pageProps }) {
  return (
    <ComputeProvider provider="vercel" apiKey={process.env.VERCEL_API_KEY}>
      <Component {...pageProps} />
    </ComputeProvider>
  )
}
```

### Vite/React

[Section titled “Vite/React”](#vitereact)

```
// main.tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { ComputeProvider } from '@computesdk/ui'
import App from './App'
import '@computesdk/ui/styles.css'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ComputeProvider provider="e2b" apiKey={import.meta.env.VITE_E2B_API_KEY}>
      <App />
    </ComputeProvider>
  </StrictMode>
)
```

## Examples

[Section titled “Examples”](#examples)

Check out complete examples in our [examples directory](../../examples/):

* [Next.js Integration](../../examples/nextjs/)
* [Vite + React](../../examples/basic/)
* [Custom IDE](../../examples/ide/)

## Related Documentation

[Section titled “Related Documentation”](#related-documentation)

* [Overview](./overview.md) - SDK architecture and concepts
* [Configuration](./configuration.md) - Global configuration options
* [Code Execution](./code-execution.md) - Running code and commands
* [Providers](../providers/) - Provider-specific documentation

# Features

> Features by Compute SDK.

## All you need is compute.

Turn any compute instance into a sandbox primitive with our self-executing binaries. Deploy our lightweight sidecar containers alongside your existing infrastructure to instantly enable secure code execution without architectural changes or vendor dependencies.

![Geometric pattern](/hero-geometric.png)

* Multi-provider Support

Switch between E2B, Vercel, Daytona, Modal, CodeSandbox and more without code changes. Provider-agnostic design means no vendor lock-in.

Real-time Terminal Access

Create and manage persistent terminal sessions with WebSocket connectivity for interactive development and debugging.

Complete Filesystem Control

Full CRUD operations on files and directories with real-time file watching and change notifications across all providers.

TypeScript-Native API

Full TypeScript support with comprehensive error handling, making development safer and more productive.

Process Signal Management

Start, stop, and monitor processes with port forwarding and server readiness detection for complete process control.

JWT-Secured Endpoints

First-come-first-served authentication model with token-based access control for secure code execution environments.

One-off Command Execution

Execute commands instantly without spinning up persistent terminals for quick tasks and automated workflows.

WebSocket Communication

Low-latency bidirectional communication for real-time updates and interactive sessions with your sandbox environments.

Health Monitoring

Built-in health checks and status endpoints for reliability and observability of your code execution infrastructure.

## Ready to transform your compute infrastructure?

Turn any compute instance into a secure code execution environment. Deploy our lightweight sidecar containers and start building sandboxes in minutes.

[Get Started](/pricing) [Book a call →](https://cal.com/heygarrison)

[X  ](https://x.com/computesdk)[GitHub ](https://github.com/computesdk/computesdk)

# Compute SDK

[What's new Read the post: Announcing ComputeSDK ](/blog/announcement/)

# Embedded Compute for Your Apps

A developer-first primitive to embed compute into your app, agent, or network with the ability to connect directly from the browser.

[Get Started](https://www.computesdk.com/start/introduction/) [ GitHub](https://github.com/computesdk/computesdk)

index.jsx

```

import { createCompute } from 'computesdk';
import { provider } from '@computesdk/provider';

// Create compute instance
const compute = createCompute({ 
  defaultProvider: provider({ apiKey: process.env.PROVIDER_API_KEY }) 
});

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

// Execute code
const result = await sandbox.runCode('print("Hello World!")');
console.log(result.stdout); // "Hello World!"

// Clean up
await sandbox.destroy();
```

Introducing

# All of a sudden everyone is a coder now.

I remember scouring through the Joomla! documentation site for a website I was building when I was 13. I remember that the concepts were not the gotchas, but syntax or one little piece of information was. Every bit of detail was worth reading because you weren't sure when you would need it for recall.

On June 20, 2024 anthropic released Claude 3.5 Sonnet and the internet changed. All of a sudden an AI studio had released a model that was good enough to output code for all of us. All of a sudden everyone could be a coder. A vibe coder.

However, just like any experienced programmer can tell you. Creating something is addicting. The next million developers haven't learned to code by building Joomla, WordPress or Magento sites like me. They've learned or are learning to code by vibe coding.

Simplicity is more important than ever.

These next sets of coders don't want to fiddle with Terraform, CDK, or some vendor's docs. They don't even want to waste context window space on this. The next set of coders want to build even more complex applications and therefore need to simplify. They don't want to be forced to make "The Right Decision". They want optionality in their compute layer.

ComputeSDK is a primitive to help you build any application. To start, we're building the primitive around raw compute. We've aggregated some of the best integrations from E2B, Vercel, Fly, and Cloudflare so that you can get started quickly without needing to manage the complexity of a specific vendor.

We can't wait to see what you build.

![GS Logo](/GS.svg) ![GS Logo](/GS-dark.svg)

Garrison Snelling

CEO, ComputeSDK

<garrison@computesdk.com>

[X  ](https://x.com/computesdk)[GitHub ](https://github.com/computesdk/computesdk)

# Pricing

> Pricing by Compute SDK.

## Pricing

Secure Code Execution Made Simple

Start free with our provider-agnostic SDK, then scale with advanced features for production-ready code execution environments.

### Free

$0 forever

Perfect for getting started with code execution in isolated sandbox environments.

* Multi-provider support (E2B, Vercel, Daytona, Modal, CodeSandbox)
* Basic filesystem operations
* Command execution
* TypeScript support

[Get started today](https://buy.polar.sh/polar_cl_7kppmQMXd5cjk9iCiNv0XZkSSI1mCbCFei0JE0mLchM)

### Premium

$97 per 100k executions

Turn any compute instance into a sandbox primitive with our self-executing binaries.

* Real-time terminal access with WebSocket connectivity
* Complete filesystem control with real-time file watching
* One-off command execution without persistent terminals
* Process signal management with port forwarding
* JWT-secured endpoints with token-based access control
* Health monitoring with built-in status endpoints

[Get started today](https://buy.polar.sh/polar_cl_7kppmQMXd5cjk9iCiNv0XZkSSI1mCbCFei0JE0mLchM)

## Pricing & Usage

Have a different question and can't find the answer you're looking for?\
[Reach out](mailto:email@computesdk.com) to our support team and we'll get back to you as soon as we can.

* What does it cost?

$97 per 100,000 executions. An "execution" is any API call - file operation, terminal command, or signal.

What counts as an execution?

Every API call counts as one execution: creating a file, running a terminal command, sending a signal, or getting file status. WebSocket connections themselves don't count, only the operations you perform.

Can we use this across multiple environments?

Your subscription covers usage across all your compute environments - whether that's staging and production, or multiple providers like Vercel and Fly.

How does team usage work?

The pricing is per organization, not per user. Your whole team can use Sidekick across all your environments, sharing the execution allowance.

How do API keys work?

You'll get an API key when you sign up. Set it as an environment variable in your compute environment, and Sidekick will automatically track your usage and apply it to your account. One API key works across all your environments and providers.

What about SSH and VS Code for Web?

SSH access and VS Code for Web are coming soon as optional add-ons. These will be opt-in features since they require additional resources, but they'll integrate seamlessly with the existing API.

[X  ](https://x.com/computesdk)[GitHub ](https://github.com/computesdk/computesdk)

# Sidekick

> Sidekick by Compute SDK.

# Sidekick

$97 /month

### What’s included?

Real-time WebSocket API

Interactive terminals & file operations

Live file watching & signals

100k executions included

Works with any ComputeSDK provider

### How do we get started?

Install the CLI, run `computesdk sidekick launch` in your environment, and start developing in real-time.

### Need more executions?

Additional executions are $97 per 100k. Usage scales with your development needs.

Read the documentation and pricing details. Questions? Email us.

Sidekick

A complete cloud development environment for any ComputeSDK provider.

Turn any compute platform into an interactive workspace with real-time file operations, interactive terminals, and live file watching - delivered through one consistent API.

<!-- <dl class="mt-10 max-w-xl space-y-8 text-base/7 text-gray-600 lg:max-w-none">
              <div class="relative pl-9">
                <dt class="inline font-semibold text-gray-900">
                  <svg viewBox="0 0 20 20" fill="currentColor" data-slot="icon" aria-hidden="true" class="absolute left-1 top-1 size-5 text-green-800">
                    <path d="M5.5 17a4.5 4.5 0 0 1-1.44-8.765 4.5 4.5 0 0 1 8.302-3.046 3.5 3.5 0 0 1 4.504 4.272A4 4 0 0 1 15 17H5.5Zm3.75-2.75a.75.75 0 0 0 1.5 0V9.66l1.95 2.1a.75.75 0 1 0 1.1-1.02l-3.25-3.5a.75.75 0 0 0-1.1 0l-3.25 3.5a.75.75 0 1 0 1.1 1.02l1.95-2.1v4.59Z" clip-rule="evenodd" fill-rule="evenodd" />
                  </svg>
                  Push to deploy.
                </dt>
                <dd class="inline">Lorem ipsum, dolor sit amet consectetur adipisicing elit. Maiores impedit perferendis suscipit eaque, iste dolor cupiditate blanditiis ratione.</dd>
                </div>

</div>
              <div class="relative pl-9">
                <dt class="inline font-semibold text-gray-900">
                  <svg viewBox="0 0 20 20" fill="currentColor" data-slot="icon" aria-hidden="true" class="absolute left-1 top-1 size-5 text-green-800">
                    <path d="M10 1a4.5 4.5 0 0 0-4.5 4.5V9H5a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2v-6a2 2 0 0 0-2-2h-.5V5.5A4.5 4.5 0 0 0 10 1Zm3 8V5.5a3 3 0 1 0-6 0V9h6Z" clip-rule="evenodd" fill-rule="evenodd" />
                  </svg>
                  SSL certificates.
                </dt>
                <dd class="inline">Anim aute id magna aliqua ad ad non deserunt sunt. Qui irure qui lorem cupidatat commodo.</dd>
              </div>
              <div class="relative pl-9">
                <dt class="inline font-semibold text-gray-900">
                  <svg viewBox="0 0 20 20" fill="currentColor" data-slot="icon" aria-hidden="true" class="absolute left-1 top-1 size-5 text-green-800">
                    <path d="M4.632 3.533A2 2 0 0 1 6.577 2h6.846a2 2 0 0 1 1.945 1.533l1.976 8.234A3.489 3.489 0 0 0 16 11.5H4c-.476 0-.93.095-1.344.267l1.976-8.234Z" />
                    <path d="M4 13a2 2 0 1 0 0 4h12a2 2 0 1 0 0-4H4Zm11.24 2a.75.75 0 0 1 .75-.75H16a.75.75 0 0 1 .75.75v.01a.75.75 0 0 1-.75.75h-.01a.75.75 0 0 1-.75-.75V15Zm-2.25-.75a.75.75 0 0 0-.75.75v.01c0 .414.336.75.75.75H13a.75.75 0 0 0 .75-.75V15a.75.75 0 0 0-.75-.75h-.01Z" clip-rule="evenodd" fill-rule="evenodd" />
                  </svg>
                  Database backups.
                </dt>
                <dd class="inline">Ac tincidunt sapien vehicula erat auctor pellentesque rhoncus. Et magna sit morbi lobortis.</dd>
              </div>
            </dl> -->

### What is it?

Sidekick is a universal development layer that runs inside your compute environments. Launch it with one command, and instantly get real-time file management, interactive terminals, live file watching, and signal broadcasting - no matter if you're on Vercel, Fly, Cloudflare, or any other provider.

> Game changer: Your existing development tools can connect directly to any compute environment. No special clients, no browser limitations - just give your tools a WebSocket URL and they have full access to the VM.

## Your tools get direct VM access

The breakthrough is simple: your local development tools can connect directly to any compute environment. Your IDE, debugger, terminal, or custom scripts - they all get real-time access to the actual VM where your code runs.

* **Use your existing tools. **VS Code, IntelliJ, terminal scripts - everything works exactly like local development.
* **Real-time collaboration.** Multiple developers can connect their tools to the same environment simultaneously.
* **Build integrations easily.** Your CI/CD, monitoring, or custom tooling can connect to any environment with a simple WebSocket.
* **Debug in production.** Debug in production. Connect your debugger directly to production VMs for live troubleshooting.

```
  # Your local tools connect directly to the VM: 
  code --remote wss://prod-vm.com/ws 
  # VS Code 
  remote curl wss://staging.com/ws/files 
  # API access 
  wscat -c wss://dev.com/ws/terminal 
  # Terminal access 
  # No special clients, no proprietary protocols
```

Yes, and they're all different for each platform. SSH here, proprietary dashboard there, custom CLI somewhere else. That inconsistency slows you down and creates friction when working across multiple providers. Plus, most cloud platforms give you static deployments - you deploy, hope for the best, and debug from logs.

Sidekick gives you the same powerful, interactive development experience everywhere. One API, one workflow, unlimited compute providers.

## How it works

Inside your compute environment (Vercel, Fly, etc.) `$ sidekick launch`

Returns a WebSocket endpoint for real-time connection. `wss://your-environment.com/ws`

Now you have full development access:

* Real-time file operations
* Interactive terminal sessions
* Live file watching
* Signal broadcasting

### It works everywhere you need it

* **Production debugging.** Something broken in production? Launch Sidekick and debug directly in the live environment with full file access and terminal control.
* **Multi-provider development.** Working across Vercel, Fly, and Cloudflare? Same development experience everywhere, no context switching.
* **Cloud-native development.** Skip the "works on my machine" problem entirely. Develop where your code actually runs.
* **Team standardization.** Give your entire team the same powerful development interface, regardless of which compute provider they prefer.
* **CI/CD integration.** Build development and debugging capabilities directly into your deployment pipeline.
* **Live collaboration.** Multiple developers can connect to the same environment simultaneously for pair programming or debugging sessions.

## API Overview

Sidekick provides a comprehensive REST API with WebSocket support for real-time operations:

| Feature             | Endpoint                   | Real-time               |
| ------------------- | -------------------------- | ----------------------- |
| File Operations     | GET/POST/PUT/DELETE /files | ✅ Live updates          |
| Terminal Management | POST /terminals, /execute  | ✅ PTY sessions          |
| File Watching       | GET/POST/DELETE /watchers  | ✅ Change notifications  |
| Signal Broadcasting | POST /signals/\*           | ✅ Port & status signals |

## Pricing & Usage

#### What does it cost?

$97/month includes 100,000 executions. Additional executions are $97 per 100k. An "execution" is any API call - file operation, terminal command, or signal.

#### What counts as an execution?

#### Can we use this across multiple environments?

Your subscription covers usage across all your compute environments - whether that's staging and production, or multiple providers like Vercel and Fly.

#### How does team usage work?

The pricing is per organization, not per user. Your whole team can use Sidekick across all your environments, sharing the execution allowance.

#### How do API keys work?

#### What about SSH and VS Code for Web?

SSH access and VS Code for Web are coming soon as optional add-ons. These will be opt-in features since they require additional resources, but they'll integrate seamlessly with the existing API.

## Getting started

Ready to transform your compute environments into interactive development workspaces? Get your API key, install the CLI, and launch your first Sidekick instance in under a minute.

```

# Install the CLI 
    $ npm install -g sidekick 
    # Set your API key (get one from your dashboard) 
    $ export SIDEKICK_API_KEY=your_api_key_here 
    # Launch in your compute environment 
    $ sidekick launch 
    # Start developing in real-time 
    ✅ WebSocket API ready at wss://your-env.com/ws 
    ✅ Usage tracking enabled for your account
    
```

# Sidekick

$97 /month

### What’s included?

Real-time WebSocket API

Interactive terminals & file operations

Live file watching & signals

100k executions included

Works with any ComputeSDK provider

### How do we get started?

Install the CLI, run `computesdk sidekick launch` in your environment, and start developing in real-time.

### Need more executions?

Additional executions are $97 per 100k. Usage scales with your development needs.

Read the documentation and pricing details. Questions? Email us.

[X  ](https://x.com/computesdk)[GitHub ](https://github.com/computesdk/computesdk)

Code Executor

Code Executor

Output:

Code Executor

Server-Side Data Demo

{item.name}