computesdk 1.10.0 → 1.10.2

package/README.md

@@ -1,99 +1,27 @@
-<div align="center">
-  <img src="https://www.computesdk.com/_astro/hv_main_logo_light.CpYMD9-V.svg" alt="ComputeSDK" width="300" />
-</div>
+# computesdk
 
-<div align="center">
-  <strong>A free and open-source toolkit for running other people's code in your applications.</strong>
-</div>
+The gateway SDK for running code in remote sandboxes. Zero-config auto-detection with support for E2B, Modal, Railway, Daytona, Vercel, and more.
 
-<div align="center">
-
-[![npm version](https://badge.fury.io/js/computesdk.svg)](https://badge.fury.io/js/computesdk)
-[![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue.svg)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Documentation](https://img.shields.io/badge/docs-computesdk.com-blue)](https://computesdk.com)
-
-</div>
-
----
-
-## 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 Blaxel, E2B, Vercel, or Daytona.
-
-**Why ComputeSDK?**
-- 🔄 **Provider-agnostic** - Switch between Blaxel, E2B, Vercel, Daytona, Modal, CodeSandbox and more without code changes
-- ⚡ **Zero-config mode** - Auto-detect provider from environment variables
-- 🛡️ **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:**
-- **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
-
-- 🚀 **Multi-provider support** - Blaxel, E2B, Vercel, Daytona, Modal, CodeSandbox
-- ⚡ **Zero-config mode** - Auto-detect provider from environment variables
-- 📁 **Filesystem operations** - Read, write, create directories across providers
-- 🖥️ **Terminal support** - Interactive PTY terminals with exec mode
-- ⚡ **Command execution** - Run shell commands with PTY or exec mode
-- 🔧 **Type-safe commands** - Build shell commands with `@computesdk/cmd`
-- 🛡️ **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
-
-## Get Started in 30 Seconds
+## Installation
 
 ```bash
-# Install the core SDK
 npm install computesdk
+```
 
-# Add your preferred provider
-npm install @computesdk/blaxel     # For AI-powered code execution
-npm install @computesdk/e2b        # For data science and Python
-npm install @computesdk/vercel     # For web-scale Node.js/Python
-npm install @computesdk/daytona    # For development workspaces
-npm install @computesdk/modal      # For GPU-accelerated Python workloads
-npm install @computesdk/codesandbox # For collaborative sandboxes
+## Quick Start
 
-# Frontend integration (optional)
-npm install @computesdk/ui         # React hooks and utilities
-```
+### Zero-Config Mode (Recommended)
 
-Set your environment variables and you're ready to go:
+Set your provider credentials as environment variables and ComputeSDK automatically detects and configures everything:
 
 ```bash
-export BLAXEL_API_KEY=your_api_key
-export BLAXEL_WORKSPACE=your_workspace
-# or E2B_API_KEY=your_api_key
-# or VERCEL_TOKEN=your_token
-# or DAYTONA_API_KEY=your_key
-# or MODAL_TOKEN_ID=your_token_id and MODAL_TOKEN_SECRET=your_token_secret
-# or CODESANDBOX_TOKEN=your_token
+export E2B_API_KEY=your_e2b_api_key
 ```
 
-## Quick Start
-
 ```typescript
 import { compute } from 'computesdk';
-import { blaxel } from '@computesdk/blaxel';
-
-// Set default provider
-compute.setConfig({
-  provider: blaxel({
-    apiKey: process.env.BLAXEL_API_KEY,
-    workspace: process.env.BLAXEL_WORKSPACE
-  })
-});
 
-// Create a sandbox
+// Auto-detects E2B from environment
 const sandbox = await compute.sandbox.create();
 
 // Execute code
@@ -101,385 +29,258 @@ const result = await sandbox.runCode('print("Hello World!")');
 console.log(result.stdout); // "Hello World!"
 
 // Clean up
-await compute.sandbox.destroy(sandbox.sandboxId);
+await sandbox.destroy();
 ```
 
-## Zero-Config Mode
-
-ComputeSDK can automatically detect and configure your provider from environment variables:
-
-```bash
-# Set your ComputeSDK API key
-export COMPUTESDK_API_KEY=your_computesdk_api_key
+### Explicit Configuration
 
-# Set credentials for your provider (auto-detected)
-export E2B_API_KEY=your_e2b_key
-# or export DAYTONA_API_KEY=your_daytona_key
-# or export MODAL_TOKEN_ID=xxx MODAL_TOKEN_SECRET=xxx
-```
+For more control, use `setConfig()` to explicitly configure the provider:
 
 ```typescript
 import { compute } from 'computesdk';
 
-// No provider configuration needed - auto-detected from environment!
+compute.setConfig({
+  provider: 'e2b',
+  e2b: { apiKey: 'your_api_key' }
+});
+
 const sandbox = await compute.sandbox.create();
-const result = await sandbox.runCode('print("Hello World!")');
-console.log(result.stdout);
 ```
 
-Provider detection order: E2B → Railway → Daytona → Modal → Runloop → Vercel → Cloudflare → CodeSandbox → Blaxel
+## Supported Providers
 
-You can also explicitly set the provider:
+ComputeSDK automatically detects providers based on environment variables:
 
-```bash
-export COMPUTESDK_PROVIDER=e2b
-```
+| Provider | Environment Variables | Use Cases |
+|----------|----------------------|-----------|
+| **E2B** | `E2B_API_KEY` | Data science, Python/Node.js, interactive terminals |
+| **Modal** | `MODAL_TOKEN_ID`, `MODAL_TOKEN_SECRET` | GPU computing, ML inference, Python workloads |
+| **Railway** | `RAILWAY_TOKEN` | Full-stack deployments, persistent storage |
+| **Daytona** | `DAYTONA_API_KEY` | Development workspaces, custom environments |
+| **Runloop** | `RUNLOOP_API_KEY` | Code execution, automation |
+| **Vercel** | `VERCEL_TOKEN` or `VERCEL_OIDC_TOKEN` | Serverless functions, web apps |
+| **Cloudflare** | `CLOUDFLARE_API_TOKEN` | Edge computing |
+| **CodeSandbox** | `CODESANDBOX_TOKEN` | Collaborative development |
+
+### Provider Detection Order
 
-## Provider Setup
+When using zero-config mode, ComputeSDK detects providers in this order:
 
-### Blaxel - AI-Powered Code Execution
+**E2B → Railway → Daytona → Modal → Runloop → Vercel → Cloudflare → CodeSandbox**
 
-Blaxel provides intelligent code execution with AI assistance:
+You can force a specific provider:
 
 ```bash
-export BLAXEL_API_KEY=your_blaxel_api_key_here
-export BLAXEL_WORKSPACE=your_workspace_here
+export COMPUTESDK_PROVIDER=modal
 ```
 
-```typescript
-import { compute } from 'computesdk';
-import { blaxel } from '@computesdk/blaxel';
+## API Reference
 
-compute.setConfig({ 
-  provider: blaxel({ 
-    apiKey: process.env.BLAXEL_API_KEY,
-    workspace: process.env.BLAXEL_WORKSPACE
-  }) 
-});
+### Configuration
 
-const sandbox = await compute.sandbox.create();
+#### `compute.setConfig(config)`
 
-// Execute code with AI assistance
-const result = await sandbox.runCode(`
-print("Hello from Blaxel!")
-# Your code can leverage AI capabilities
-import json
-data = {"message": "AI-powered execution"}
-print(json.dumps(data, indent=2))
-`);
+Configure the gateway with explicit provider settings.
 
-console.log(result.stdout);
+```typescript
+compute.setConfig({
+  provider: 'e2b',
+  e2b: { apiKey: 'your_api_key' }
+});
 ```
 
-### E2B - Full Development Environment
-
-E2B provides full filesystem and terminal support:
-
-```bash
-export E2B_API_KEY=e2b_your_api_key_here
-```
+**Provider-specific configs:**
 
 ```typescript
-import { compute } from 'computesdk';
-import { e2b } from '@computesdk/e2b';
-
-compute.setConfig({ 
-  provider: e2b({ apiKey: process.env.E2B_API_KEY }) 
+// E2B
+compute.setConfig({
+  provider: 'e2b',
+  e2b: { 
+    apiKey: 'e2b_xxx',
+    templateId: 'optional_template' 
+  }
 });
 
-const sandbox = await compute.sandbox.create();
+// Modal
+compute.setConfig({
+  provider: 'modal',
+  modal: { 
+    tokenId: 'ak-xxx',
+    tokenSecret: 'as-xxx'
+  }
+});
 
-// Execute Python with data science libraries
-const result = await sandbox.runCode(`
-import pandas as pd
-import numpy as np
+// Railway
+compute.setConfig({
+  provider: 'railway',
+  railway: { 
+    apiToken: 'your_token',
+    projectId: 'project_id',
+    environmentId: 'env_id'
+  }
+});
 
-data = {'A': [1, 2, 3], 'B': [4, 5, 6]}
-df = pd.DataFrame(data)
-print(df)
-print(f"Sum: {df.sum().sum()}")
-`);
+// Daytona
+compute.setConfig({
+  provider: 'daytona',
+  daytona: { apiKey: 'your_api_key' }
+});
 
-// Interactive terminal support
-const terminal = await sandbox.terminal.create({
-  command: 'bash',
-  cols: 80,
-  rows: 24
+// Vercel
+compute.setConfig({
+  provider: 'vercel',
+  vercel: { 
+    token: 'your_token',
+    teamId: 'team_xxx',
+    projectId: 'prj_xxx'
+  }
 });
 ```
 
-### Vercel - Scalable Serverless Execution
-
-Vercel provides reliable execution with filesystem support:
+### Sandbox Management
 
-```bash
-# Method 1: OIDC Token (Recommended)
-vercel env pull  # Downloads VERCEL_OIDC_TOKEN
+#### `compute.sandbox.create(options?)`
 
-# 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
-```
+Create a new sandbox.
 
 ```typescript
-import { compute } from 'computesdk';
-import { vercel } from '@computesdk/vercel';
-
-compute.setConfig({ 
-  provider: vercel({ runtime: 'node' }) 
-});
-
 const sandbox = await compute.sandbox.create();
 
-// Execute Node.js or Python
-const result = await sandbox.runCode(`
-console.log('Node.js version:', process.version);
-console.log('Hello from Vercel!');
-`);
-
-// Up to 45 minutes execution time
-// Global infrastructure deployment
+// With options
+const sandbox = await compute.sandbox.create({
+  runtime: 'python',
+  timeout: 300000, // 5 minutes
+  metadata: { userId: '123' }
+});
 ```
 
-### Daytona - Development Workspaces
+**Options:**
+- `runtime?: 'node' | 'python'` - Runtime environment (default: 'node')
+- `timeout?: number` - Timeout in milliseconds
+- `metadata?: Record<string, any>` - Custom metadata
+- `envs?: Record<string, string>` - Environment variables
 
-Daytona provides development workspace environments:
+#### `compute.sandbox.getById(sandboxId)`
 
-```bash
-export DAYTONA_API_KEY=your_daytona_api_key_here
-```
+Get an existing sandbox by ID.
 
 ```typescript
-import { compute } from 'computesdk';
-import { daytona } from '@computesdk/daytona';
-
-compute.setConfig({ 
-  provider: daytona({ apiKey: process.env.DAYTONA_API_KEY }) 
-});
-
-const sandbox = await compute.sandbox.create();
-
-// Execute in development workspace
-const result = await sandbox.runCode(`
-print('Hello from Daytona!')
-import sys
-print(f'Python version: {sys.version}')
-`);
+const sandbox = await compute.sandbox.getById('sandbox-id');
 ```
 
-## Core API
+#### `compute.sandbox.list()`
 
-### Configuration
+List all active sandboxes.
 
 ```typescript
-import { compute } from 'computesdk';
-
-// Set default provider
-compute.setConfig({ provider: myProvider });
+const sandboxes = await compute.sandbox.list();
+```
 
-// Get current config
-const config = compute.getConfig();
+### Sandbox Operations
 
-// Clear config
-compute.clearConfig();
-```
+#### `sandbox.runCode(code, runtime?)`
 
-### Sandbox Management
+Execute code in the sandbox.
 
 ```typescript
-// Create sandbox with explicit provider
-const sandbox = await compute.sandbox.create({
-  provider: e2b({ apiKey: 'your-key' }),
-  options: { runtime: 'python', timeout: 300000 }
-});
-
-// Create sandbox with default provider
-const sandbox = await compute.sandbox.create({
-  options: { runtime: 'python' }
-});
+const result = await sandbox.runCode('print("Hello")', 'python');
+console.log(result.stdout); // "Hello"
+console.log(result.stderr);
+console.log(result.exitCode);
+```
 
-// Get existing sandbox
-const sandbox = await compute.sandbox.getById('sandbox-id');
+#### `sandbox.runCommand(command, args?)`
 
-// List all sandboxes
-const sandboxes = await compute.sandbox.list();
+Run a shell command.
 
-// Destroy sandbox
-await compute.sandbox.destroy('sandbox-id');
+```typescript
+const result = await sandbox.runCommand('npm', ['install', 'express']);
+console.log(result.stdout);
 ```
 
-### Code Execution
+#### `sandbox.getInfo()`
 
-```typescript
-// Run code
-const result = await sandbox.runCode('print("Hello")', 'python');
+Get sandbox information.
 
-// Run shell command
-const result = await sandbox.runCommand('ls', ['-la']);
-
-// Result structure
-interface ExecutionResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-  executionTime: number;
-  sandboxId: string;
-  provider: string;
-}
+```typescript
+const info = await sandbox.getInfo();
+console.log(info.id);
+console.log(info.status); // 'running' | 'stopped' | 'error'
+console.log(info.createdAt);
 ```
 
-### Filesystem Operations
+#### `sandbox.destroy()`
 
-```typescript
-// Write file
-await sandbox.filesystem.writeFile('/tmp/hello.py', 'print("Hello")');
+Destroy the sandbox and clean up resources.
 
-// Read file
-const content = await sandbox.filesystem.readFile('/tmp/hello.py');
-
-// Create directory
-await sandbox.filesystem.mkdir('/tmp/mydir');
+```typescript
+await sandbox.destroy();
+```
 
-// List directory
-const files = await sandbox.filesystem.readdir('/tmp');
+### Filesystem Operations
 
-// Check if exists
-const exists = await sandbox.filesystem.exists('/tmp/hello.py');
+The sandbox provides full filesystem access:
 
-// Remove file/directory
-await sandbox.filesystem.remove('/tmp/hello.py');
-```
+#### `sandbox.filesystem.writeFile(path, content)`
 
-### Terminal Operations
+Write a file to the sandbox.
 
 ```typescript
-// Create terminal (E2B only)
-const terminal = await sandbox.terminal.create({
-  command: 'bash',
-  cols: 80,
-  rows: 24
-});
-
-// Write to terminal
-await terminal.write('ls -la\n');
-
-// Resize terminal
-await terminal.resize(120, 30);
+await sandbox.filesystem.writeFile('/tmp/hello.py', 'print("Hello World")');
+```
 
-// Kill terminal
-await terminal.kill();
+#### `sandbox.filesystem.readFile(path)`
 
-// List terminals
-const terminals = await sandbox.terminal.list();
+Read a file from the sandbox.
 
-// Get terminal by ID
-const terminal = await sandbox.terminal.getById('terminal-id');
+```typescript
+const content = await sandbox.filesystem.readFile('/tmp/hello.py');
+console.log(content); // 'print("Hello World")'
 ```
 
-## Web Framework Integration
+#### `sandbox.filesystem.mkdir(path)`
 
-ComputeSDK provides built-in request handlers for web frameworks:
+Create a directory.
 
 ```typescript
-import { handleComputeRequest } from 'computesdk';
-import { e2b } from '@computesdk/e2b';
+await sandbox.filesystem.mkdir('/tmp/mydir');
+```
 
-// Next.js API route
-export async function POST(request: Request) {
-  return handleComputeRequest({
-    request,
-    provider: e2b({ apiKey: process.env.E2B_API_KEY })
-  });
-}
+#### `sandbox.filesystem.readdir(path)`
 
-// Client usage
-const response = await fetch('/api/compute', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    action: 'compute.sandbox.runCode',
-    code: 'print("Hello from web!")',
-    runtime: 'python'
-  })
-});
+List directory contents.
 
