A JavaScript SDK for executing multi-language code in controlled sandboxes, supporting both synchronous and asynchronous modes, as well as multi-language kernels (Python, R, Node.js, Deno/TypeScript, Java/IJAVA, Bash)
npm install @scalebox/sdk








A JavaScript SDK for executing multi-language code in controlled sandboxes, supporting both synchronous and asynchronous modes, as well as multi-language kernels (Python, R, Node.js, Deno/TypeScript, Java/IJAVA, Bash). Comprehensive real-world test cases and scripts are provided.
any๐ Session API Documentation | ๐ ไธญๆๆๆกฃ
Sandbox and asynchronous AsyncSandbox execution


``bashUsing npm
npm install @scalebox/sdk
Configuration
$3
The SDK supports reading configuration from environment variables or
.env file:| Variable | Required | Description | Default |
|----------|----------|-------------|---------|
|
SCALEBOX_API_KEY | Yes* | API key for authentication | - |
| SCALEBOX_ACCESS_TOKEN | Yes* | Access token (alternative to API key) | - |
| SCALEBOX_API_URL | No | API endpoint URL | https://api.scalebox.dev |
| SCALEBOX_DOMAIN | No | Custom domain for sandboxes | - |*Either
SCALEBOX_API_KEY or SCALEBOX_ACCESS_TOKEN must be provided.$3
Using environment variables:
`bash
export SCALEBOX_API_KEY=your_api_key_here
export SCALEBOX_API_URL=https://api.scalebox.dev # optional
`Using .env file:
`env
.env
SCALEBOX_API_KEY=your_api_key_here
SCALEBOX_API_URL=https://api.scalebox.dev # optional
`Using code configuration:
`javascript
import { Sandbox } from '@scalebox/sdk'const sandbox = await Sandbox.create('code-interpreter', {
apiKey: 'your_api_key_here',
apiUrl: 'https://api.scalebox.dev' // optional
})
`Quick Start
$3
The simplest way to execute code - everything is handled automatically!
`typescript
import { Session } from '@scalebox/sdk'// Simple execution
const result = await Session.run({
code: 'print("Hello, Scalebox!")',
language: 'python'
})
console.log(result.text) // Hello, Scalebox!
`Multi-step workflow with session reuse (10-100x faster):
`typescript
// Step 1: Initialize with packages
const step1 = await Session.run({
code: 'import pandas as pd; import numpy as np',
packages: ['pandas', 'numpy'],
keepAlive: true // Keep session for reuse
})// Step 2: Upload and process data (reuses session, packages already installed!)
const step2 = await Session.run({
code: 'df = pd.read_csv("data.csv"); print(df.head())',
sessionId: step1.sessionId,
files: { 'data.csv': csvData }
})
// Step 3: Continue analysis
const step3 = await Session.run({
code: 'print(df.describe())',
sessionId: step1.sessionId
})
// Close when done
await Session.close(step1.sessionId!)
`Pause/Resume for cost optimization:
`typescript
// Create session and process data
const result = await Session.run({
code: 'import pandas as pd; df = pd.read_csv("data.csv")',
files: { 'data.csv': csvData },
packages: ['pandas'],
keepAlive: true
})// Pause to save resources during long wait for external data
await Session.pause(result.sessionId!)
// Later: automatically resumed when reusing
const result2 = await Session.run({
code: 'print(df.describe())',
sessionId: result.sessionId // โ
Automatically resumes
})
// Close when done
await Session.close(result.sessionId!)
`Real-time progress tracking:
`typescript
const result = await Session.run({
code: pythonCode,
packages: ['pandas', 'matplotlib'],
onProgress: (progress) => {
console.log([${progress.stage}] ${progress.percent}% - ${progress.message})
}
})// Check performance insights
console.log('Timing:', result.timing)
console.log('Bottleneck:', result.insights.bottleneck)
console.log('Suggestions:', result.insights.suggestions)
`Object storage mount (S3-compatible):
`typescript
// Create session with object storage mounted
const result = await Session.run({
code: ,
objectStorage: {
uri: 's3://my-bucket/data/',
mountPoint: '/mnt/oss',
accessKey: 'YOUR_ACCESS_KEY',
secretKey: 'YOUR_SECRET_KEY',
region: 'ap-east-1',
endpoint: 'https://s3.ap-east-1.amazonaws.com'
}
})
`๐ Complete Session API Guide | ๐ ๅฎๆดไธญๆๆๅ | ๐ More Examples
$3
For fine-grained control over sandbox lifecycle:
`javascript
import { Sandbox } from '@scalebox/sdk'const sandbox = await Sandbox.create('code-interpreter', {
timeoutMs: 300000, // 5 minutes
metadata: { test: 'example' }
})
// Check sandbox status
const isRunning = await sandbox.isRunning()
console.log('Sandbox is running:', isRunning)
// Get sandbox information
// โ ๏ธ Note: getInfo() returns public sandbox metadata
// Internal properties like envdAccessToken and sandboxDomain are excluded for security
// Use sandbox.sandboxId, sandbox.sandboxDomain directly if needed
const info = await sandbox.getInfo()
console.log('Sandbox info:', info)
// Filesystem operations
const files = await sandbox.files.list("/")
console.log('Files:', files)
// Command execution
const result = await sandbox.commands.run('echo "Hello World"')
console.log('Command output:', result.stdout)
// Cleanup
await sandbox.kill()
`Quick Start (Code Interpreter)
`javascript
import { CodeInterpreter } from '@scalebox/sdk'async function main() {
// โ
Recommended: Use CodeInterpreter.create() static method
const interpreter = await CodeInterpreter.create({
templateId: 'code-interpreter'
})
const exec = await interpreter.runCode("print('hello from interpreter')", { language: "python" })
console.log(exec.logs.stdout)
await interpreter.close()
}
main()
`API Examples
$3
`javascript
import { Sandbox } from '@scalebox/sdk'// Create sandbox
const sandbox = await Sandbox.create('code-interpreter', {
timeoutMs: 300000,
metadata: { project: 'my-app' },
envs: { NODE_ENV: 'production' }
})
// Create sandbox with object storage mount
const sandboxWithOSS = await Sandbox.create('code-interpreter', {
timeoutMs: 300000,
objectStorage: {
uri: 's3://my-bucket/data/',
mountPoint: '/mnt/oss',
accessKey: 'YOUR_ACCESS_KEY',
secretKey: 'YOUR_SECRET_KEY',
region: 'ap-east-1',
endpoint: 'https://s3.ap-east-1.amazonaws.com'
}
})
// Object storage is now mounted at /mnt/oss
// Connect to existing sandbox
const connectedSandbox = await Sandbox.connect('sandbox-id')
// List all sandboxes
const paginator = Sandbox.list()
while (paginator.hasNext) {
const sandboxes = await paginator.nextItems()
console.log(sandboxes)
}
// Sandbox operations
await sandbox.setTimeout(600000) // 10 minutes
await sandbox.betaPause() // Pause sandbox
await sandbox.kill() // Close sandbox
`$3
Control where your sandbox is scheduled based on geographical preferences. By default, the system uses load-balanced scheduling across all available clusters.
`javascript
import { Sandbox, SandboxApi } from '@scalebox/sdk'// Get available regions
const regions = await SandboxApi.getScaleboxRegions()
console.log('Available regions:', regions)
// Output: [{ id: 'us-east', name: 'US East (N. Virginia)' }, ...]
// Auto-detect region from source IP
const sandbox1 = await Sandbox.create('code-interpreter', {
locality: {
autoDetect: true // Infers region from your IP address
}
})
// Specify a preferred region (best-effort, allows fallback)
const sandbox2 = await Sandbox.create('code-interpreter', {
locality: {
region: 'us-east' // Prefers us-east, but falls back if unavailable
}
})
// WARNING: Hard constraint - use with caution
// This will fail with a 409 Conflict error if the region is unavailable
const sandbox3 = await Sandbox.create('code-interpreter', {
locality: {
region: 'us-east',
force: true // Hard constraint - may cause creation failures
}
})
`Important Notes:
- Default behavior: If
locality is not specified, the system uses load-balanced scheduling (recommended for To B products to avoid single-point overheating)
- Best-effort mode (force: false, default): If the preferred region is unavailable, the system gracefully falls back to other available regions
- Hard constraint mode (force: true): Sandbox creation will fail with a 409 Conflict error if the requested region is unavailable, even if other regions have capacity. WARNING: Use with caution.
- Use cases for force: true: Strict compliance requirements, regulatory constraints, or data residency requirements
- Recommended: Use force: false (default) for most use cases to ensure high availability$3
Pause sandboxes to save compute resources while preserving filesystem state. Paused sandboxes don't consume CPU or memory, only storage.
`javascript
// Pause a running sandbox
await sandbox.betaPause()
console.log('Sandbox paused - no compute costs')// Resume paused sandbox using connect (unified endpoint)
// connect() automatically resumes if paused, or connects if running
await sandbox.connect()
console.log('Sandbox resumed and ready')
// Resume with new timeout
await sandbox.connect({ timeoutMs: 900000 }) // 15 minutes
// Check sandbox status
const info = await sandbox.getInfo()
console.log('Status:', info.status) // 'running' | 'paused' | 'stopped'
// Static connect method (auto-resumes if paused)
const connectedSandbox = await Sandbox.connect(sandboxId)
`Benefits:
- Cost optimization: Paused sandboxes only charge for storage, not CPU/RAM
- State preservation: Files, installed packages, and filesystem state are preserved
- Automatic resume: Use
connect() to automatically resume paused sandboxes
- Timeout management: Update timeout when resumingUse cases:
- Long idle periods between executions
- Batch processing with gaps
- Cost optimization for infrequently used sandboxes
$3
`javascript
// Read file
const content = await sandbox.files.read('/path/to/file.txt')// Write file
await sandbox.files.write('/path/to/file.txt', 'Hello World')
// List directory
const files = await sandbox.files.list('/home/user')
// Create directory
await sandbox.files.makeDir('/home/user/newdir')
// Move file
await sandbox.files.move('/old/path', '/new/path')
// Remove file
await sandbox.files.remove('/path/to/file.txt')
`$3
`javascript
// Execute command synchronously
const result = await sandbox.commands.run('ls -la')
console.log(result.stdout)
console.log(result.stderr)
console.log(result.exitCode)// Execute command in background
const handle = await sandbox.commands.run('long-running-command', {
background: true
})
// Wait for command to complete
const finalResult = await handle.wait()
// Kill command
await handle.kill()
`$3
`javascript
// Start pseudo-terminal
const pty = await sandbox.pty.start({
cwd: '/home/user',
envs: { PATH: '/usr/bin:/bin' }
})// Send data
await pty.send('echo "Hello from PTY"')
// Wait for output
await pty.wait()
`Multi-Language Examples
- Python: language: "python"
- R: language: "r"
- Node.js: language: "nodejs"
- Deno/TypeScript: language: "typescript"
- Java (IJAVA/pure Java): language: "ijava" or language: "java"
- Bash: language: "bash"Example (Node.js):
`javascript
import { Sandbox } from '@scalebox/sdk'const sbx = await Sandbox.create()
const code =
x=\${x}\);
const result = await sbx.runCode(code, { language: "nodejs" })
console.log(result.logs.stdout)
`Example (R):
`javascript
import { Sandbox } from '@scalebox/sdk'const sbx = await Sandbox.create()
const code =
const res = await sbx.runCode(code, { language: "r" })
console.log(res.logs.stdout)
`Example (Deno/TypeScript):
`javascript
import { Sandbox } from '@scalebox/sdk'const sbx = await Sandbox.create()
const ts =
const res = await sbx.runCode(ts, { language: "typescript" })
console.log(res.logs.stdout)
`Example (Java/IJAVA):
`javascript
import { Sandbox } from '@scalebox/sdk'const sbx = await Sandbox.create()
const code =
const res = await sbx.runCode(code, { language: "java" })
console.log(res.logs.stdout)
`Example (Bash):
`javascript
import { Sandbox } from '@scalebox/sdk'const sbx = await Sandbox.create()
const res = await sbx.runCode("echo 'Hello from Bash'", { language: "bash" })
console.log(res.logs.stdout)
`Context Management
Context allows reusing variables/state across multiple executions using real gRPC service:
`javascript
import { CodeInterpreter } from '@scalebox/sdk'// โ
Recommended: Use static create method
const interpreter = await CodeInterpreter.create()
// Create context (using gRPC)
const ctx = await interpreter.createCodeContext({ language: "python", cwd: "/tmp" })
await interpreter.runCode("counter = 0", { language: "python", context: ctx })
await interpreter.runCode("counter += 1; print(counter)", { language: "python", context: ctx })
// Destroy context (using gRPC)
await interpreter.destroyContext(ctx)
// Manage multiple contexts
const pythonCtx = await interpreter.createCodeContext({ language: "python" })
const jsCtx = await interpreter.createCodeContext({ language: "nodejs" })
console.log('Active contexts:', interpreter.getContexts().length)
`Callbacks (Optional)
`javascript
import { Sandbox } from '@scalebox/sdk'const sbx = await Sandbox.create()
function onStdout(msg) {
console.log("STDOUT:", msg.content)
}
function onStderr(msg) {
console.log("STDERR:", msg.content)
}
function onResult(res) {
console.log("RESULT formats:", Object.keys(res.formats))
}
function onError(err) {
console.log("ERROR:", err.name, err.value)
}
await sbx.runCode(
"print('with callbacks')",
{
language: "python",
onStdout,
onStderr,
onResult,
onError
}
)
`Result Formats
Result may contain the following data fields:
- text, html, markdown, svg, png, jpeg, pdf, latex
- jsonData, javascript, data, chart
- executionCount, isMainResult, extraYou can view available formats via
Object.keys(result.formats).Running Tests
The test/ directory contains comprehensive real-world use cases covering:
- Synchronous and asynchronous comprehensive use cases
- Multi-language kernels (Python, R, Node.js, Deno/TypeScript, Java/IJAVA, Bash)
- Context management, callbacks, and result formats`bash
Run all tests
npm testRun specific tests
npm run test:integration
`Troubleshooting
- Import/dependency errors: Ensure dependencies are properly installed
- External kernels unavailable: Ensure environment has corresponding language runtime (R/Node/Deno/JDK) installed and backend has enabled the kernel
- Timeout/network: Check network and backend service reachability, increase timeout/requestTimeout if necessaryTech Stack
!Python
!R
!JavaScript
!TypeScript
!Java
!Bash
Platform Support
Automated Release Process
This project uses semantic-release for fully automated version management and releases.
$3
Use Conventional Commits specification:
`bash
New feature (automatically publish minor version)
git commit -m "feat: add new authentication method"Bug fix (automatically publish patch version)
git commit -m "fix: resolve timeout issue in sandbox"Breaking change (automatically publish major version)
git commit -m "feat!: breaking change in API"Documentation update (does not trigger release)
git commit -m "docs: update installation guide"Performance optimization (automatically publish patch version)
git commit -m "perf: optimize memory usage"
`$3
1. Commit code using standardized commit message
2. Push to main branch
3. CI automatically handles:
- โ
Analyze commit messages to determine version type
- โ
Automatically update version number
- โ
Generate CHANGELOG.md
- โ
Create Git tag
- โ
Publish to npm
- โ
Create GitHub Release
$3
| Commit Type | Version Increment | Example |
|------------|---------|------|
|
feat: | minor (0.1.0) | New feature |
| fix: | patch (0.0.1) | Bug fix |
| perf: | patch (0.0.1) | Performance optimization |
| feat!: | major (1.0.0) | Breaking change |
| docs: | - | Documentation update |
| chore: | - | Build/tools |
| test:` | - | Testing related |