computesdk

The universal SDK for running code in remote sandboxes.

Gateway/control-plane transport has been removed from computesdk. Configure compute with provider or providers, or use provider packages directly.

Installation

npm install computesdk

Quick Start

Direct Provider Mode (Recommended)

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

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

// Clean up
await sandbox.destroy();

Explicit Configuration

For more control, configure compute with an explicit provider:

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

compute.setConfig({
  provider: modal({
    tokenId: process.env.MODAL_TOKEN_ID,
    tokenSecret: process.env.MODAL_TOKEN_SECRET,
  }),
});

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: 'round-robin', // or 'priority'
  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' });

Supported Providers

Use provider packages directly to create provider instances:

| 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_API_KEY, RAILWAY_PROJECT_ID, RAILWAY_ENVIRONMENT_ID | 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_SANDBOX_URL, CLOUDFLARE_SANDBOX_SECRET | Edge computing | | CodeSandbox | CSB_API_KEY | Collaborative development |

Example imports:

import { e2b } from '@computesdk/e2b';
import { modal } from '@computesdk/modal';
import { vercel } from '@computesdk/vercel';
import { daytona } from '@computesdk/daytona';

API Reference

Configuration

compute.setConfig(config)

Configure compute with provider or providers.

compute.setConfig({
  provider: e2b({
    apiKey: process.env.E2B_API_KEY,
  }),
});

compute(...) callable mode is also supported:

const scopedCompute = compute({
  provider: vercel({
    token: process.env.VERCEL_TOKEN,
    teamId: process.env.VERCEL_TEAM_ID,
    projectId: process.env.VERCEL_PROJECT_ID,
  }),
});

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

Multi-provider config shape:

compute.setConfig({
  providers: [e2b({...}), modal({...})],
  providerStrategy: 'priority', // default: 'priority'
  fallbackOnError: true,        // default: true
});

You can also combine both provider and providers:

compute.setConfig({
  provider: e2b({...}),         // primary provider (first choice)
  providers: [modal({...})],    // fallback/secondary providers
});

When both are present, provider is treated as the primary provider and is placed first.

Sandbox Management

compute.sandbox.create(options?)

Create a new sandbox.

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',
});

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 - Human-readable name for the sandbox

Note: Not every provider honors every option. Support for fields like name, metadata, and envs depends on the underlying provider SDK — some pass them through, some map them to a different field, and some ignore them silently. Check your provider package's README for the exact set of options it respects.

compute.sandbox.getById(sandboxId)

Get an existing sandbox by ID.

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

Sandbox Operations

sandbox.runCommand(command, options?)

Run a shell command.

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,
});

sandbox.destroy()

Destroy the sandbox and clean up resources.

await sandbox.destroy();

Filesystem Operations

The sandbox provides full filesystem access:

sandbox.filesystem.writeFile(path, content)

Write a file to the sandbox.

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

sandbox.filesystem.readFile(path)

Read a file from the sandbox.

const content = await sandbox.filesystem.readFile('/tmp/hello.py');
console.log(content); // 'print("Hello World")'

sandbox.filesystem.mkdir(path)

Create a directory.

await sandbox.filesystem.mkdir('/tmp/mydir');

sandbox.filesystem.readdir(path)

List directory contents.

const files = await sandbox.filesystem.readdir('/tmp');
console.log(files); // [{ name: 'hello.py', type: 'file', size: 123 }, ...]

sandbox.filesystem.exists(path)

Check if a file or directory exists.

const exists = await sandbox.filesystem.exists('/tmp/hello.py');
console.log(exists); // true

sandbox.filesystem.remove(path)

Remove a file or directory.

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

Examples

Multi-Step Build Process

import { compute } from 'computesdk';

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

// 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 source code
await sandbox.filesystem.writeFile('/app/src/index.js', `
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.json({ message: 'Hello World!' });
});

console.log('Server ready!');
`);

// Install dependencies
const installResult = await sandbox.runCommand('npm install', { cwd: '/app' });
console.log('Install:', installResult.stdout);

// Run the app
const runResult = await sandbox.runCommand('node src/index.js', { cwd: '/app' });

console.log(runResult.stdout);

await sandbox.destroy();

Using Different Providers

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; print(pd.__version__)"');
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();

Error Handling

try {
  const sandbox = await compute.sandbox.create();
  const result = await sandbox.runCommand('invalid python code');
} catch (error) {
  console.error('Execution failed:', error.message);
  
  // Check for specific error types
  if (error.message.includes('No provider instance configured')) {
    console.error('Configure compute.setConfig({ provider: e2b({...}) }) first');
  }
}

Provider Packages (Advanced)

For advanced use cases where you want to use provider SDKs directly, see individual provider packages:

• @computesdk/e2b - E2B provider
• @computesdk/modal - Modal provider
• @computesdk/railway - Railway provider
• @computesdk/daytona - Daytona provider

Example direct mode usage:

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

const compute = e2b({ apiKey: 'your_api_key' });
const sandbox = await compute.sandbox.create();

Building Custom Providers

Want to add support for a new compute provider? See @computesdk/provider for the provider framework and documentation on building custom providers.

TypeScript Support

Full TypeScript support with comprehensive type definitions:

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

License

MIT