​
Using the TypeScript SDK

Execute commands in your sandbox using the execute method:

import SandboxSDK from '@avmcodes/sandbox-sdk';

const client = new SandboxSDK({
  apiKey: process.env['SANDBOX_SDK_API_KEY'],
});

// Execute a simple command
const result = await client.sandboxes.execute('sbx_x1y2z3a4b5c6d7e8', {
  command: "python -c \"print('Hello, World!')\"",
});

console.log('Exit code:', result.exit_code);
console.log('Output:', result.stdout);
console.log('Errors:', result.stderr);

​
Basic Command Execution

Execute any shell command in your sandbox:

const result = await client.sandboxes.execute('sbx_x1y2z3a4b5c6d7e8', {
  command: 'ls -la /data',
});

if (result.status === 'completed' && result.exit_code === 0) {
  console.log('Command output:', result.stdout);
} else {
  console.error('Command failed:', result.stderr);
}

​
Using Shell Features

The API supports full shell features like pipes, redirection, and chaining:

// Using pipes
const result = await client.sandboxes.execute('sbx_x1y2z3a4b5c6d7e8', {
  command: 'cat file.txt | grep "error" | wc -l',
});

// Using redirection
const result = await client.sandboxes.execute('sbx_x1y2z3a4b5c6d7e8', {
  command: 'python script.py > output.txt 2>&1',
});

// Chaining commands
const result = await client.sandboxes.execute('sbx_x1y2z3a4b5c6d7e8', {
  command: 'cd /data && npm install && npm test',
});

​
Setting Environment Variables

Pass environment variables to your command:

const result = await client.sandboxes.execute('sbx_x1y2z3a4b5c6d7e8', {
  command: 'python script.py',
  env: {
    API_KEY: 'your-api-key',
    DEBUG: 'true',
    NODE_ENV: 'production',
  },
});

​
Setting Working Directory

Execute commands in a specific directory:

const result = await client.sandboxes.execute('sbx_x1y2z3a4b5c6d7e8', {
  command: 'npm install',
  working_dir: '/app/my-project',
});

​
Setting Timeout

Control how long a command can run (1-300 seconds):

const result = await client.sandboxes.execute('sbx_x1y2z3a4b5c6d7e8', {
  command: 'python long-running-script.py',
  timeout: 120, // 2 minutes
});

​
Running Python Scripts

Execute Python code directly:

const result = await client.sandboxes.execute('sbx_x1y2z3a4b5c6d7e8', {
  command: 'python -c "import json; print(json.dumps({\"status\": \"ok\"}))"',
});

const data = JSON.parse(result.stdout);
console.log(data);

​
Running Node.js Scripts

Execute Node.js code:

const result = await client.sandboxes.execute('sbx_x1y2z3a4b5c6d7e8', {
  command: 'node -e "console.log(JSON.stringify({status: \\"ok\\"}))"',
});

​
Response Structure

The execute() method returns a SandboxExecuteResponse object:

const result = await client.sandboxes.execute('sbx_x1y2z3a4b5c6d7e8', {
  command: 'python -c "print(\'Hello, World!\')"',
});

// result contains:
console.log(result.id);              // "exec_m1n2o3p4q5r6s7t8"
console.log(result.status);          // "completed"
console.log(result.exit_code);       // 0
console.log(result.stdout);          // "Hello, World!\n"
console.log(result.stderr);          // ""
console.log(result.execution_time_ms); // 142
console.log(result.created_at);      // "2024-01-15T12:30:00Z"
console.log(result.completed_at);    // "2024-01-15T12:30:00.142Z"

​
Execution Status

The status field indicates the execution state:

  • running - Command is currently executing
  • completed - Command finished successfully or with an error
  • timeout - Command exceeded the timeout limit
  • error - An error occurred during execution

​
Handling Results

​
Successful Execution

const result = await client.sandboxes.execute('sbx_x1y2z3a4b5c6d7e8', {
  command: 'echo "Success"',
});

if (result.status === 'completed' && result.exit_code === 0) {
  console.log('Success:', result.stdout);
} else {
  console.error('Failed:', result.stderr);
}

​
Error Handling

try {
  const result = await client.sandboxes.execute('sbx_x1y2z3a4b5c6d7e8', {
    command: 'python script.py',
  });

  if (result.status === 'timeout') {
    console.error('Command timed out');
  } else if (result.status === 'error') {
    console.error('Execution error:', result.stderr);
  } else if (result.exit_code !== 0) {
    console.error('Command failed with exit code:', result.exit_code);
    console.error('Error output:', result.stderr);
  }
} catch (error) {
  console.error('API error:', error);
}

​
Parameters

​
command
string
required

The command to execute. Supports full CLI commands with shell features like redirection, pipes, etc.

​
timeout
integer
default:
"30"

Execution timeout in seconds (1-300). Default is 30 seconds.

​
env
object

Environment variables to set for the command execution (key-value pairs).

​
working_dir
string

Working directory for command execution. If not specified, uses the sandbox’s default directory.

​
Response Fields

​
Best Practices

  1. Always check the exit code: A command may complete but fail with a non-zero exit code
  2. Set appropriate timeouts: Long-running commands should have higher timeout values
  3. Use working directories: Specify working_dir to ensure commands run in the correct location
  4. Handle errors gracefully: Check both status and exit_code to handle all failure scenarios
  5. Use environment variables: Pass configuration via env rather than hardcoding values in commands
Create Volume SnapshotsList Sandboxes