computesdk 2.0.0 → 2.0.2

package/README.md

@@ -1,746 +1,712 @@
-# ComputeSDK
+# computesdk
 
-A unified abstraction layer for executing code in secure, isolated sandboxed environments across multiple cloud providers.
-
-Similar to how Vercel's AI SDK abstracts different LLM providers, ComputeSDK abstracts different compute sandbox providers into a single, consistent TypeScript interface.
-
-## Features
-
-- 🚀 **Multi-provider support** - E2B, Vercel, Daytona
-- 📁 **Filesystem operations** - Read, write, create directories across providers
-- 🖥️ **Terminal support** - Interactive PTY terminals (E2B)
-- ⚡ **Command execution** - Run shell commands directly
-- 🔄 **Auto-detection** - Automatically selects providers based on environment variables
-- 🛡️ **Type-safe** - Full TypeScript support with comprehensive error handling
-- 📦 **Modular** - Install only the providers you need
-- 🔧 **Extensible** - Easy to add custom providers
-
-## Supported Providers
-
-| Provider | Code Execution | Filesystem | Terminal | Use Cases |
-|----------|----------------|------------|----------|-----------|
-| **E2B** | Python | ✅ 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 |
+The gateway SDK for running code in remote sandboxes. Zero-config auto-detection with support for E2B, Modal, Railway, Daytona, Vercel, and more.
 
 ## Installation
 
 ```bash
-# 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
 ```
 
 ## Quick Start
 
-### Auto-detection (Recommended)
+### Zero-Config Mode (Recommended)
 
-ComputeSDK automatically detects available providers based on environment variables:
+Set your provider credentials as environment variables and ComputeSDK automatically detects and configures everything:
+
+```bash
+export E2B_API_KEY=your_e2b_api_key
+```
 
 ```typescript
-import { ComputeSDK } from 'computesdk';
+import { compute } from 'computesdk';
 
-// Automatically detects and uses the first available provider
-const sandbox = ComputeSDK.createSandbox();
+// Auto-detects E2B from environment
+const sandbox = await compute.sandbox.create();
 
-const result = await sandbox.execute('print("Hello World!")');
-console.log(result.stdout); // "Hello World!"
+// Execute code
+const result = await sandbox.runCode('print("Hello World!")');
+console.log(result.output); // "Hello World!"
 
-await sandbox.kill();
+// Clean up
+await sandbox.destroy();
 ```
 
-### Provider-specific Usage
+### Explicit Configuration
+
+For more control, use `setConfig()` to explicitly configure the provider:
 
 ```typescript
-import { executeSandbox } from 'computesdk';
-import { e2b } from '@computesdk/e2b';
+import { compute } from 'computesdk';
 
-// Execute with specific provider
-const result = await executeSandbox({
-  sandbox: e2b(),
-  code: 'print("Hello from E2B!")',
-  runtime: 'python'
+compute.setConfig({
+  provider: 'your-provider',
+  apiKey: process.env.COMPUTESDK_API_KEY,
+  'your-provider': {
+    apiKey: process.env.YOUR_PROVIDER_API_KEY
+  }
 });
 
-console.log(result.stdout);
+const sandbox = await compute.sandbox.create();
 ```
 
-### Advanced Usage with Type Safety
+## Supported Providers
 
-ComputeSDK provides rich TypeScript interfaces for different provider capabilities:
+ComputeSDK automatically detects providers based on environment variables:
 
-```typescript
-import { ComputeSDK, FilesystemComputeSandbox, TerminalComputeSandbox } from 'computesdk';
+| 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 |
 
-const sandbox = ComputeSDK.createSandbox();
+### Provider Detection Order
 
-// Check provider capabilities at runtime
-if ('filesystem' in sandbox) {
-  const fsSandbox = sandbox as FilesystemComputeSandbox;
-  
-  // Use filesystem operations
-  await fsSandbox.filesystem.writeFile('/tmp/data.txt', 'Hello World!');
-  const content = await fsSandbox.filesystem.readFile('/tmp/data.txt');
-  console.log(content); // "Hello World!"
-}
+When using zero-config mode, ComputeSDK detects providers in this order:
 
-if ('terminal' in sandbox) {
-  const termSandbox = sandbox as TerminalComputeSandbox;
-  
-  // Create interactive terminal (E2B only)
-  const terminal = await termSandbox.terminal.create({
-    command: 'bash',
-    cols: 80,
-    rows: 24
-  });
-  
-  await terminal.write('echo "Interactive terminal!"\n');
-  await terminal.kill();
-}
-```
-
-## Environment Setup
+**E2B → Railway → Daytona → Modal → Runloop → Vercel → Cloudflare → CodeSandbox**
 
-Each provider requires specific environment variables for authentication:
+You can force a specific provider:
 
