devbox-sdk

Secure Sandbox SDK for Isolated Code Execution. Execute AI-generated code, run automation tasks, and test untrusted code with zero risk to your infrastructure.

Installation

npm install devbox-sdk

Requirements

• Node.js >= 22.0.0
• Kubernetes configuration (KUBECONFIG environment variable or file path)

Quick Start

Secure Code Execution

import { DevboxSDK } from 'devbox-sdk'

// Initialize SDK
const sdk = new DevboxSDK({
  kubeconfig: process.env.KUBECONFIG
})

// Create a secure sandbox
const sandbox = await sdk.createDevbox({
  name: 'ai-task',
  runtime: 'python',
  resource: { cpu: 1, memory: 512 }
})

// Execute code safely in isolation
const result = await sandbox.codeRun('print("Hello from secure sandbox!")')
console.log(result.stdout) // "Hello from secure sandbox!"

// Clean up
await sandbox.delete()
await sdk.close()

Features

🛡️ Secure Sandbox Execution

Execute code in isolated container environments with zero risk to your infrastructure:

// Create isolated sandbox
const sandbox = await sdk.createDevbox({
  name: 'untrusted-code',
  runtime: 'node.js',
  resource: { cpu: 2, memory: 4096 }
})

// Execute AI-generated or untrusted code safely
const result = await sandbox.codeRun(aiGeneratedCode)

// Each sandbox is completely isolated
// - No access to host filesystem
// - Resource limits enforced
// - Network isolation
// - Automatic cleanup on deletion

Security Features:

• Container Isolation - Each sandbox runs in an isolated Kubernetes Pod
• Path Validation - Prevents directory traversal attacks
• Resource Limits - CPU and memory constraints
• Access Control - Kubeconfig-based authentication
• HTTPS/TLS - All communications encrypted

⚡ Fast Code Execution

Execute code synchronously or asynchronously with real-time output:

// Synchronous execution (waits for completion)
const result = await sandbox.execSync({
  command: 'python script.py',
  cwd: '/workspace',
  timeout: 60000
})
console.log(result.stdout)
console.log(result.exitCode)

// Asynchronous execution (returns immediately)
const process = await sandbox.exec({
  command: 'npm run build',
  cwd: '/workspace'
})

// Get process status
const status = await sandbox.getProcessStatus(process.processId)

// Get real-time logs
const logs = await sandbox.getProcessLogs(process.processId, {
  lines: 100
})

// Kill process if needed
await sandbox.killProcess(process.processId)

Code Execution Methods:

• codeRun(code, options?) - Execute code string directly (Node.js/Python)
• execSync(options) - Synchronous command execution
• exec(options) - Asynchronous command execution
• execSyncStream(options) - Stream output in real-time (SSE)

📁 File Operations

Full CRUD operations with support for text and binary content:

// Write text file
await sandbox.writeFile('app.js', 'console.log("Hello")')

// Write binary file
await sandbox.writeFile('image.png', imageBuffer)

// Read file
const content = await sandbox.readFile('app.js')
console.log(content.toString())

// List files
const files = await sandbox.listFiles('/workspace')
console.log(files.files)

// Batch upload
await sandbox.batchUpload({
  files: {
    'src/index.js': 'console.log("Hello")',
    'package.json': JSON.stringify({ name: 'my-app' })
  }
})

// Download file
const fileContent = await sandbox.downloadFile('app.js', {
  format: 'buffer' // or 'base64', 'text'
})

// Move and rename
await sandbox.moveFile({ from: '/old/path', to: '/new/path' })
await sandbox.renameFile({ path: '/old-name', newName: 'new-name' })

🔐 Git Integration

Clone, pull, push, and manage Git repositories securely:

// Clone repository
await sandbox.git.clone({
  url: 'https://github.com/user/repo.git',
  path: '/workspace/repo',
  auth: {
    type: 'https',
    username: 'user',
    password: 'token'
  }
})

// Pull changes
await sandbox.git.pull({
  path: '/workspace/repo',
  auth: { /* ... */ }
})

