Code Execution

VoidRun provides powerful code execution capabilities inside isolated MicroVMs. Execute shell commands, run scripts, or use the built-in code interpreter for multi-language code execution.

The Code Interpreter

VoidRun includes a built-in code interpreter that allows you to execute code in multiple programming languages without manually setting up runtimes. The interpreter handles:

Multiple languages: Python, JavaScript/Node.js, TypeScript, Bash
Automatic setup: Temporary files and cleanup are handled automatically
Output parsing: Results are parsed and returned in a structured format
Streaming support: Real-time output for long-running code

🐍 Python

Full Python 3 runtime with pip package installation support.

📦 JavaScript

Node.js runtime for executing JavaScript and TypeScript code.

🖥️ Shell

Bash shell for system commands and scripting.

Running Commands

Basic Command Execution

Execute any shell command inside the sandbox:

import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });
const sandbox = await vr.createSandbox({ cpu: 2, mem: 2048 });

// Execute a simple bash command
const result = await sandbox.exec({ 
  command: 'echo "Hello, VoidRun!" && pwd' 
});

console.log('stdout:', result.data?.stdout);
console.log('stderr:', result.data?.stderr);
console.log('exit code:', result.data?.exitCode);

await sandbox.remove();

Running Python Code

Use the code interpreter to run Python code:

import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });
const sandbox = await vr.createSandbox({ cpu: 2, mem: 2048 });

// Run Python code using the interpreter
const result = await sandbox.runCode(`
import math
import json

# Calculate fibonacci
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

results = [fibonacci(i) for i in range(10)]
print(json.dumps(results))
`, { language: 'python' });

console.log('Success:', result.success);
console.log('Output:', result.stdout);
console.log('Results:', result.results);

await sandbox.remove();

Running JavaScript/Node.js Code

Execute JavaScript code with the Node.js runtime:

import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });
const sandbox = await vr.createSandbox({ cpu: 2, mem: 2048 });

// Run JavaScript code
const result = await sandbox.runCode(`
const numbers = [1, 2, 3, 4, 5];

// Calculate sum and average
const sum = numbers.reduce((a, b) => a + b, 0);
const avg = sum / numbers.length;

console.log(JSON.stringify({ sum, avg, count: numbers.length }));
`, { language: 'javascript' });

console.log('Output:', result.stdout);

await sandbox.remove();

Running Bash Scripts

Execute shell commands and scripts:

import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });
const sandbox = await vr.createSandbox({ cpu: 2, mem: 2048 });

// Run bash commands
const result = await sandbox.runCode(`
# System information
echo "Hostname: $(hostname)"
echo "Date: $(date)"
echo "Uptime: $(uptime -p)"

# List files
ls -la /home
`, { language: 'bash' });

console.log('Output:', result.stdout);

await sandbox.remove();

Handling Output

Response Structure

Every execution returns a structured response with stdout, stderr, and exit code:

import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });
const sandbox = await vr.getSandbox('sandbox-id');

const result = await sandbox.exec({ 
  command: 'ls -la /nonexistent 2>&1; echo "Exit code: $?"' 
});

// Access output fields
console.log('Standard Output:', result.data?.stdout);
console.log('Standard Error:', result.data?.stderr);
console.log('Exit Code:', result.data?.exitCode);

// Check success
if (result.data?.exitCode === 0) {
  console.log('Command succeeded');
} else {
  console.log('Command failed');
}

Code Interpreter Response

The code interpreter returns additional structured data:

import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });
const sandbox = await vr.getSandbox('sandbox-id');

const result = await sandbox.runCode(`
import json
data = {"name": "VoidRun", "version": 1.0}
print(json.dumps(data))
`, { language: 'python' });

// Code interpreter response structure
console.log('Success:', result.success);        // boolean
console.log('Stdout:', result.stdout);          // raw output
console.log('Stderr:', result.stderr);          // errors
console.log('Exit Code:', result.exitCode);     // process exit code
console.log('Results:', result.results);        // parsed last line
console.log('Logs:', result.logs);              // { stdout: [], stderr: [] }

Streaming Output

For long-running commands, use streaming to get real-time output:

import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });
const sandbox = await vr.getSandbox('sandbox-id');