-const result = await response.json();
-console.log(result.result.stdout);
+```typescript
+const files = await sandbox.filesystem.readdir('/tmp');
+console.log(files); // [{ name: 'hello.py', type: 'file', size: 123 }, ...]
 ```
 
-### Supported Actions
-
-- `compute.sandbox.create` - Create new sandbox
-- `compute.sandbox.destroy` - Destroy sandbox
-- `compute.sandbox.getInfo` - Get sandbox information
-- `compute.sandbox.list` - List all sandboxes
-- `compute.sandbox.runCode` - Execute code
-- `compute.sandbox.runCommand` - Run shell command
-- `compute.sandbox.filesystem.readFile` - Read file
-- `compute.sandbox.filesystem.writeFile` - Write file
-- `compute.sandbox.filesystem.mkdir` - Create directory
-- `compute.sandbox.filesystem.readdir` - List directory
-- `compute.sandbox.filesystem.exists` - Check if path exists
-- `compute.sandbox.filesystem.remove` - Remove file/directory
-- `compute.sandbox.terminal.create` - Create terminal
-- `compute.sandbox.terminal.list` - List terminals
-- `compute.sandbox.terminal.getById` - Get terminal by ID
-- `compute.sandbox.terminal.destroy` - Destroy terminal
-- `compute.sandbox.terminal.write` - Write to terminal
-- `compute.sandbox.terminal.resize` - Resize terminal
-- `compute.sandbox.terminal.kill` - Kill terminal
-
-## Frontend Integration
-
-Use `@computesdk/ui` for framework-agnostic factory functions:
+#### `sandbox.filesystem.exists(path)`
 
