Computesdk

---

#What is ComputeSDK?

ComputeSDK is the open, multi-provider benchmark harness for cloud infrastructure. It is the engine behind ComputeSDK Benchmarks and a unified TypeScript SDK for running code in remote sandboxes.

The same API lets you:

• Benchmark providers fairly — run the same workload on E2B, Modal, Vercel, and dozens of others, then publish reproducible results.
• Build provider-agnostic apps — switch sandboxes without changing application code for AI agents, code-execution platforms, and developer tools.

Whether you're comparing infrastructure or running it, ComputeSDK provides one unified API.

Perfect for:

• 📊 Benchmarking infrastructure providers
• 🤖 AI code execution agents
• 📊 Data science platforms
• 🎓 Educational coding environments
• 🧪 Testing & CI/CD systems
• 🔧 Developer tools

#Quick Start

npm install computesdk @computesdk/e2b

Configure a provider and use the SDK:

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();

const result = await sandbox.runCommand('python -c "print(\'Hello World!\')"');
console.log(result.stdout); // "Hello World!"

await sandbox.destroy();

#Features

• 🧪 Open benchmark harness - Run reproducible workloads across providers and publish independent benchmarks (ComputeSDK Benchmarks)
• 🔄 Multi-provider support - E2B, Modal, Daytona, Vercel, and more
• 📁 Filesystem operations - Read, write, create directories across providers
• 🖥️ Command execution - Run shell commands in sandboxes
• 🧵 Terminals - Interactive (PTY) and exec-mode command tracking
• 🛡️ Type-safe - Full TypeScript support with comprehensive error handling
• 🔧 Extensible - Easy to add custom providers via @computesdk/provider

#Supported Providers

Install provider packages and pass instances into compute.setConfig:

#Configuration

#Direct Provider Mode

Pass a provider instance directly to setConfig():

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();

#Multi-Provider Configuration

Configure multiple providers for resilience and routing:

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

compute.setConfig({
  providers: [
    e2b({ apiKey: process.env.E2B_API_KEY }),
    modal({
      tokenId: process.env.MODAL_TOKEN_ID,
      tokenSecret: process.env.MODAL_TOKEN_SECRET,
    }),
  ],
  providerStrategy: 'priority', // or 'round-robin'
  fallbackOnError: true,
});

// Uses configured strategy
const sandbox = await compute.sandbox.create();

// Force a specific provider for one call
const modalSandbox = await compute.sandbox.create({ provider: 'modal' });

#Switching Providers at Runtime

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

// Use E2B for data science
compute.setConfig({
  provider: e2b({ apiKey: process.env.E2B_API_KEY }),
});

const e2bSandbox = await compute.sandbox.create();
await e2bSandbox.runCommand('python -c "import pandas as pd"');
await e2bSandbox.destroy();

// Switch to Modal for GPU workloads
compute.setConfig({
  provider: modal({
    tokenId: process.env.MODAL_TOKEN_ID,
    tokenSecret: process.env.MODAL_TOKEN_SECRET,
  }),
});

const modalSandbox = await compute.sandbox.create();
await modalSandbox.runCommand('python -c "import torch; print(torch.cuda.is_available())"');
await modalSandbox.destroy();

#Core API

#Sandbox Management

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

// Create with options
const sandbox = await compute.sandbox.create({
  runtime: 'python',
  timeout: 300000,
  metadata: { userId: '123' }
});

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

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

// Destroy sandbox
await sandbox.destroy();

#Command Execution

// Execute Python code
const result = await sandbox.runCommand('python -c "print(\'Hello\')"');
console.log(result.stdout);
console.log(result.exitCode);

// Run shell commands
const cmd = await sandbox.runCommand('npm install express');
console.log(cmd.stdout);
console.log(cmd.exitCode);

#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/data');

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

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

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

#Example: Data Science Workflow

import { compute } from 'computesdk';

const sandbox = await compute.sandbox.create({ runtime: 'python' });

// Create project structure
await sandbox.filesystem.mkdir('/analysis');
await sandbox.filesystem.mkdir('/analysis/data');

// Write input data
const csvData = `name,age,city
Alice,25,New York
Bob,30,San Francisco`;

await sandbox.filesystem.writeFile('/analysis/data/people.csv', csvData);

// Write the analysis script
await sandbox.filesystem.writeFile('/analysis/analyze.py', `
import json
import pandas as pd

df = pd.read_csv('/analysis/data/people.csv')
print(f"Average age: {df['age'].mean()}")

results = {'average_age': df['age'].mean()}
with open('/analysis/results.json', 'w') as f:
    json.dump(results, f)
`);

// Run it
const result = await sandbox.runCommand('python /analysis/analyze.py');
console.log(result.stdout);

// Read results
const results = await sandbox.filesystem.readFile('/analysis/results.json');
console.log('Results:', JSON.parse(results));

await sandbox.destroy();

#Provider Packages

Install the provider packages you need and pass their instances into compute.setConfig:

npm install @computesdk/archil           # Archil provider
npm install @computesdk/beam             # Beam provider
npm install @computesdk/blaxel           # Blaxel provider
npm install @computesdk/buddy            # Buddy provider
npm install @computesdk/cloud-run        # Google Cloud Run provider
npm install @computesdk/cloudflare       # Cloudflare provider
npm install @computesdk/codesandbox      # CodeSandbox provider
npm install @computesdk/createos-sandbox # CreateOS VM sandbox provider
npm install @computesdk/daytona          # Daytona provider
npm install @computesdk/declaw           # Declaw provider
npm install @computesdk/e2b              # E2B provider
npm install @computesdk/freestyle        # Freestyle provider
npm install @computesdk/givemeanode      # givemeanode provider
npm install @computesdk/hopx             # HopX provider
npm install @computesdk/isorun           # Isorun provider
npm install @computesdk/lightning        # Lightning AI provider
npm install @computesdk/modal            # Modal provider
npm install @computesdk/microsandbox     # Local and cloud microsandbox provider
npm install @computesdk/miosa            # MIOSA provider
npm install @computesdk/mosaic           # Mosaic provider
npm install @computesdk/northflank       # Northflank provider
npm install @computesdk/run-cloud        # Run Cloud Firecracker sandbox provider
npm install @computesdk/runloop          # Runloop provider
npm install @computesdk/sail             # Sail provider
npm install @computesdk/sandbox0         # Sandbox0 provider
npm install @computesdk/superserve       # Superserve provider
npm install @computesdk/tensorlake       # Tensorlake provider
npm install @computesdk/upstash          # Upstash provider
npm install @computesdk/vercel           # Vercel provider

You can also use a provider's callable form directly, bypassing compute.setConfig:

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

const e2bCompute = e2b({ apiKey: process.env.E2B_API_KEY });
const sandbox = await e2bCompute.sandbox.create();

See individual provider READMEs for details:

• @computesdk/archil - Disk-attached command-execution sandboxes
• @computesdk/beam - Serverless cloud sandboxes
• @computesdk/blaxel - Agent sandboxes with custom images
• @computesdk/buddy - Persistent Ubuntu sandboxes for agents, booting in milliseconds, with preview URLs and snapshots
• @computesdk/cloud-run - Google Cloud Run sandboxes
• @computesdk/cloudflare - Edge computing sandboxes
• @computesdk/codesandbox - Collaborative development
• @computesdk/createos-sandbox - NodeOps VM sandboxes, with pause/resume/fork snapshots and a native-handle escape hatch
• @computesdk/daytona - Development workspaces
• @computesdk/declaw - Isolated cloud sandboxes
• @computesdk/e2b - Data science, Python/Node.js, terminals
• @computesdk/freestyle - Full Linux VMs for long-running agent tasks, with snapshots and persistence
• @computesdk/givemeanode - Very fast microVM sandboxes, from any container image
• @computesdk/hopx - Fast ephemeral sandboxes
• @computesdk/isorun - Code execution with snapshot support
• @computesdk/lightning - Lightning AI cloud sandboxes for command execution and filesystem access
• @computesdk/modal - GPU computing, ML inference
• @computesdk/miosa - Snapshot-backed Firecracker microVMs with native filesystem, preview URLs, and checkpoints
• @computesdk/mosaic - Firecracker microVMs with preview URLs, snapshots, and container-image environments
• @computesdk/neevcloud - Secure cloud sandboxes with command execution, filesystem, and preview URLs
• @computesdk/northflank - Cloud sandboxes with preview URLs
• @computesdk/run-cloud - Fast Firecracker microVM sandboxes with filesystem and snapshot support
• @computesdk/runloop - Code execution, automation
• @computesdk/sandbox0 - Fast persistent sandboxes with native filesystem access
• @computesdk/superserve - Firecracker microVM sandboxes
• @computesdk/tensorlake - Stateful MicroVM sandboxes for agentic applications, with snapshot support
• @computesdk/upstash - Ephemeral and persistent sandboxes
• @computesdk/vercel - Serverless functions

#Building Custom Providers

Want to add support for a new compute provider? See @computesdk/provider for the provider framework:

import { defineProvider } from '@computesdk/provider';

export const myProvider = defineProvider({
  name: 'my-provider',
  defaultMode: 'direct',
  methods: {
    sandbox: {
      create: async (config, options) => {
        // Your implementation
      },
      // ... other methods
    }
  }
});

#Documentation

• 📖 Full Documentation - Complete guides and API reference
• 🚀 Getting Started - Quick setup guide
• 🎯 Providers - Provider-specific documentation

#TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type { 
  Sandbox,
  SandboxInfo,
  CodeResult,
  CommandResult,
  CreateSandboxOptions
} from 'computesdk';

#Contributing

ComputeSDK is open source and welcomes contributions!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

#Community & Support

• 💬 GitHub Discussions - Ask questions and share ideas
• 🐛 GitHub Issues - Report bugs and request features

#License

MIT License - see the LICENSE file for details.

---