@computesdk/workbench

Interactive REPL for testing ComputeSDK sandbox operations with instant feedback and autocomplete.

Features

• 🚀 Zero ceremony - Just run commands, no sandbox ID management
• ✨ Tab autocomplete - All 100+ @computesdk/cmd functions autocomplete
• 🔄 Provider switching - Seamlessly switch between e2b, daytona, modal, etc.
• ⚡ Smart evaluation - Type npm.install('express') and it just runs
• 📊 Real-time feedback - See timing, output, and errors instantly

Installation

npm install -D @computesdk/workbench

# Install at least one provider
npm install @computesdk/e2b
# or any other provider

Quick Start

1. Configure credentials in .env:

# E2B Provider
E2B_API_KEY=e2b_your_api_key_here

# Daytona Provider
DAYTONA_API_KEY=your_daytona_api_key

2. Start workbench:

npx workbench

3. Run commands (autocomplete works!):

workbench> npm.install('express')
⏳ Creating sandbox with e2b...
✅ Sandbox ready (1.2s)
Running: npm install express
✅ Completed (3.2s)

workbench> git.clone('https://github.com/user/repo')
Running: git clone https://github.com/user/repo
✅ Completed (2.1s)

workbench> ls('/home')
Running: ls /home
total 8
drwxr-xr-x 3 user user 4096 Dec 12 19:00 node_modules
drwxr-xr-x 2 user user 4096 Dec 12 19:01 repo
✅ Completed (0.1s)

Commands

Workbench Commands

• provider <name> - Switch provider (e.g., provider e2b)
• providers - List all providers with status
• restart - Restart current sandbox
• destroy - Destroy current sandbox
• info - Show sandbox info (provider, uptime)
• env - Show environment/credentials status
• help - Show this help
• exit - Exit workbench

Each provider requires its package installed (e.g. @computesdk/e2b) and its credentials configured.

Running Commands

Just type any @computesdk/cmd function. Tab autocomplete works!

Package Managers:

npm.install('express')
npm.run('dev')
pnpm.install()
yarn.add('lodash')
pip.install('requests')

Git:

git.clone('https://...')
git.commit('Initial commit')
git.push()

Filesystem:

mkdir('/app/src')
ls('/home')
cat('/home/file.txt')
cp('/src', '/dest', { recursive: true })
rm('/file.txt')              // Remove file
rm.rf('/directory')          // Force remove anything
rm.auto('/path')             // Smart remove (auto-detects file vs directory)

Network:

curl('https://api.example.com')
wget('https://file.com/download.zip')

And 100+ more! Press Tab to explore.

Provider Switching

Switch between providers:

workbench> provider e2b
✅ Switched to e2b

workbench> npm.install('express')
⏳ Creating sandbox with e2b...
✅ Sandbox ready (1.2s)
Running: npm install express
✅ Completed (3.2s)

workbench> provider daytona
Destroy current sandbox? (y/N): y
✅ Switched to daytona

Creating and Switching Sandboxes

When you create a sandbox using create(), it automatically becomes your current active sandbox. All subsequent commands will run on this sandbox.

> create({ namespace: "h" })
✅ Switched to sandbox sandbox-123
{ sandboxId: 'sandbox-123', provider: 'e2b', metadata: {} }
e2b:sandbox-123>  // Prompt shows you're now on this sandbox

> ls('/home')  // Runs on sandbox-123

Switching Between Sandboxes

If you already have an active sandbox and create another one, the workbench will prompt you:

e2b:sandbox-456> create({ namespace: "prod" })
Switch to new sandbox? (Y/n): y
✅ Switched to sandbox sandbox-789
e2b:sandbox-789>

Press Enter or type "y" to switch. Type "n" to create the sandbox without switching to it.

Tab Autocomplete

Autocomplete works for all commands:

workbench> npm.<TAB>
install  run  init  uninstall

workbench> git.<TAB>
add  branch  checkout  clone  commit  diff  fetch  
init  log  pull  push  reset  stash  status

workbench> provider <TAB>
e2b  daytona  modal  runloop  vercel

Supported Providers

Install any combination of:

• @computesdk/e2b - E2B sandboxes
• @computesdk/daytona - Daytona workspaces
• @computesdk/modal - Modal containers
• @computesdk/runloop - Runloop instances
• @computesdk/vercel - Vercel functions
• @computesdk/cloudflare - Cloudflare Workers
• @computesdk/codesandbox - CodeSandbox boxes
• @computesdk/blaxel - Blaxel environments
• @computesdk/northflank - Northflank deployment services

Environment Variables

Set provider credentials in .env:

# E2B
E2B_API_KEY=e2b_xxx

# Daytona
DAYTONA_API_KEY=xxx

# Modal
MODAL_TOKEN_ID=xxx
MODAL_TOKEN_SECRET=xxx

# Runloop
RUNLOOP_API_KEY=xxx

# Vercel
VERCEL_TOKEN=xxx
VERCEL_TEAM_ID=xxx
VERCEL_PROJECT_ID=xxx

# Cloudflare
CLOUDFLARE_API_TOKEN=xxx
CLOUDFLARE_ACCOUNT_ID=xxx

# CodeSandbox
CSB_API_KEY=xxx

# Blaxel
BL_API_KEY=xxx
BL_WORKSPACE=xxx

# Northflank
NORTHFLANK_TOKEN=nf_xxx
NORTHFLANK_PROJECT_ID=my-project
NORTHFLANK_TEAM_ID=xxx       # optional — required only for organization API tokens
NORTHFLANK_API_URL=xxx       # optional — defaults to https://api.northflank.com

Tips

• Command history: Use ↑/↓ arrows to navigate previous commands
• Exit gracefully: Type exit or .exit, optionally destroy sandbox
• Check status: Run env to see which providers are configured
• Auto-create: First command automatically creates a sandbox
• Stay in context: Workbench maintains "current sandbox" - no IDs to track

Debugging SDK Tests

The workbench is a full Node.js REPL with the ComputeSDK pre-loaded. You can reproduce any SDK test by calling the same methods interactively.

SDK to Workbench Mapping

| SDK Test Code | Workbench Equivalent | |---------------|---------------------| | sandbox.runCommand('echo hi') | runCommand('echo hi') or getInstance().runCommand(...) | | sandbox.filesystem.readFile(path) | filesystem.readFile(path) | | sandbox.getInfo() | sandboxInfo() | | sandbox.getUrl({ port }) | getUrl({ port: 3000 }) |

Example: Reproducing a Failing Test

If this test fails:

// From provider-compatibility.test.ts
it('command with streaming callbacks', async () => {
  let stdoutCalled = false;
  const result = await sandbox.runCommand('echo "hello"', {
    onStdout: () => { stdoutCalled = true; },
  });
  expect(stdoutCalled).toBe(true);
});

Reproduce it in workbench:

> ls('/home')  // Auto-creates sandbox
> const sandbox = getInstance()
> let stdoutCalled = false
> const result = await sandbox.runCommand('echo "hello"', {
    onStdout: (data) => { console.log('STDOUT:', data); stdoutCalled = true }
  })
> stdoutCalled  // Should be true
> result

Verbose Mode

Enable verbose mode to see full response objects and WebSocket debug info:

> verbose()  // Toggle on - shows full results and WebSocket frames
> ls('/home')
> verbose()  // Toggle off

Direct Shell Commands

Prefix with $ to run shell commands directly (bypasses @computesdk/cmd):

> $echo "hello" | tr 'a-z' 'A-Z'
> $for i in 1 2 3; do echo $i; done

License

MIT