-```typescript
-import { createCompute, createSandboxConsole } from '@computesdk/ui';
+Check if a file or directory exists.
 
-function CodeExecutor() {
-  const compute = createCompute({
-    apiEndpoint: '/api/compute',
-    defaultRuntime: 'python'
-  });
-  
-  const executeCode = async () => {
-    const sandbox = await compute.sandbox.create();
-    const result = await sandbox.runCode('print("Hello World!")');
-    console.log(result.result?.stdout);
-    await sandbox.destroy();
-  };
-  
-  return (
-    <button onClick={executeCode}>
-      Execute Code
-    </button>
-  );
-}
+```typescript
+const exists = await sandbox.filesystem.exists('/tmp/hello.py');
+console.log(exists); // true
 ```
 
-## Error Handling
+#### `sandbox.filesystem.remove(path)`
+
+Remove a file or directory.
 
 ```typescript
-try {
-  const sandbox = await compute.sandbox.create();
-  const result = await sandbox.runCode('invalid code');
-} catch (error) {
-  console.error('Execution failed:', error.message);
-}
+await sandbox.filesystem.remove('/tmp/hello.py');
 ```
 
 ## Examples
 
-### Data Science with E2B
+### Data Science Workflow
 
 ```typescript
 import { compute } from 'computesdk';
