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'); const server = http.createServer((req, res) => { res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ message: 'Hello from Blaxel!', timestamp: new Date().toISOString() })); }); 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> <script> export default { name: 'TodoList', data() { return { newTodo: '', todos: [ { id: 1, text: 'Learn Vue.js', completed: true }, { id: 2, text: 'Build with ComputeSDK', completed: false }, { id: 3, text: 'Deploy to CodeSandbox', completed: false } ] } }, computed: { completedCount() { return this.todos.filter(todo => todo.completed).length; } }, methods: { addTodo() { if (this.newTodo.trim()) { this.todos.push({ id: Date.now(), text: this.newTodo.trim(), completed: false }); this.newTodo = ''; } }, removeTodo(id) { this.todos = this.todos.filter(todo => todo.id !== id); } } } </script> <style scoped> .todo-app { max-width: 400px; margin: 0 auto; padding: 20px; } .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> <script> import TodoList from './components/TodoList.vue' export default { name: 'App', components: { TodoList } } </script> <style> #app { font-family: Avenir, Helvetica, Arial, sans-serif; text-align: center; color: #2c3e50; margin-top: 20px; } </style> `); 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']; const results = await Promise.all( regions.map(async (region) => { const sandbox = await compute.sandbox.create({ provider: vercel({ runtime: 'node', region: region, memory: 512 }) }); const result = await sandbox.runCode(` console.log('Region:', '${region}'); console.log('Timestamp:', new Date().toISOString()); // 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)  © 2025 ComputeSDK, Inc. All rights reserved.

# 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)  © 2025 ComputeSDK, Inc. All rights reserved.

# 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)  © 2025 ComputeSDK, Inc. All rights reserved.

# 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. Subscribe 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.  ### 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? 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. ## 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. Subscribe Read the documentation and pricing details. Questions? Email us.   [X ](https://x.com/computesdk)[GitHub ](https://github.com/computesdk/computesdk)  © 2025 ComputeSDK, Inc. All rights reserved.

Code Executor

Code Executor

Output:

Code Executor

Server-Side Data Demo

{item.name}