WorkspaceSandbox Interface

The WorkspaceSandbox interface defines how workspaces execute commands.

Methods

start()

Start the sandbox. Called automatically by workspace.init() or on first executeCommand() call.

await sandbox.start();

This method prepares the sandbox for command execution.

stop()

Stop the sandbox.

await sandbox.stop?.();

destroy()

Clean up sandbox resources. Called by workspace.destroy().

await sandbox.destroy();

executeCommand(command, args?, options?)

Execute a shell command.

const result = await sandbox.executeCommand('ls', ['-la', '/docs']);
const result = await sandbox.executeCommand('npm', ['install', 'lodash']);

Parameters:

command:

string

Command to execute

args?:

string[]

Command arguments

options.timeout?:

number

Execution timeout in milliseconds

options.cwd?:

string

Working directory for the command

options.env?:

Record<string, string>

Additional environment variables

options.onStdout?:

(data: string) => void

Callback for stdout streaming

options.onStderr?:

(data: string) => void

Callback for stderr streaming

Returns: Promise<CommandResult>

interface CommandResult {
  success: boolean;
  stdout: string;
  stderr: string;
  exitCode: number;
  executionTimeMs: number;
}

getInfo()

Get sandbox status and resource information.

const info = await sandbox.getInfo();
// { status: 'running', resources: { memoryMB: 512, cpuPercent: 5 } }

Returns: Promise<SandboxInfo>

interface SandboxInfo {
  status: 'starting' | 'running' | 'stopped' | 'error';
  resources?: {
    memoryMB?: number;
    memoryUsedMB?: number;
    cpuCores?: number;
    cpuPercent?: number;
    diskMB?: number;
    diskUsedMB?: number;
  };
}

getInstructions()

Get a description of how this sandbox works. Used in tool descriptions to help agents understand the execution context.

const instructions = sandbox.getInstructions?.();
// 'Local command execution. Working directory: "/workspace".'

Returns: string

Related

• Workspace Class
• Filesystem Interface