Execute Commands

Learn how to run commands inside your sandboxes.

Using the TypeScript SDK

Run commands in your sandbox via the execute method.

example.ts

import SandboxSDK from '@dvmcodes/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

Run arbitrary shell commands inside your sandbox.

basic-exec.ts

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 provides full shell capabilities, including piping, redirection, and command chaining.

shell-features.ts

// 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

Provide environment variables when running a command.

env-vars.ts

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

Run commands from a specified working directory.

working-dir.ts

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

Setting Timeout

Set a maximum execution time for commands (1–300 seconds).

timeout.ts

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

Running Python Scripts

Run Python code directly within the sandbox.

run-python.ts

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:

run-node.ts

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. Example fields:

response-fields.ts

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

Check both status and exit_code to determine command outcome reliably.

Handling Results

Successful Execution

successful-exec.ts

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

error-handling.ts

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 run, supporting full CLI syntax such as pipes and output redirection.

timeout integer default:"30"

Maximum execution time in seconds (1–300). Defaults to 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.