-### E2B (Full Features)
 ```bash
-export E2B_API_KEY=e2b_your_api_key_here
+export COMPUTESDK_PROVIDER=modal
 ```
-Get your API key from [e2b.dev](https://e2b.dev/)
 
-### Vercel (Filesystem + Code Execution)
-```bash
-export VERCEL_TOKEN=your_vercel_token_here
-export VERCEL_TEAM_ID=your_team_id_here
-export VERCEL_PROJECT_ID=your_project_id_here
-```
-Get your token from [Vercel Account Tokens](https://vercel.com/account/tokens)
+## API Reference
 
-### Daytona (Development Workspaces)
-```bash
-export DAYTONA_API_KEY=your_daytona_api_key_here
+### Configuration
+
+#### `compute.setConfig(config)`
+
+Configure the gateway with explicit provider settings.
+
+```typescript
+compute.setConfig({
+  provider: 'your-provider',
+  apiKey: process.env.COMPUTESDK_API_KEY,
+  'your-provider': {
+    apiKey: process.env.YOUR_PROVIDER_API_KEY
+  }
+});
 ```
 
+**Provider-specific configs:**
 
+```typescript
+// E2B
+compute.setConfig({
+  provider: 'e2b',
+  apiKey: process.env.COMPUTESDK_API_KEY,
+  e2b: { 
+    apiKey: 'e2b_xxx',
+    templateId: 'optional_template' 
+  }
+});
 
-## API Reference
+// Modal
+compute.setConfig({
+  provider: 'modal',
+  apiKey: process.env.COMPUTESDK_API_KEY,
+  modal: { 
+    tokenId: 'ak-xxx',
+    tokenSecret: 'as-xxx'
+  }
+});
+
+// Railway
+compute.setConfig({
+  provider: 'railway',
+  apiKey: process.env.COMPUTESDK_API_KEY,
+  railway: { 
+    apiToken: 'your_token',
+    projectId: 'project_id',
+    environmentId: 'env_id'
+  }
+});
+
+// Daytona
+compute.setConfig({
+  provider: 'daytona',
+  apiKey: process.env.COMPUTESDK_API_KEY,
+  daytona: { apiKey: 'your_api_key' }
+});
 
-### Core SDK
+// Vercel
+compute.setConfig({
+  provider: 'vercel',
+  apiKey: process.env.COMPUTESDK_API_KEY,
+  vercel: { 
+    token: 'your_token',
+    teamId: 'team_xxx',
+    projectId: 'prj_xxx'
+  }
+});
+```
 
-#### `ComputeSDK.createSandbox(config?)`
+### Sandbox Management
 
-Creates a sandbox using auto-detection or specified configuration.
+#### `compute.sandbox.create(options?)`
 
-```typescript
-// Auto-detection
-const sandbox = ComputeSDK.createSandbox();
+Create a new sandbox.
 
-// With configuration
-const sandbox = ComputeSDK.createSandbox({
-  provider: 'e2b',
-  runtime: 'python',
-  timeout: 600000 // 10 minutes
+```typescript
+const sandbox = await compute.sandbox.create();
+
+// With options
+const sandbox = await compute.sandbox.create({
+  timeout: 300000, // 5 minutes
+  metadata: { userId: '123' },
+  namespace: 'my-org',
+  name: 'my-sandbox',
 });
 ```
 
-**Parameters:**
-- `config` (optional): Sandbox configuration object
+**Options:**
+- `timeout?: number` - Timeout in milliseconds
+- `metadata?: Record<string, any>` - Custom metadata
+- `envs?: Record<string, string>` - Environment variables
+- `namespace?: string` - Namespace for organizing sandboxes
+- `name?: string` - Name for the sandbox (enables findOrCreate)
+- `overlays?: SetupOverlayConfig[]` - Template overlays to apply
+- `servers?: ServerStartOptions[]` - Servers to start automatically
+
+#### `compute.sandbox.getById(sandboxId)`
 
-**Returns:** `ComputeSandbox` - The appropriate sandbox type based on provider capabilities
+Get an existing sandbox by ID.
 
-#### `ComputeSDK.detectProviders()`
+```typescript
+const sandbox = await compute.sandbox.getById('sandbox-id');
+```
 
-Detects available providers based on environment variables.
+#### `compute.sandbox.findOrCreate(options)`
+
+Find an existing sandbox by namespace and name, or create a new one.
 
 ```typescript
-const providers = ComputeSDK.detectProviders();
-console.log('Available providers:', providers); // ['e2b', 'vercel']
+const sandbox = await compute.sandbox.findOrCreate({
+  namespace: 'my-org',
+  name: 'my-project',
+});
 ```
 
-**Returns:** `ProviderType[]` - Array of available provider names
+#### `compute.sandbox.find(options)`
 
-### Utility Functions
+Find an existing sandbox by namespace and name (returns null if not found).
 
-#### `executeSandbox(params)`
+```typescript
+const sandbox = await compute.sandbox.find({
+  namespace: 'my-org',
+  name: 'my-project',
+});
+```
+
+### Sandbox Operations
 
-Utility function for one-off code execution.
+#### `sandbox.runCode(code, language?)`
+
+Execute code in the sandbox.
 
 ```typescript
-import { executeSandbox } from 'computesdk';
-import { vercel } from '@computesdk/vercel';
+const result = await sandbox.runCode('print("Hello")', 'python');
+console.log(result.output); // "Hello"
+console.log(result.exitCode);
+```
+
+#### `sandbox.runCommand(command, options?)`
 
-const result = await executeSandbox({
-  sandbox: vercel({ runtime: 'node' }),
-  code: 'console.log("Hello from Node.js!");',
-  runtime: 'node'
+Run a shell command.
+
+```typescript
+const result = await sandbox.runCommand('npm install express');
+console.log(result.stdout);
+console.log(result.exitCode);
+
+// With options
+const result = await sandbox.runCommand('npm install', {
+  cwd: '/app',
+  env: { NODE_ENV: 'production' },
+  background: true,
 });
 ```
 
-**Parameters:**
+#### `sandbox.destroy()`
+
+Destroy the sandbox and clean up resources.
+
 ```typescript
-interface ExecuteSandboxParams {
-  sandbox: ComputeSandbox;
-  code: string;
-  runtime?: Runtime;
-}
+await sandbox.destroy();
 ```
 
-### Sandbox Interfaces
+### Filesystem Operations
 
-ComputeSDK provides a rich type system for different provider capabilities:
+The sandbox provides full filesystem access:
 
-#### `BaseComputeSandbox`
+#### `sandbox.filesystem.writeFile(path, content)`
 
-Basic code execution capabilities (all providers support this):
+Write a file to the sandbox.
 
 ```typescript
-interface BaseComputeSandbox {
-  provider: string;
-  sandboxId: string;
-  
-  execute(code: string, runtime?: Runtime): Promise<ExecutionResult>;
-  runCode(code: string, runtime?: Runtime): Promise<ExecutionResult>;
-  runCommand(command: string, args?: string[]): Promise<ExecutionResult>;
-  kill(): Promise<void>;
-  getInfo(): Promise<SandboxInfo>;
-}
+await sandbox.filesystem.writeFile('/tmp/hello.py', 'print("Hello World")');
 ```
 
-#### `FilesystemComputeSandbox`
+#### `sandbox.filesystem.readFile(path)`
 
-Extends base capabilities with filesystem operations (E2B, Vercel, Daytona):
+Read a file from the sandbox.
 
 ```typescript
-interface FilesystemComputeSandbox extends BaseComputeSandbox {
-  readonly filesystem: SandboxFileSystem;
-}
+const content = await sandbox.filesystem.readFile('/tmp/hello.py');
+console.log(content); // 'print("Hello World")'
+```
 
-interface SandboxFileSystem {
-  readFile(path: string): Promise<string>;
-  writeFile(path: string, content: string): Promise<void>;
-  mkdir(path: string): Promise<void>;
-  readdir(path: string): Promise<FileEntry[]>;
-  exists(path: string): Promise<boolean>;
-  remove(path: string): Promise<void>;
-}
+#### `sandbox.filesystem.mkdir(path)`
+
+Create a directory.
+
+```typescript
+await sandbox.filesystem.mkdir('/tmp/mydir');
 ```
 
-#### `TerminalComputeSandbox`
+#### `sandbox.filesystem.readdir(path)`
 
-Extends base capabilities with terminal operations (E2B only):
+List directory contents.
 
 ```typescript
-interface TerminalComputeSandbox extends BaseComputeSandbox {
-  readonly terminal: SandboxTerminal;
-}
+const files = await sandbox.filesystem.readdir('/tmp');
+console.log(files); // [{ name: 'hello.py', type: 'file', size: 123 }, ...]
+```
 
-interface SandboxTerminal {
-  create(options?: TerminalCreateOptions): Promise<InteractiveTerminalSession>;
-  list(): Promise<InteractiveTerminalSession[]>;
-}
+#### `sandbox.filesystem.exists(path)`
+
+Check if a file or directory exists.
+
+```typescript
+const exists = await sandbox.filesystem.exists('/tmp/hello.py');
+console.log(exists); // true
 ```
 
-#### `FullComputeSandbox`
+#### `sandbox.filesystem.remove(path)`
 
-Full capabilities including filesystem and terminal (E2B only):
+Remove a file or directory.
 
 ```typescript
-interface FullComputeSandbox extends FilesystemComputeSandbox, TerminalComputeSandbox {}
+await sandbox.filesystem.remove('/tmp/hello.py');
 ```
 
-### Data Types
+### Terminal Operations
 
-#### `ExecutionResult`
+The sandbox provides terminal access in two modes: **PTY mode** (interactive shell) and **Exec mode** (command tracking).
 
-Result object returned by all execution methods:
+#### `sandbox.terminal.create(options?)`
+
+Create a new terminal session.
 
 ```typescript
-interface ExecutionResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-  executionTime: number;
-  sandboxId: string;
-  provider: string;
-}
+// PTY mode - Interactive shell
+const pty = await sandbox.terminal.create({ pty: true, shell: '/bin/bash' });
+
+// Exec mode - Command tracking (default)
+const exec = await sandbox.terminal.create({ pty: false });
 ```
 
-#### `SandboxInfo`
+**Options:**
+- `pty?: boolean` - Terminal mode: `true` = PTY (interactive), `false` = exec (command tracking). Default: `false`
+- `shell?: string` - Shell to use (e.g., '/bin/bash'). PTY mode only
+- `encoding?: 'raw' | 'base64'` - Output encoding. Default: `'raw'`
 
-Information about a sandbox instance:
+**Returns:** `TerminalInstance`
+
+#### `sandbox.terminal.list()`
+
+List all active terminals.
 
 ```typescript
-interface SandboxInfo {
-  id: string;
-  provider: string;
-  runtime: Runtime;
-  status: 'running' | 'stopped' | 'error';
-  createdAt: Date;
-  timeout: number;
-  metadata?: Record<string, any>;
-}
+const terminals = await sandbox.terminal.list();
+console.log(terminals); // [{ id: 'term-1', pty: true, status: 'running', ... }]
 ```
 
-#### `FileEntry`
+#### `sandbox.terminal.retrieve(id)`
 
-File system entry information:
+Retrieve a specific terminal by ID.
 
 ```typescript
-interface FileEntry {
-  name: string;
-  path: string;
-  isDirectory: boolean;
-  size: number;
-  lastModified: Date;
-}
+const terminal = await sandbox.terminal.retrieve('term-123');
+console.log(terminal.id, terminal.status);
 ```
 
-## Examples
+#### `sandbox.terminal.destroy(id)`
 
-### Cross-Provider Data Processing
+Destroy a terminal by ID.
 
 ```typescript
-import { ComputeSDK, FilesystemComputeSandbox } from 'computesdk';
+await sandbox.terminal.destroy('term-123');
+```
 
-async function processData() {
-  // Auto-detect best available provider
-  const sandbox = ComputeSDK.createSandbox();
-  
-  if ('filesystem' in sandbox) {
-    const fsSandbox = sandbox as FilesystemComputeSandbox;
-    
-    // Create project structure
-    await fsSandbox.filesystem.mkdir('/project/data');
-    await fsSandbox.filesystem.mkdir('/project/output');
-    
-    // Write input data
-    const data = JSON.stringify([
-      { name: 'Alice', sales: 1000 },
-      { name: 'Bob', sales: 1500 },
-      { name: 'Charlie', sales: 800 }
-    ]);
-    
-    await fsSandbox.filesystem.writeFile('/project/data/sales.json', data);
-    
-    // Process data based on provider
-    let code: string;
-    if (sandbox.provider === 'e2b') {
-      // Python processing for E2B
-      code = `
-import json
-import pandas as pd
-
-# Read data
-with open('/project/data/sales.json', 'r') as f:
-    data = json.load(f)
-
-# Process with pandas
-df = pd.DataFrame(data)
-total_sales = df['sales'].sum()
-avg_sales = df['sales'].mean()
-
-# Write results
-results = {
-    'total_sales': total_sales,
-    'average_sales': avg_sales,
-    'top_performer': df.loc[df['sales'].idxmax(), 'name']
-}
+### PTY Mode (Interactive Shell)
 
-with open('/project/output/results.json', 'w') as f:
-    json.dump(results, f, indent=2)
-
-print(f"Total Sales: ${total_sales}")
-print(f"Average Sales: ${avg_sales:.2f}")
-print(f"Top Performer: {results['top_performer']}")
-      `;
-    } else {
-      // JavaScript processing for Vercel/Daytona
-      code = `
-const fs = require('fs');
-
-// Read data
-const data = JSON.parse(fs.readFileSync('/project/data/sales.json', 'utf8'));
-
-// Process data
-const totalSales = data.reduce((sum, person) => sum + person.sales, 0);
-const avgSales = totalSales / data.length;
-const topPerformer = data.reduce((top, person) => 
-  person.sales > top.sales ? person : top
-);
-
-// Write results
-const results = {
-  total_sales: totalSales,
-  average_sales: avgSales,
-  top_performer: topPerformer.name
-};
-
-fs.writeFileSync('/project/output/results.json', JSON.stringify(results, null, 2));
-
-console.log(\`Total Sales: $\${totalSales}\`);
-console.log(\`Average Sales: $\${avgSales.toFixed(2)}\`);
-console.log(\`Top Performer: \${results.top_performer}\`);
-      `;
-    }
-    
-    // Execute processing
-    const result = await fsSandbox.execute(code);
-    console.log('Processing Output:', result.stdout);
-    
-    // Read results
-    const results = await fsSandbox.filesystem.readFile('/project/output/results.json');
-    console.log('Results:', JSON.parse(results));
-    
-    // List generated files
-    const outputFiles = await fsSandbox.filesystem.readdir('/project/output');
-    console.log('Generated files:', outputFiles.map(f => f.name));
-  }
-  
-  await sandbox.kill();
-}
+PTY mode creates an interactive shell session with real-time input/output over WebSocket.
+
+#### `terminal.write(input)`
 
-processData().catch(console.error);
+Send input to the terminal shell.
+
+```typescript
+const pty = await sandbox.terminal.create({ pty: true });
+pty.on('output', (data) => console.log(data));
+pty.write('ls -la\n');
+pty.write('pwd\n');
+await pty.destroy();
 ```
 
-### Interactive Development with E2B
+#### `terminal.resize(cols, rows)`
+
+Resize the terminal window.
 
 ```typescript
-import { e2b } from '@computesdk/e2b';
-import { TerminalComputeSandbox, FilesystemComputeSandbox } from 'computesdk';
+pty.resize(120, 40);
+```
 
-async function interactiveDevelopment() {
-  const sandbox = e2b() as TerminalComputeSandbox & FilesystemComputeSandbox;
-  
-  // Set up development environment
-  await sandbox.filesystem.mkdir('/workspace');
-  await sandbox.filesystem.writeFile('/workspace/requirements.txt', 
-    'pandas\nnumpy\nmatplotlib\nscikit-learn'
-  );
-  
-  // Create interactive terminal
-  const terminal = await sandbox.terminal.create({
-    command: 'bash',
-    cols: 120,
-    rows: 30
-  });
-  
-  // Set up output handler
-  terminal.onData = (data: Uint8Array) => {
-    const output = new TextDecoder().decode(data);
-    console.log('Terminal:', output);
-  };
-  
-  // Install dependencies
-  await terminal.write('cd /workspace\n');
-  await terminal.write('pip install -r requirements.txt\n');
-  
-  // Start interactive Python session
-  await terminal.write('python3\n');
-  await terminal.write('import pandas as pd\n');
-  await terminal.write('import numpy as np\n');
-  await terminal.write('print("Development environment ready!")\n');
-  
-  // Simulate interactive development
-  await new Promise(resolve => setTimeout(resolve, 5000));
-  
-  // Clean up
-  await terminal.kill();
-  await sandbox.kill();
-}
+#### `terminal.on(event, handler)`
 
-interactiveDevelopment().catch(console.error);
+Register an event handler. Events: `'output'`, `'error'`, `'destroyed'`.
+
+```typescript
+pty.on('output', (data) => console.log('Output:', data));
+pty.on('error', (error) => console.error('Error:', error));
+pty.on('destroyed', () => console.log('Terminal destroyed'));
 ```
 
-### Multi-Provider Comparison
+#### `terminal.off(event, handler)`
+
+Unregister an event handler.
 
 ```typescript
-import { executeSandbox } from 'computesdk';
-import { e2b } from '@computesdk/e2b';
-import { vercel } from '@computesdk/vercel';
-import { daytona } from '@computesdk/daytona';
-
-async function compareProviders() {
-  const testCode = `
-import json
-import time
-start = time.time()
-
-# Simple computation
-result = sum(range(1000))
-elapsed = time.time() - start
-
-output = {
-    "result": result,
-    "elapsed_ms": round(elapsed * 1000, 2),
-    "provider": "will_be_set"
-}
+const handler = (data) => console.log(data);
+pty.on('output', handler);
+pty.off('output', handler);
+```
 
-print(json.dumps(output))
-  `;
-  
-  const providers = [
-    { name: 'E2B', factory: () => e2b() },
-    { name: 'Vercel', factory: () => vercel({ runtime: 'python' }) },
-    { name: 'Daytona', factory: () => daytona({ runtime: 'python' }) },
-  ];
-  
-  console.log('Performance Comparison:');
-  console.log('='.repeat(50));
-  
-  for (const { name, factory } of providers) {
-    try {
-      const start = Date.now();
-      const result = await executeSandbox({
-        sandbox: factory(),
-        code: testCode,
-        runtime: 'python'
-      });
-      const totalTime = Date.now() - start;
-      
-      const output = JSON.parse(result.stdout);
-      console.log(`${name}:`);
-      console.log(`  Computation: ${output.result}`);
-      console.log(`  Execution time: ${output.elapsed_ms}ms`);
-      console.log(`  Total time: ${totalTime}ms`);
-      console.log(`  Provider overhead: ${totalTime - output.elapsed_ms}ms`);
-      console.log();
-      
-    } catch (error) {
-      console.log(`${name}: Failed - ${error.message}`);
-      console.log();
-    }
-  }
-}
+#### Terminal Properties
 
-compareProviders().catch(console.error);
+```typescript
+console.log(pty.id);       // Terminal ID
+console.log(pty.status);   // 'running' | 'stopped' | 'active' | 'ready'
+console.log(pty.channel);  // WebSocket channel (PTY only)
+console.log(pty.pty);      // true for PTY mode
 ```
 
-## Error Handling
+### Exec Mode (Command Tracking)
 
-ComputeSDK provides comprehensive error handling with specific error types:
+Exec mode executes commands with structured result tracking, suitable for automation.
 
-```typescript
-import { ComputeSDK } from 'computesdk';
+#### `terminal.command.run(command, options?)`
 
-try {
-  const sandbox = ComputeSDK.createSandbox();
-  const result = await sandbox.execute('invalid python code');
-} catch (error) {
-  if (error.message.includes('Missing') && error.message.includes('API key')) {
-    console.error('Authentication Error: Check your environment variables');
-    console.error('Required: E2B_API_KEY, VERCEL_TOKEN, etc.');
-  } else if (error.message.includes('timeout')) {
-    console.error('Timeout Error: Execution took too long');
-  } else if (error.message.includes('quota') || error.message.includes('limit')) {
-    console.error('Quota Error: API usage limits exceeded');
-  } else if (error.message.includes('not installed')) {
-    console.error('Configuration Error: Provider package not installed');
-    console.error('Run: npm install @computesdk/[provider-name]');
-  } else {
-    console.error('Execution Error:', error.message);
-  }
-}
+Execute a command in the terminal.
+
+```typescript
+const exec = await sandbox.terminal.create({ pty: false });
+
+// Foreground execution (waits for completion)
+const cmd = await exec.command.run('npm test');
+console.log(cmd.stdout);
+console.log(cmd.stderr);
+console.log(cmd.exitCode);
+
+// Background execution (returns immediately)
+const bgCmd = await exec.command.run('npm install', { background: true });
+console.log(bgCmd.status); // 'running'
+await bgCmd.wait(); // Wait for completion
+console.log(bgCmd.exitCode);
 ```
 
-## Provider-Specific Features
+**Parameters:**
+- `command: string` - The command to execute
+- `options?: { background?: boolean }` - Execution options
+
+**Returns:** `Command` object
 
-### E2B - Full Development Environment
+#### `terminal.command.list()`
 
-E2B provides the richest feature set with full filesystem and terminal support:
+List all commands executed in this terminal.
 
 ```typescript
-import { e2b } from '@computesdk/e2b';
+const commands = await exec.command.list();
+commands.forEach(cmd => {
+  console.log(cmd.id, cmd.command, cmd.status, cmd.exitCode);
+});
+```
 
-const sandbox = e2b();
+#### `terminal.command.retrieve(cmdId)`
 
-// Full Python environment with data science libraries
-const result = await sandbox.execute(`
-import pandas as pd
-import matplotlib.pyplot as plt
-import numpy as np
+Retrieve a specific command by ID.
 
-# Create and visualize data
-data = np.random.randn(1000)
-plt.hist(data, bins=50)
-plt.savefig('/tmp/histogram.png')
-print("Histogram saved!")
-`);
+```typescript
+const cmd = await exec.command.retrieve('cmd-123');
+console.log(cmd.stdout);
+```
+
+### Command Object
+
+The `Command` object represents a command execution result.
+
+#### Command Properties
 
-// Check if file was created
-const exists = await sandbox.filesystem.exists('/tmp/histogram.png');
-console.log('Histogram created:', exists);
+```typescript
+console.log(cmd.id);          // Command ID
+console.log(cmd.terminalId);  // Parent terminal ID
+console.log(cmd.command);     // Executed command
+console.log(cmd.status);      // 'running' | 'completed' | 'failed'
+console.log(cmd.stdout);      // Standard output
+console.log(cmd.stderr);      // Standard error
+console.log(cmd.exitCode);    // Exit code (undefined if running)
+console.log(cmd.durationMs);  // Execution time in milliseconds
+console.log(cmd.startedAt);   // Start timestamp
+console.log(cmd.finishedAt);  // Finish timestamp (undefined if running)
 ```
 
-### Vercel - Scalable Serverless Execution
+#### `command.wait(timeout?)`
 
-Vercel provides reliable execution with filesystem support:
+Wait for a background command to complete.
 
 ```typescript
-import { vercel } from '@computesdk/vercel';
+const cmd = await exec.command.run('sleep 5', { background: true });
+await cmd.wait(); // Waits up to default timeout
+console.log(cmd.exitCode);
+
+// With custom timeout (in seconds, 0 = no timeout)
+await cmd.wait(10);
+```
 
-const sandbox = vercel({ runtime: 'node' });
+#### `command.refresh()`
 
-// Process data with Node.js
-const result = await sandbox.execute(`
-const fs = require('fs');
-const path = require('path');
+Refresh the command status from the server.
 
-// Create API simulation
-const apiData = {
-  users: 1000,
-  active: 750,
-  revenue: 50000
-};
+```typescript
+const cmd = await exec.command.run('npm build', { background: true });
+// ... later ...
+await cmd.refresh();
+console.log(cmd.status, cmd.exitCode);
+```
 
-// Write to filesystem
-fs.writeFileSync('/tmp/api-data.json', JSON.stringify(apiData, null, 2));
+#### `terminal.destroy()`
 
-console.log('API data processed and saved');
-console.log('Active users:', apiData.active);
-`);
+Destroy the terminal and clean up resources.
 
-// Read the generated data
-const data = await sandbox.filesystem.readFile('/tmp/api-data.json');
-console.log('Generated data:', JSON.parse(data));
+```typescript
+await exec.destroy();
 ```
 
-### Daytona - Development Workspaces
+## Examples
 
-Daytona provides development workspace environments with full filesystem support:
+### Multi-Step Build Process
 
 ```typescript
-import { daytona } from '@computesdk/daytona';
+import { compute } from 'computesdk';
 
-const sandbox = daytona({ runtime: 'python' });
+const sandbox = await compute.sandbox.create();
 
-// Execute Python code in workspace
-const result = await sandbox.execute(`
-import json
-import os
+// 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));
 
-# Create project structure
-os.makedirs('/workspace/src', exist_ok=True)
-os.makedirs('/workspace/tests', exist_ok=True)
+// Write source code
+await sandbox.filesystem.writeFile('/app/src/index.js', `
+const express = require('express');
+const app = express();
 
-# Write project files
-with open('/workspace/src/main.py', 'w') as f:
-    f.write('def hello():\\n    return "Hello from Daytona!"\\n')
+app.get('/', (req, res) => {
+  res.json({ message: 'Hello World!' });
+});
+
+console.log('Server ready!');
+`);
 
-with open('/workspace/tests/test_main.py', 'w') as f:
-    f.write('from src.main import hello\\n\\ndef test_hello():\\n    assert hello() == "Hello from Daytona!"\\n')
+// Install dependencies
+const installResult = await sandbox.runCommand('npm install', { cwd: '/app' });
+console.log('Install:', installResult.stdout);
 
-print("Project structure created!")
-print("Files:", os.listdir('/workspace'))
+// 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()));
 `);
 
-// Check created files
-const files = await sandbox.filesystem.readdir('/workspace');
-console.log('Workspace files:', files.map(f => f.name));
+console.log(runResult.output);
 
-// Read project file
-const mainPy = await sandbox.filesystem.readFile('/workspace/src/main.py');
-console.log('main.py content:', mainPy);
+await sandbox.destroy();
 ```
 
+### Terminal Command Execution
 
+```typescript
+import { compute } from 'computesdk';
 
-## Best Practices
+const sandbox = await compute.sandbox.create();
 
-### 1. Provider Selection
+// Create exec mode terminal for command tracking
+const terminal = await sandbox.terminal.create({ pty: false });
 
-Choose providers based on your use case:
+// Run build commands with tracking
+const install = await terminal.command.run('npm install');
+console.log('Install exit code:', install.exitCode);
 
-- **E2B**: Data science, ML, interactive development, full Python environment
-- **Vercel**: Web applications, APIs, serverless functions, long-running tasks
-- **Daytona**: Development workspaces, custom environments, team collaboration
+const build = await terminal.command.run('npm run build');
+console.log('Build output:', build.stdout);
 
-### 2. Resource Management
+// Run tests in background
+const tests = await terminal.command.run('npm test', { background: true });
+console.log('Tests started:', tests.status);
 
-Always clean up resources:
+// Wait for tests to complete
+await tests.wait(60); // 60 second timeout
+console.log('Tests completed:', tests.exitCode === 0 ? 'PASSED' : 'FAILED');
+console.log('Test output:', tests.stdout);
 
-```typescript
-const sandbox = ComputeSDK.createSandbox();
-try {
-  // Your code here
-  const result = await sandbox.execute('print("Hello")');
-} finally {
-  // Always clean up
-  await sandbox.kill();
-}
-```
+// List all commands
+const commands = await terminal.command.list();
+console.log(`Executed ${commands.length} commands`);
 
-### 3. Error Handling
+await terminal.destroy();
+await sandbox.destroy();
+```
 
-Implement comprehensive error handling:
+### Interactive Terminal Session
 
 ```typescript
-async function robustExecution(code: string) {
-  let sandbox;
-  try {
-    sandbox = ComputeSDK.createSandbox();
-    return await sandbox.execute(code);
-  } catch (error) {
-    console.error('Execution failed:', error.message);
-    throw error;
-  } finally {
-    if (sandbox) {
-      await sandbox.kill();
-    }
-  }
-}
-```
+import { compute } from 'computesdk';
+
+const sandbox = await compute.sandbox.create();
+
+// Create PTY terminal for interactive shell
+const pty = await sandbox.terminal.create({ 
+  pty: true, 
+  shell: '/bin/bash' 
+});
+
+// Collect all output
+let output = '';
+pty.on('output', (data) => {
+  output += data;
+  console.log(data);
+});
+
+pty.on('error', (error) => {
+  console.error('Terminal error:', error);
+});
+
+// Execute interactive commands
+pty.write('echo "Starting project setup"\n');
+pty.write('mkdir -p /workspace/myproject\n');
+pty.write('cd /workspace/myproject\n');
+pty.write('npm init -y\n');
+pty.write('npm install express\n');
+pty.write('echo "Setup complete"\n');
+
+// Wait for operations to complete
+await new Promise(resolve => setTimeout(resolve, 5000));
 
-### 4. Type Safety
+// Clean up
+await pty.destroy();
+await sandbox.destroy();
 
-Use TypeScript interfaces for better development experience:
+console.log('Complete output:', output);
+```
+
+### Using Different Providers
 
 ```typescript
-import { FilesystemComputeSandbox, TerminalComputeSandbox } from 'computesdk';
+import { compute } from 'computesdk';
 
-function requiresFilesystem(sandbox: FilesystemComputeSandbox) {
-  // TypeScript ensures filesystem operations are available
-  return sandbox.filesystem.readFile('/path/to/file');
-}
+// Use E2B for data science
+compute.setConfig({
+  provider: 'e2b',
+  e2b: { apiKey: process.env.E2B_API_KEY }
+});
+
+const e2bSandbox = await compute.sandbox.create();
+await e2bSandbox.runCode('import pandas as pd; print(pd.__version__)');
+await e2bSandbox.destroy();
+
+// Switch to Modal for GPU workloads
+compute.setConfig({
+  provider: 'modal',
+  modal: { 
+    tokenId: process.env.MODAL_TOKEN_ID,
+    tokenSecret: process.env.MODAL_TOKEN_SECRET
+  }
+});
+
+const modalSandbox = await compute.sandbox.create();
+await modalSandbox.runCode('import torch; print(torch.cuda.is_available())');
+await modalSandbox.destroy();
+```
+
+## Error Handling
 
-function requiresTerminal(sandbox: TerminalComputeSandbox) {
-  // TypeScript ensures terminal operations are available
-  return sandbox.terminal.create({ command: 'bash' });
+```typescript
+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');
+  }
 }
 ```
 
-## Contributing
+## Direct Mode (Advanced)
 
-We welcome contributions! Please see our [Contributing Guide](https://github.com/computesdk/computesdk/blob/main/CONTRIBUTING.md) for details.
+For advanced use cases where you want to bypass the gateway and use provider SDKs directly, see individual provider packages:
 
-### Adding New Providers
+- **[@computesdk/e2b](../e2b)** - E2B provider
+- **[@computesdk/modal](../modal)** - Modal provider
+- **[@computesdk/railway](../railway)** - Railway provider
+- **[@computesdk/daytona](../daytona)** - Daytona provider
 
-1. Implement the appropriate `ComputeSpecification` interface:
-   - `BaseComputeSpecification` for basic execution
-   - `FilesystemComputeSpecification` for filesystem support
-   - `TerminalComputeSpecification` for terminal support
-   - `FullComputeSpecification` for complete functionality
+Example direct mode usage:
 
-2. Add comprehensive tests covering all implemented interfaces
+```typescript
+import { e2b } from '@computesdk/e2b';
 
-3. Include documentation and examples
+const compute = e2b({ apiKey: 'your_api_key' });
+const sandbox = await compute.sandbox.create();
+```
 
-4. Submit a pull request
+## Building Custom Providers
 
-## License
+Want to add support for a new compute provider? See **[@computesdk/provider](../provider)** for the provider framework and documentation on building custom providers.
 
-MIT - see [LICENSE](https://github.com/computesdk/computesdk/blob/main/LICENSE) for details.
+## TypeScript Support
 
-## Support
+Full TypeScript support with comprehensive type definitions:
 
-- [GitHub Issues](https://github.com/computesdk/computesdk/issues)
-- [Documentation](https://github.com/computesdk/computesdk)
-- [Examples](https://github.com/computesdk/computesdk/tree/main/examples)
+```typescript
+import type { 
+  Sandbox,
+  SandboxInfo,
+  CodeResult,
+  CommandResult,
+  CreateSandboxOptions
+} from 'computesdk';
+```
 
----
+## License
 
-Made with ❤️ by the ComputeSDK team
+MIT