-import { e2b } from '@computesdk/e2b';
-
-compute.setConfig({ provider: e2b({ apiKey: process.env.E2B_API_KEY }) });
 
-const sandbox = await compute.sandbox.create();
+// Assumes E2B_API_KEY is set in environment
+const sandbox = await compute.sandbox.create({ runtime: 'python' });
 
 // Create project structure
 await sandbox.filesystem.mkdir('/analysis');
@@ -508,23 +309,14 @@ print(df)
 avg_age = df['age'].mean()
 print(f"\\nAverage age: {avg_age}")
 
-# Create visualization
-plt.figure(figsize=(8, 6))
-plt.bar(df['name'], df['age'])
-plt.title('Age by Person')
-plt.xlabel('Name')
-plt.ylabel('Age')
-plt.savefig('/analysis/output/age_chart.png')
-print("\\nChart saved to /analysis/output/age_chart.png")
-
 # Save results
+import json
 results = {
     'total_people': len(df),
     'average_age': avg_age,
     'cities': df['city'].unique().tolist()
 }
 
-import json
 with open('/analysis/output/results.json', 'w') as f:
     json.dump(results, f, indent=2)
 
@@ -537,218 +329,138 @@ console.log(result.stdout);
 const results = await sandbox.filesystem.readFile('/analysis/output/results.json');
 console.log('Analysis results:', JSON.parse(results));
 