// Stream output in real-time
await sandbox.execStream(
  { command: 'for i in {1..10}; do echo "Count: $i"; sleep 1; done' },
  {
    onStdout: (data) => console.log('stdout:', data),
    onStderr: (data) => console.error('stderr:', data),
    onExit: ({ exitCode }) => console.log('Exited with code:', exitCode),
    onError: (error) => console.error('Error:', error)
  }
);

console.log('Command completed');

Execution Options

Timeout

Set execution timeouts to prevent hanging commands:

The default timeout is 30 seconds. For long-running commands, explicitly set a higher timeout value.

import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });
const sandbox = await vr.getSandbox('sandbox-id');

// Set a 60-second timeout
const result = await sandbox.exec({ 
  command: 'sleep 30 && echo "Done"',
  timeout: 60  // seconds
});

// For code interpreter
const codeResult = await sandbox.runCode(`
import time
time.sleep(30)
print("Done sleeping")
`, { language: 'python', timeout: 60 });

Working Directory

Execute commands in a specific directory:

import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });
const sandbox = await vr.getSandbox('sandbox-id');

// Execute in specific directory
const result = await sandbox.exec({ 
  command: 'pwd && ls -la',
  cwd: '/app/src'  // working directory
});

console.log(result.data?.stdout); // /app/src

Environment Variables

Pass custom environment variables to commands:

import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });
const sandbox = await vr.getSandbox('sandbox-id');

// Pass environment variables
const result = await sandbox.exec({ 
  command: 'echo "API Key: $API_KEY" && echo "Debug: $DEBUG"',
  env: {
    API_KEY: 'secret-key-123',
    DEBUG: 'true'
  }
});

console.log(result.data?.stdout);

Background Processes

Run long-running processes in the background:

import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });
const sandbox = await vr.getSandbox('sandbox-id');

// Start a background process
const runResult = await sandbox.commands.run({
  command: 'npm run dev',
  cwd: '/app'
});

console.log('Process PID:', runResult.data?.pid);

// List running processes
const listResult = await sandbox.commands.list();
console.log('Running processes:', listResult.data);

// Wait for process to complete
const waitResult = await sandbox.commands.wait(runResult.data?.pid);
console.log('Exit code:', waitResult.data?.exitCode);

// Or kill a running process
await sandbox.commands.kill(runResult.data?.pid);

Best Practices

Security: Never execute untrusted user input directly. Always sanitize and validate code before execution. Consider using allowlists for acceptable commands.

Error Handling

Always handle execution errors gracefully:

import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });
const sandbox = await vr.getSandbox('sandbox-id');

try {
  const result = await sandbox.exec({ 
    command: 'some-command-that-might-fail' 
  });
  
  if (result.data?.exitCode !== 0) {
    console.error('Command failed:', result.data?.stderr);
    // Handle failure
  } else {
    console.log('Success:', result.data?.stdout);
  }
} catch (error) {
  console.error('Execution error:', error);
  // Handle network/API errors
}

Getting Started

Core Concepts

Environments

Networking

Advanced Access

Code Execution

Code Execution

The Code Interpreter

🐍 Python

📦 JavaScript

🖥️ Shell

Running Commands

Basic Command Execution

Running Python Code

Running JavaScript/Node.js Code

Running Bash Scripts

Handling Output

Response Structure

Code Interpreter Response

Streaming Output

Execution Options

Timeout

Working Directory

Environment Variables

Background Processes

Best Practices

Error Handling

Next Steps

File System

Custom Images

Getting Started

Core Concepts

Environments

Networking

Advanced Access

​Code Execution

​The Code Interpreter

🐍 Python

📦 JavaScript

🖥️ Shell

​Running Commands

​Basic Command Execution

​Running Python Code

​Running JavaScript/Node.js Code

​Running Bash Scripts

​Handling Output

​Response Structure

​Code Interpreter Response

​Streaming Output

​Execution Options

​Timeout

​Working Directory

​Environment Variables

​Background Processes

​Best Practices

​Error Handling

​Next Steps

File System

Custom Images

Code Execution

The Code Interpreter

Running Commands

Basic Command Execution

Running Python Code

Running JavaScript/Node.js Code

Running Bash Scripts

Handling Output

Response Structure

Code Interpreter Response

Streaming Output

Execution Options

Timeout

Working Directory

Environment Variables

Background Processes

Best Practices

Error Handling

Next Steps