Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vibekit.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
Method signature

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

​
Parameters

ParameterTypeRequiredDefaultDescription
commandstringYes-The shell command to execute in the sandbox environment
optionsobjectNo{}Configuration options for command execution

​
Options Object

PropertyTypeRequiredDefaultDescription
timeoutMsnumberNo-Maximum time in milliseconds to wait for command completion
backgroundbooleanNofalseWhether to run the command in the background (non-blocking)
branchstringNo-Git branch to checkout or create before executing the command
callbacksStreamCallbacksNo-Streaming callbacks for real-time command output

​
StreamCallbacks Interface

PropertyTypeRequiredDescription
onUpdate(message: string) => voidNoCalled with streaming updates from command output (stdout)
onError(error: string) => voidNoCalled when errors occur during command execution (stderr)

​
Return value

TypeDescription
Promise<AgentResponse>Promise that resolves to the command execution results

​
AgentResponse Interface

PropertyTypeDescription
sandboxIdstringUnique identifier for the sandbox environment
stdoutstringStandard output from the command execution
stderrstringStandard error from the command execution
exitCodenumberExit 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