// Push changes
await sandbox.git.push({
  path: '/workspace/repo',
  auth: { /* ... */ }
})

// Get status
const status = await sandbox.git.status('/workspace/repo')
console.log(status.branch)
console.log(status.changes)

// List branches
const branches = await sandbox.git.branches('/workspace/repo')

📊 Monitoring

Monitor sandbox resource usage and metrics:

// Get monitor data
const monitorData = await sdk.getMonitorData('sandbox-name', {
  start: Date.now() - 3600000, // 1 hour ago
  end: Date.now()
})

monitorData.forEach(data => {
  console.log('CPU:', data.cpu)
  console.log('Memory:', data.memory)
  console.log('Timestamp:', data.timestamp)
})

🔄 Lifecycle Management

Create, start, pause, restart, and delete sandboxes:

// Create sandbox
const sandbox = await sdk.createDevbox({
  name: 'my-sandbox',
  runtime: 'node.js',
  resource: { cpu: 2, memory: 4096 }
})

// Control lifecycle
await sandbox.start()
await sandbox.pause()
await sandbox.restart()
await sandbox.shutdown()
await sandbox.delete()

// List all sandboxes
const sandboxes = await sdk.listDevboxes()

// Get existing sandbox
const existing = await sdk.getDevbox('my-sandbox')

Use Cases

AI Agents & Code Generation

// Execute AI-generated code safely
const aiCode = await llm.generateCode(prompt)
const result = await sandbox.codeRun(aiCode)

if (result.exitCode !== 0) {
  console.error('Execution failed:', result.stderr)
} else {
  console.log('Result:', result.stdout)
}

Automation & Testing

// Run untrusted automation scripts in isolation
await sandbox.execSync({
  command: 'npm test',
  cwd: '/workspace',
  timeout: 60000
})

CI/CD Tasks

// Execute build tasks in isolated environment
await sandbox.git.clone({ url: repoUrl, path: '/workspace' })
await sandbox.execSync({ command: 'npm install' })
await sandbox.execSync({ command: 'npm run build' })

Configuration

SDK Configuration

const sdk = new DevboxSDK({
  // Required: Kubernetes config
  kubeconfig: process.env.KUBECONFIG, // or file path
  
  // Optional: API base URL
  baseUrl: 'https://api.sealos.io',
  
  // Optional: HTTP client configuration
  http: {
    timeout: 30000,        // Request timeout in milliseconds
    retries: 3,            // Number of retry attempts
    rejectUnauthorized: true // SSL certificate verification
  }
})

Sandbox Creation Options

await sdk.createDevbox({
  name: 'my-sandbox',           // Required: Unique name
  runtime: 'node.js',          // Required: Runtime environment
  resource: {                  // Required: Resource allocation
    cpu: 2,                    // CPU cores
    memory: 4096              // Memory in MB
  },
  ports: [                     // Optional: Port mappings
    { containerPort: 3000, servicePort: 3000 }
  ],
  env: [                       // Optional: Environment variables
    { name: 'NODE_ENV', value: 'production' }
  ]
})

API Reference

DevboxSDK

Main SDK class for managing sandboxes.

Methods

• createDevbox(config: DevboxCreateConfig): Promise<DevboxInstance> - Create a new sandbox
• getDevbox(name: string): Promise<DevboxInstance> - Get an existing sandbox
• listDevboxes(): Promise<DevboxInstance[]> - List all sandboxes
• getMonitorData(devboxName: string, timeRange?: TimeRange): Promise<MonitorData[]> - Get monitoring data
• close(): Promise<void> - Close all connections and cleanup

DevboxInstance

Represents a single sandbox instance with methods for code execution, file operations, and more.

Properties

• name: string - Sandbox name
• status: string - Current status
• runtime: DevboxRuntime - Runtime environment
• resources: ResourceInfo - Resource allocation
• git: Git - Git operations interface

Methods

Code Execution:

• codeRun(code: string, options?: CodeRunOptions): Promise<SyncExecutionResponse>
• execSync(options: ProcessExecOptions): Promise<SyncExecutionResponse>
• exec(options: ProcessExecOptions): Promise<ProcessExecResponse>
• execSyncStream(options: ProcessExecOptions): Promise<ReadableStream>

Process Management:

• getProcessStatus(processId: string): Promise<GetProcessStatusResponse>
• getProcessLogs(processId: string, options?: { lines?: number }): Promise<GetProcessLogsResponse>
• killProcess(processId: string, options?: KillProcessOptions): Promise<void>
• listProcesses(): Promise<ListProcessesResponse>

File Operations:

• writeFile(path: string, content: string | Buffer, options?: WriteOptions): Promise<void>
• readFile(path: string, options?: ReadOptions): Promise<Buffer>
• listFiles(path: string): Promise<ListFilesResponse>
• batchUpload(options: BatchUploadOptions): Promise<TransferResult>
• downloadFile(path: string, options?: DownloadFileOptions): Promise<Buffer | string>
• moveFile(options: MoveFileOptions): Promise<MoveFileResponse>
• renameFile(options: RenameFileOptions): Promise<RenameFileResponse>

File Watching:

• watchFiles(path: string, callback: (event: FileChangeEvent) => void): Promise<FileWatchWebSocket>

Git Operations:

• git.clone(options: GitCloneOptions): Promise<void>
• git.pull(options: GitPullOptions): Promise<void>
• git.push(options: GitPushOptions): Promise<void>
• git.status(path: string): Promise<GitStatus>
• git.branches(path: string): Promise<GitBranchInfo[]>

Lifecycle:

• start(): Promise<void>
• pause(): Promise<void>
• restart(): Promise<void>
• shutdown(): Promise<void>
• delete(): Promise<void>
• refreshInfo(): Promise<void>

Error Handling

The SDK provides comprehensive error types:

import {
  DevboxSDKError,
  AuthenticationError,
  ConnectionError,
  FileOperationError,
  DevboxNotFoundError,
  ValidationError
} from 'devbox-sdk'

try {
  await sandbox.writeFile('/invalid/path', 'content')
} catch (error) {
  if (error instanceof FileOperationError) {
    console.error('File operation failed:', error.message)
  } else if (error instanceof ValidationError) {
    console.error('Validation error:', error.message)
  }
}

Security Best Practices

1. Always validate input before executing in sandbox
2. Set resource limits to prevent resource exhaustion
3. Use HTTPS for all communications
4. Clean up sandboxes after use to free resources
5. Monitor resource usage to detect anomalies
6. Use path validation for all file operations

Examples

Complete AI Agent Workflow

import { DevboxSDK } from 'devbox-sdk'

async function runAIAgent() {
  const sdk = new DevboxSDK({
    kubeconfig: process.env.KUBECONFIG
  })

  try {
    // Create secure sandbox
    const sandbox = await sdk.createDevbox({
      name: 'ai-agent',
      runtime: 'python',
      resource: { cpu: 2, memory: 4096 }
    })

    // Execute AI-generated code
    const aiCode = await llm.generateCode(userPrompt)
    const result = await sandbox.codeRun(aiCode)

    if (result.exitCode === 0) {
      console.log('Success:', result.stdout)
    } else {
      console.error('Error:', result.stderr)
    }

    // Clean up
    await sandbox.delete()
  } finally {
    await sdk.close()
  }
}

runAIAgent()

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type {
  DevboxSDKConfig,
  DevboxCreateConfig,
  DevboxInfo,
  FileMap,
  ProcessExecOptions,
  GitCloneOptions
} from 'devbox-sdk'

Performance

• Connection Pooling: Efficient HTTP connection reuse (>98% reuse rate)
• Adaptive Transfer: Smart file transfer strategies based on file size
• Fast Creation: Quick sandbox initialization
• Type Safety: Full TypeScript support prevents runtime errors

License

Apache-2.0

Links

• GitHub Repository
• Documentation
• Issue Tracker