-await compute.sandbox.destroy(sandbox.sandboxId);
+await sandbox.destroy();
 ```
 
-### Cross-Provider Data Processing
+### Multi-Step Build Process
 
 ```typescript
 import { compute } from 'computesdk';
-import { vercel } from '@computesdk/vercel';
-import { daytona } from '@computesdk/daytona';
-
-async function processData(provider: any) {
-  compute.setConfig({ provider });
-  
-  const sandbox = await compute.sandbox.create();
-  
-  // Create workspace
-  await sandbox.filesystem.mkdir('/workspace');
-  
-  // Write input data
-  await sandbox.filesystem.writeFile('/workspace/input.json', 
-    JSON.stringify({ numbers: [1, 2, 3, 4, 5] })
-  );
-  
-  // Process with code execution
-  const result = await sandbox.runCode(`
-import json
 
-# Read input
-with open('/workspace/input.json', 'r') as f:
-    data = json.load(f)
+const sandbox = await compute.sandbox.create({ runtime: 'node' });
 
-# Process
-numbers = data['numbers']
-result = {
-    'sum': sum(numbers),
-    'average': sum(numbers) / len(numbers),
-    'count': len(numbers)
-}
+// Create project structure
+await sandbox.filesystem.mkdir('/app');
+await sandbox.filesystem.mkdir('/app/src');
+
+// Write package.json
+await sandbox.filesystem.writeFile('/app/package.json', JSON.stringify({
+  name: 'my-app',
+  version: '1.0.0',
+  dependencies: {
+    'express': '^4.18.0'
+  }
+}, null, 2));
 
-# Write output
-with open('/workspace/output.json', 'w') as f:
-    json.dump(result, f, indent=2)
+// Write source code
+await sandbox.filesystem.writeFile('/app/src/index.js', `
+const express = require('express');
+const app = express();
 
-print("Processing complete!")
-  `);
-  
-  // Read results
-  const output = await sandbox.filesystem.readFile('/workspace/output.json');
-  await compute.sandbox.destroy(sandbox.sandboxId);
-  
-  return JSON.parse(output);
-}
+app.get('/', (req, res) => {
+  res.json({ message: 'Hello World!' });
+});
 
-// Use with different providers
-const vercelResult = await processData(vercel({ runtime: 'python' }));
-console.log('Vercel result:', vercelResult);
+console.log('Server ready!');
+`);
 
-const daytonaResult = await processData(daytona({ runtime: 'python' }));
-console.log('Daytona result:', daytonaResult);
-```
+// Install dependencies
+const installResult = await sandbox.runCommand('npm', ['install'], { cwd: '/app' });
+console.log('Install:', installResult.stdout);
 
-## Provider Packages
+// Run the app
+const runResult = await sandbox.runCode(`
+const { spawn } = require('child_process');
+const proc = spawn('node', ['src/index.js'], { cwd: '/app' });
+proc.stdout.on('data', (data) => console.log(data.toString()));
+`);
 
-ComputeSDK uses separate provider packages:
+console.log(runResult.stdout);
 
-```bash
-npm install @computesdk/blaxel     # Blaxel provider
-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
+await sandbox.destroy();
 ```
 
-Each provider implements the same interface but may support different capabilities (filesystem, terminal, etc.).
+### Using Different Providers
 
-## Utility Packages
+```typescript
+import { compute } from 'computesdk';
 
-Additional packages for enhanced functionality:
+// Use E2B for data science
+compute.setConfig({
+  provider: 'e2b',
+  e2b: { apiKey: process.env.E2B_API_KEY }
+});
 
-```bash
-npm install @computesdk/cmd        # Type-safe shell command builders
-npm install @computesdk/client     # Universal sandbox client (browser/Node.js)
-npm install @computesdk/events     # Event storage and real-time streaming
-npm install @computesdk/workbench  # Interactive REPL for sandbox testing
-```
+const e2bSandbox = await compute.sandbox.create();
+await e2bSandbox.runCode('import pandas as pd; print(pd.__version__)');
+await e2bSandbox.destroy();
 
-### @computesdk/cmd - Type-Safe Commands
+// Switch to Modal for GPU workloads
+compute.setConfig({
+  provider: 'modal',
+  modal: { 
+    tokenId: process.env.MODAL_TOKEN_ID,
+    tokenSecret: process.env.MODAL_TOKEN_SECRET
+  }
+});
 
-Build shell commands with full TypeScript support:
+const modalSandbox = await compute.sandbox.create();
+await modalSandbox.runCode('import torch; print(torch.cuda.is_available())');
+await modalSandbox.destroy();
+```
+
+## Error Handling
 
 ```typescript
-import { npm, git, mkdir, cmd } from '@computesdk/cmd';
+try {
+  const sandbox = await compute.sandbox.create();
+  const result = await sandbox.runCode('invalid python code');
+} catch (error) {
+  console.error('Execution failed:', error.message);
+  
+  // Check for specific error types
+  if (error.message.includes('No provider detected')) {
+    console.error('Set provider credentials in environment variables');
+  }
+}
+```
 
-// Type-safe command builders
-await sandbox.runCommand(npm.install('express'));
-await sandbox.runCommand(git.clone('https://github.com/user/repo'));
-await sandbox.runCommand(mkdir('/app/src'));
+## Direct Mode (Advanced)
 
-// With options
-await sandbox.runCommand(cmd(npm.run('dev'), { cwd: '/app', background: true }));
-```
+For advanced use cases where you want to bypass the gateway and use provider SDKs directly, see individual provider packages:
 
-### @computesdk/workbench - Interactive REPL
+- **[@computesdk/e2b](../e2b)** - E2B provider
+- **[@computesdk/modal](../modal)** - Modal provider
+- **[@computesdk/railway](../railway)** - Railway provider
+- **[@computesdk/daytona](../daytona)** - Daytona provider
 
-Test sandbox operations interactively:
+Example direct mode usage:
 
-```bash
-npx workbench
+```typescript
+import { e2b } from '@computesdk/e2b';
 
-# Commands autocomplete!
-workbench> npm.install('express')
-workbench> git.clone('https://github.com/user/repo')
-workbench> ls('/home')
+const compute = e2b({ apiKey: 'your_api_key' });
+const sandbox = await compute.sandbox.create();
 ```
 
-## Custom Providers
-
-Create custom providers using the factory:
+## Building Custom Providers
 
-```typescript
-import { createProvider } from 'computesdk';
-
-const myProvider = createProvider({
-  name: 'my-provider',
-  methods: {
-    sandbox: {
-      create: async (config, options) => {
-        // Implementation
-      },
-      getById: async (config, id) => {
-        // Implementation  
-      },
-      list: async (config) => {
-        // Implementation
-      },
-      destroy: async (config, id) => {
-        // Implementation
-      }
-    }
-  }
-});
-```
+Want to add support for a new compute provider? See **[@computesdk/provider](../provider)** for the provider framework and documentation on building custom providers.
 
 ## TypeScript Support
 
-ComputeSDK is fully typed with comprehensive TypeScript definitions:
+Full TypeScript support with comprehensive type definitions:
 
 ```typescript
 import type { 
-  Sandbox, 
-  Provider, 
-  ExecutionResult,
-  ComputeConfig,
-  Runtime 
+  Sandbox,
+  SandboxInfo,
+  CodeResult,
+  CommandResult,
+  CreateSandboxOptions
 } from 'computesdk';
 ```
 
-## Provider Comparison
-
-| Provider | Code Execution | Filesystem | Terminal | Use Cases |
-|----------|----------------|------------|----------|-----------|
-| **E2B** | Python, Node.js | ✅ Full | ✅ PTY | Data science, AI/ML, interactive development |
-| **Vercel** | Node.js, Python | ✅ Full | ❌ | Web apps, APIs, serverless functions |
-| **Daytona** | Python, Node.js | ✅ Full | ❌ | Development workspaces, custom environments |
-
-### Key Differences
-
-- **E2B**: Full development environment with data science libraries and interactive terminals
-- **Vercel**: Ephemeral sandboxes optimized for serverless execution (up to 45 minutes)
-- **Daytona**: Development workspaces with persistent environments
-
-## Examples
-
-Check out the [examples directory](./examples) for complete implementations with different web frameworks:
-
-- [Next.js](./examples/nextjs)
-- [Nuxt](./examples/nuxt) 
-- [SvelteKit](./examples/sveltekit)
-- [Remix](./examples/remix)
-- [Astro](./examples/astro)
-
-## Resources
-
-- 📖 **[Full Documentation](https://computesdk.com)** - Complete guides and API reference
-- 🚀 **[Getting Started](https://computesdk.com/getting-started)** - Quick setup guide
-- 💡 **[Examples](./examples)** - Real-world usage examples
-- 🎯 **[Providers](https://computesdk.com/providers)** - Provider-specific guides
-
-## Contributing
-
-ComputeSDK is open source and welcomes contributions! Whether you're fixing bugs, adding features, or improving documentation, we'd love your help.
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-## Community & Support
-
-- 💬 **[GitHub Discussions](https://github.com/computesdk/computesdk/discussions)** - Ask questions and share ideas
-- 🐛 **[GitHub Issues](https://github.com/computesdk/computesdk/issues)** - Report bugs and request features
-- 📧 **[Contact Us](https://computesdk.com/contact)** - Get in touch with the team
-
 ## License
 
-MIT License - see the [LICENSE](LICENSE) file for details.
-
----
-
-<div align="center">
-  <strong>Built with ❤️ by the ComputeSDK team</strong><br>
-  <a href="https://computesdk.com">computesdk.com</a>
-</div>
+MIT