@computesdk/codesandbox

@computesdk/codesandbox

CodeSandbox provider for ComputeSDK - Execute code in secure, isolated CodeSandbox environments with full filesystem and development environment support.

Installation

npm install @computesdk/codesandbox

Setup

• Get your CodeSandbox API key from codesandbox.io/t/api
• Set the environment variable:

export CSB_API_KEY=your_api_key_here

Quick Start

Gateway Mode (Recommended)

Use the gateway for zero-config auto-detection:

import { compute } from 'computesdk';

// Auto-detects CodeSandbox from CSB_API_KEY environment variable
const sandbox = await compute.sandbox.create();

// Execute JavaScript/Node.js code
const result = await sandbox.runCommand(`node - <<'JS'
const message = "Hello from CodeSandbox!";
console.log(message);

const data = { users: 3, tasks: 15 };
console.log(JSON.stringify(data, null, 2));
JS`);

console.log(result.stdout);
// Output:
// Hello from CodeSandbox!
// {
//   "users": 3,
//   "tasks": 15
// }

// Execute Python code
const pythonResult = await sandbox.runCommand(`python - <<'PY'
import json
data = {"framework": "CodeSandbox", "language": "Python"}
print(json.dumps(data, indent=2))
print(f"Running in: {data['framework']}")
PY`);

console.log(pythonResult.stdout);
// Output:
// {
//   "framework": "CodeSandbox",
//   "language": "Python"
// }
// Running in: CodeSandbox

await sandbox.destroy();

Direct Mode

For direct SDK usage without the gateway:

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

const compute = codesandbox({ 
  apiKey: process.env.CSB_API_KEY,
  templateId: 'universal', // Optional: specify template
  timeout: 600000 // 10 minutes
});

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

const result = await sandbox.runCommand('node -e "console.log(\"Hello from CodeSandbox!\")"');
console.log(result.stdout);

await sandbox.destroy();

Configuration

Environment Variables

export CSB_API_KEY=your_api_key_here

Configuration Options

interface CodesandboxConfig {
  /** CodeSandbox API key - if not provided, will use CSB_API_KEY env var */
  apiKey?: string;
  /** Template to use for new sandboxes (defaults to universal template) */
  templateId?: string;
  /** Default runtime environment */
  runtime?: 'python' | 'node';
  /** Execution timeout in milliseconds */
  timeout?: number;
}

Features

• ✅ Code Execution - Python and Node.js runtime support
• ✅ Command Execution - Run shell commands in sandbox
• ✅ Filesystem Operations - Full file system access via CodeSandbox API
• ✅ Template Support - Create sandboxes from custom templates
• ✅ Auto Runtime Detection - Automatically detects Python vs Node.js
• ✅ Development Environment - Full development setup with package managers
• ✅ Persistence - Files persist across hibernation/resume cycles
• ✅ Snapshot/Resume - Fast sandbox restoration from snapshots

API Reference

Code Execution

// Execute Node.js code
const result = await sandbox.runCommand(`node - <<'JS'
const fs = require('fs');
const data = { timestamp: Date.now() };
console.log('Processing data:', JSON.stringify(data));
JS`);

// Execute Python code  
const result = await sandbox.runCommand(`python - <<'PY'
import datetime
import json

data = {'timestamp': datetime.datetime.now().isoformat()}
print('Processing data:', json.dumps(data))
PY`);

// Auto-detection (based on code patterns)
const result = await sandbox.runCommand('python -c "print(\"Auto-detected as Python\")"');

Command Execution

// List files
const result = await sandbox.runCommand('ls', ['-la']);

// Install Node.js packages
const result = await sandbox.runCommand('npm', ['install', 'lodash']);

// Install Python packages
const result = await sandbox.runCommand('pip', ['install', 'requests']);

// Run development server
const result = await sandbox.runCommand('npm', ['run', 'dev']);

Filesystem Operations

// Write file
await sandbox.filesystem.writeFile('/project/workspace/app.js', `
const express = require('express');
const app = express();

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

app.listen(3000, () => {
  console.log('Server running on port 3000');
});
`);

// Read file
const content = await sandbox.filesystem.readFile('/project/workspace/package.json');

// Create directory
await sandbox.filesystem.mkdir('/project/workspace/src');

// List directory contents
const files = await sandbox.filesystem.readdir('/project/workspace');

// Check if file exists
const exists = await sandbox.filesystem.exists('/project/workspace/app.js');

// Remove file or directory
await sandbox.filesystem.remove('/project/workspace/temp.txt');

Sandbox Management

// Get sandbox info
const info = await sandbox.getInfo();
console.log(info.id, info.provider, info.status);

// Resume existing sandbox
const existing = await compute.sandbox.getById(provider, 'sandbox-id');

// Hibernate sandbox (saves state)
await compute.sandbox.destroy(provider, 'sandbox-id'); // Actually hibernates

// Note: CodeSandbox doesn't support listing all sandboxes
// Each sandbox is managed individually

Best Practices

• Resource Management: Use hibernation instead of destroying sandboxes to preserve state
• Error Handling: Use try-catch blocks for robust error handling
• Timeouts: Set appropriate timeouts for long-running tasks
• File Organization: Organize files in /project/workspace/ directory
• Template Usage: Use appropriate templates for your project type
• API Key Security: Never commit API keys to version control
• Snapshot Management: Leverage CodeSandbox's snapshot/resume capabilities

Support

• CodeSandbox Documentation
• ComputeSDK Issues
• CodeSandbox Support

License

MIT