Skip to main content
The Commands resource provides shell command execution capabilities for running system commands, scripts, and tools inside sandboxes.

​
Accessing Commands Resource

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({ template: 'code-interpreter' });
await sandbox.init();
const commands = sandbox.commands;  // Lazy-loaded resource

​
Running Commands

​
run()

Execute a shell command and wait for completion. 
const result = await sandbox.commands.run('ls -la /workspace');
console.log(result.stdout);
console.log(`Exit code: ${result.exit_code}`);
Method Signature: 
async run(
  command: string,
  options?: CommandOptions
): Promise<CommandResponse>
Options: 
interface CommandOptions {
  timeout?: number;           // Timeout in seconds (default: 30)
  background?: boolean;       // Run in background
  env?: Record<string, string>; // Environment variables
  workingDir?: string;         // Working directory (default: '/workspace')
}
Returns: CommandResponse object

​
CommandResponse

The CommandResponse object contains command execution results: 
interface CommandResponse {
  stdout: string;         // Standard output
  stderr: string;         // Standard error
  exit_code: number;      // Exit code (0 = success)
  execution_time: number; // Execution time in seconds
}
Example: 
const result = await sandbox.commands.run('echo "Hello, World!"');
if (result.exit_code === 0) {
  console.log(`Output: ${result.stdout}`);
} else {
  console.log(`Error: ${result.stderr}`);
  console.log(`Exit code: ${result.exit_code}`);
}

​
Basic Usage

​
Simple Commands

// List files
const result = await sandbox.commands.run('ls -la');
console.log(result.stdout);

// Check Python version
const result = await sandbox.commands.run('python --version');
console.log(result.stdout);

​
Timeouts

Set custom timeouts for long-running commands: 
// Quick command
const result = await sandbox.commands.run('ls -la', { timeout: 10 });

// Long-running command
const result = await sandbox.commands.run('npm install', { timeout: 300 });

​
Working Directory

Execute commands in a specific directory: 
// Create project directory
await sandbox.files.mkdir('/workspace/project');

// Run command in project directory
const result = await sandbox.commands.run('ls -la', {
  workingDir: '/workspace/project'
});

​
Environment Variables

Pass environment variables for a specific command: 
// Set API key for this command only
const result = await sandbox.commands.run('echo $API_KEY', {
  env: { API_KEY: 'sk-test-123' }
});

// Multiple environment variables
const result = await sandbox.commands.run('python script.py', {
  env: {
    API_KEY: 'sk-prod-xyz',
    DEBUG: 'true',
    NODE_ENV: 'production'
  }
});

​
Background Execution

Run commands in the background: 
// Start background process
const result = await sandbox.commands.run('python long_script.py', {
  background: true
});

// Command returns immediately with process info
console.log(`Background command started: ${result.stdout}`);

​
Error Handling

Handle command execution errors: 
import { CommandExecutionError } from '@hopx-ai/sdk';

try {
  const result = await sandbox.commands.run('invalid-command-that-fails');
} catch (error) {
  if (error instanceof CommandExecutionError) {
    console.log(`Command execution failed: ${error.message}`);
    console.log(`Command: ${error.command}`);
  }
}

​
Examples

​
Package Installation

// Install Python packages
const result = await sandbox.commands.run('pip install pandas numpy', {
  timeout: 300
});

// Install Node.js packages
const result = await sandbox.commands.run('npm install express', {
  timeout: 180
});