DevboxInstance API

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

Properties

name

readonly name: string

The name of the sandbox instance.

status

readonly status: string

Current status of the sandbox (e.g., 'Running', 'Stopped').

runtime

readonly runtime: DevboxRuntime

Runtime environment (e.g., 'node.js', 'python').

resources

readonly resources: ResourceInfo

Resource allocation information.

git

readonly git: Git

Git operations interface.

Lifecycle Methods

start

Starts the sandbox.

start(): Promise<void>

pause

Pauses the sandbox.

pause(): Promise<void>

restart

Restarts the sandbox.

restart(): Promise<void>

shutdown

Shuts down the sandbox.

shutdown(): Promise<void>

delete

Deletes the sandbox.

delete(): Promise<void>

refreshInfo

Refreshes the sandbox information from the API.

refreshInfo(): Promise<void>

File Operations

writeFile

Writes content to a file.

writeFile(
  path: string,
  content: string | Buffer,
  options?: WriteOptions
): Promise<void>

Parameters

• path (string) - File path
• content (string | Buffer) - File content
• options (object, optional)
  • options.encoding (string) - File encoding ('utf8', 'base64')
  • options.mode (number) - File permissions
  • options.createDirs (boolean) - Create parent directories

readFile

Reads content from a file.

readFile(path: string, options?: ReadOptions): Promise<Buffer>

Parameters

• path (string) - File path
• options (object, optional)
  • options.encoding (string) - File encoding
  • options.offset (number) - Read offset
  • options.length (number) - Length to read

listFiles

Lists files in a directory.

listFiles(path: string): Promise<ListFilesResponse>

batchUpload

Uploads multiple files at once.

batchUpload(options: BatchUploadOptions): Promise<TransferResult>

Parameters

• options.files (FileMap) - Map of file paths to content
• options.concurrency (number, optional) - Max concurrent uploads
• options.chunkSize (number, optional) - Chunk size for large files
• options.onProgress (function, optional) - Progress callback

downloadFile

Downloads a single file.

downloadFile(
  path: string,
  options?: DownloadFileOptions
): Promise<Buffer | string>

downloadFiles

Downloads multiple files.

downloadFiles(
  paths: string[],
  options?: { format?: 'tar.gz' | 'tar' | 'multipart' | 'direct' }
): Promise<Buffer>

moveFile

Moves a file or directory.

moveFile(
  from: string,
  to: string,
  overwrite?: boolean
): Promise<MoveFileResponse>

renameFile

Renames a file or directory.

renameFile(
  path: string,
  newName: string
): Promise<RenameFileResponse>

deleteFile

Deletes a file.

deleteFile(path: string): Promise<void>

Process Execution

codeRun

Executes code directly (Node.js or Python).

codeRun(
  code: string,
  options?: CodeRunOptions
): Promise<SyncExecutionResponse>

Parameters

• code (string) - Code to execute
• options (object, optional)
  • options.language ('node' | 'python') - Programming language
  • options.cwd (string) - Working directory
  • options.env (object) - Environment variables
  • options.timeout (number) - Timeout in seconds
  • options.argv (string[]) - Command line arguments

execSync

Executes a command synchronously.

execSync(options: ProcessExecOptions): Promise<SyncExecutionResponse>

Parameters

• options.command (string) - Command to execute
• options.args (string[], optional) - Command arguments
• options.cwd (string, optional) - Working directory
• options.env (object, optional) - Environment variables
• options.shell (string, optional) - Shell to use
• options.timeout (number, optional) - Timeout in seconds

executeCommand

Executes a command asynchronously.

executeCommand(options: ProcessExecOptions): Promise<ProcessExecResponse>

Returns immediately with processId and pid.

execSyncStream

Executes a command with streaming output (SSE).

execSyncStream(options: ProcessExecOptions): Promise<ReadableStream>

getProcessStatus

Gets the status of a process.

getProcessStatus(processId: string): Promise<GetProcessStatusResponse>

getProcessLogs

Gets logs from a process.

getProcessLogs(
  processId: string,
  options?: { lines?: number }
): Promise<GetProcessLogsResponse>

killProcess

Kills a running process.

killProcess(
  processId: string,
  options?: KillProcessOptions
): Promise<void>

Parameters

• processId (string) - Process ID
• options (object, optional)
  • options.signal (string) - Signal to send ('SIGTERM', 'SIGKILL')

listProcesses

Lists all running processes.

listProcesses(): Promise<ListProcessesResponse>

Git Operations

git.clone

Clones a Git repository.

git.clone(options: GitCloneOptions): Promise<void>

Parameters

• options.url (string) - Repository URL
• options.targetDir (string) - Target directory
• options.branch (string, optional) - Branch to clone
• options.depth (number, optional) - Shallow clone depth
• options.auth (object, optional) - Authentication
  • auth.type ('https' | 'ssh') - Auth type
  • auth.username (string) - Username (for HTTPS)
  • auth.password (string) - Password/token (for HTTPS)
  • auth.privateKey (string) - Private key (for SSH)
  • auth.passphrase (string, optional) - Passphrase (for SSH)

git.pull

Pulls changes from a Git repository.

git.pull(options: GitPullOptions): Promise<void>

git.push

Pushes changes to a Git repository.

git.push(options: GitPushOptions): Promise<void>

git.status

Gets the status of a Git repository.

git.status(path: string): Promise<GitStatus>

git.branches

Lists branches in a Git repository.

git.branches(path: string): Promise<GitBranchInfo[]>

Utility Methods

getPorts

Gets listening ports on the system.

getPorts(): Promise<PortsResponse>

isHealthy

Checks if the sandbox is healthy.

isHealthy(): Promise<boolean>

waitForReady

Waits for the sandbox to be ready.

waitForReady(
  timeout?: number,
  checkInterval?: number
): Promise<void>

Parameters

• timeout (number, optional) - Timeout in milliseconds (default: 300000)
• checkInterval (number, optional) - Check interval in milliseconds (default: 2000)

Complete Example

import { DevboxSDK } from '@labring/devbox-sdk'

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

const sandbox = await sdk.createDevbox({
  name: 'example',
  runtime: 'node.js',
  resource: { cpu: 1, memory: 512 }
})

// File operations
await sandbox.writeFile('app.js', 'console.log("Hello")')
const content = await sandbox.readFile('app.js')

// Process execution
const result = await sandbox.codeRun('console.log("Hello")')
const process = await sandbox.executeCommand({
  command: 'npm',
  args: ['install']
})

// Git operations
await sandbox.git.clone({
  url: 'https://github.com/user/repo.git',
  targetDir: '/workspace/repo'
})

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

Next Steps

• Read Type Definitions
• Explore Examples