executeCommand

Method signature

public async executeCommand(
  command: string,
  options: {
    timeoutMs?: number;
    background?: boolean;
    branch?: string;
    callbacks?: StreamCallbacks;
  } = {}
): Promise<AgentResponse>

Parameters

Parameter	Type	Required	Default	Description
`command`	`string`	Yes	-	The shell command to execute in the sandbox environment
`options`	`object`	No	`{}`	Configuration options for command execution

Options Object

Property	Type	Required	Default	Description
`timeoutMs`	`number`	No	-	Maximum time in milliseconds to wait for command completion
`background`	`boolean`	No	`false`	Whether to run the command in the background (non-blocking)
`branch`	`string`	No	-	Git branch to checkout or create before executing the command
`callbacks`	`StreamCallbacks`	No	-	Streaming callbacks for real-time command output

StreamCallbacks Interface

Property	Type	Required	Description
`onUpdate`	`(message: string) => void`	No	Called with streaming updates from command output (stdout)
`onError`	`(error: string) => void`	No	Called when errors occur during command execution (stderr)

Return value

Type	Description
`Promise<AgentResponse>`	Promise that resolves to the command execution results

AgentResponse Interface

Property	Type	Description
`sandboxId`	`string`	Unique identifier for the sandbox environment
`stdout`	`string`	Standard output from the command execution
`stderr`	`string`	Standard error from the command execution
`exitCode`	`number`	Exit code from the command execution (0 indicates success)

Examples

Basic Command Execution

import { VibeKit } from 'vibekit';

const vibekit = new VibeKit(config);

// Execute a simple command
const result = await vibekit.executeCommand('ls -la');

console.log('Command output:', result.stdout);
console.log('Exit code:', result.exitCode);

Command with Timeout

// Execute command with a timeout
const result = await vibekit.executeCommand('npm install', {
  timeoutMs: 30000 // 30 seconds timeout
});

if (result.exitCode === 0) {
  console.log('Installation completed successfully');
} else {
  console.log('Installation failed:', result.stderr);
}

Background Command Execution

// Run a long-running command in the background
const result = await vibekit.executeCommand('npm run dev', {
  background: true
});

console.log('Background process started with sandbox ID:', result.sandboxId);

Streaming Command Output

// Execute command with streaming output using stdout/stderr events
vibekit.on('stdout', (output) => {
  console.log('Command output:', output);
});

vibekit.on('stderr', (error) => {
  console.error('Command error:', error);
});

const result = await vibekit.executeCommand('npm test');

console.log('Final test result:', result.exitCode === 0 ? 'PASSED' : 'FAILED');

Streaming with Callbacks (Legacy)

// Execute command with streaming output using callbacks (deprecated approach)
const result = await vibekit.executeCommand('npm test', {
  callbacks: {
    onUpdate: (message) => {
      console.log('Test output:', message);
    },
    onError: (error) => {
      console.error('Test error:', error);
    }
  }
});

console.log('Final test result:', result.exitCode === 0 ? 'PASSED' : 'FAILED');

Command with Branch Switching

// Execute command on a specific git branch
const result = await vibekit.executeCommand('npm run build', {
  branch: 'feature-new-ui',
  timeoutMs: 60000
});

if (result.exitCode === 0) {
  console.log('Build completed successfully on feature-new-ui branch');
} else {
  console.log('Build failed:', result.stderr);
}

Complex Command with All Options

// Execute a complex command with multiple options
vibekit.on('stdout', (output) => {
  console.log('pytest:', output);
});

vibekit.on('stderr', (error) => {
  console.error('pytest error:', error);
});

const result = await vibekit.executeCommand('python -m pytest tests/', {
  timeoutMs: 60000,
  background: false,
  branch: 'test-improvements'
});

console.log(`Tests completed with exit code: ${result.exitCode}`);

Error handling

The method throws errors in the following cases:

Sandbox not available: When no active sandbox environment exists
Command timeout: When the command exceeds the specified timeout
Invalid command: When the command syntax is invalid or command not found
Permission errors: When the command requires elevated permissions not available in the sandbox
Resource limitations: When the command exceeds sandbox resource limits

try {
  const result = await vibekit.executeCommand('sudo rm -rf /', {
    timeoutMs: 5000
  });
} catch (error) {
  if (error.message.includes('timeout')) {
    console.error('Command timed out');
  } else if (error.message.includes('permission')) {
    console.error('Permission denied');
  } else {
    console.error('Command execution failed:', error.message);
  }
}

Security considerations

Commands are executed within a sandboxed environment for security
Elevated privileges (sudo) may not be available depending on sandbox configuration
File system access is limited to the sandbox environment
Network access may be restricted based on sandbox configuration

Notes

Sandbox Environment: Commands are executed within the active sandbox environment
Working Directory: Commands execute in the sandbox’s default working directory
Branch Support: Automatically switches to the specified branch (creates if it doesn’t exist)
Environment Variables: Sandbox environment variables are available to executed commands
Resource Limits: Commands are subject to sandbox CPU, memory, and time limitations
Background Execution: Background commands continue running after the method returns
Streaming Support: Real-time output streaming is available through stdout/stderr events or callbacks
Exit Codes: Standard Unix exit codes apply (0 = success, non-zero = error)
Event Handling: Prefer using vibekit.on('stdout') and vibekit.on('stderr') over callback options

Get Started

Agents

Supported Sandboxes

SDK Reference

Method signature

Parameters

Options Object

StreamCallbacks Interface

Return value

AgentResponse Interface

Examples

Basic Command Execution

Command with Timeout

Background Command Execution

Streaming Command Output

Streaming with Callbacks (Legacy)

Command with Branch Switching

Complex Command with All Options

Error handling

Security considerations

Notes

​Method signature

​Parameters

​Options Object

​StreamCallbacks Interface

​Return value

​AgentResponse Interface

​Examples

​Basic Command Execution

​Command with Timeout

​Background Command Execution

​Streaming Command Output

​Streaming with Callbacks (Legacy)

​Command with Branch Switching

​Complex Command with All Options

​Error handling

​Security considerations

​Notes

Method signature

Parameters

Options Object

StreamCallbacks Interface

Return value

AgentResponse Interface

Examples

Basic Command Execution

Command with Timeout

Background Command Execution

Streaming Command Output

Streaming with Callbacks (Legacy)

Command with Branch Switching

Complex Command with All Options

Error handling

Security considerations

Notes