Skip to main content

​
Quickstart Guide

Get your first VoidRun sandbox up and running in minutes. This guide walks you through installation, authentication, and basic operations.

​
Prerequisites

Before you begin, make sure you have:
  • A VoidRun API key (get one from your VoidRun Dashboard)
  • Node.js 18+ or Python 3.9+ installed (for SDK usage)
  • curl installed (for REST API usage)

​
Step 1: Install the SDK

Choose your preferred language: 
npm install @voidrun/sdk

​
Step 2: Configure Authentication

Set your API key as an environment variable: 
export VOIDRUN_API_KEY="your-api-key-here"
You can also pass the API key directly when initializing the SDK client. See the examples below.

​
Step 3: Create Your First Sandbox

Create an isolated MicroVM environment: 
import { VoidRun } from '@voidrun/sdk';

// Initialize with environment variable
const vr = new VoidRun({});

// Or pass API key explicitly
// const vr = new VoidRun({ apiKey: 'your-api-key' });

// Create a sandbox
const sandbox = await vr.createSandbox({
  name: 'my-first-sandbox',
  cpu: 2,
  mem: 2048,
  templateId: 'ubuntu:22.04'
});

console.log(`Sandbox created: ${sandbox.id}`);
console.log(`Status: ${sandbox.status}`);

​
Step 4: Execute Commands

Run commands inside your sandbox: 
// Execute a simple command
const result = await sandbox.exec({ 
  command: 'echo "Hello from VoidRun!"' 
});

console.log(result.data?.stdout); // "Hello from VoidRun!"
console.log(result.data?.exitCode); // 0

// Execute with streaming output
await sandbox.execStream(
  { command: 'npm install && npm run build' },
  {
    onStdout: (data) => console.log('stdout:', data),
    onStderr: (data) => console.error('stderr:', data),
    onExit: ({ exitCode }) => console.log('Exited with code:', exitCode)
  }
);

​
Step 5: Work with Files

Upload, download, and manage files in your sandbox: 
// Create and write to a file
await sandbox.fs.createFile('/app/hello.txt');
await sandbox.fs.uploadFile('/app/hello.txt', 'Hello, VoidRun!');

// Read file contents
const content = await sandbox.fs.downloadFile('/app/hello.txt');
console.log(content.toString()); // "Hello, VoidRun!"

// List files in a directory
const files = await sandbox.fs.listFiles('/app');
console.log(files.data);

// Copy and move files
await sandbox.fs.copyFile('/app/hello.txt', '/app/hello-copy.txt');
await sandbox.fs.moveFile('/app/hello-copy.txt', '/tmp/hello.txt');

// Delete a file
await sandbox.fs.deleteFile('/tmp/hello.txt');

​
Step 6: Run Code with the Interpreter

Execute code in multiple languages using the built-in code interpreter: 
// Run Python code
const pyResult = await sandbox.runCode(`
import math
print(f"Pi is approximately {math.pi:.4f}")
`, { language: 'python' });
console.log(pyResult.stdout);

// Run JavaScript code
const jsResult = await sandbox.runCode(`
const numbers = [1, 2, 3, 4, 5];
const sum = numbers.reduce((a, b) => a + b, 0);
console.log(\`Sum: \${sum}\`);
`, { language: 'javascript' });
console.log(jsResult.stdout);

// Run Bash commands
const bashResult = await sandbox.runCode(`
for i in {1..5}; do
  echo "Count: $i"
done
`, { language: 'bash' });
console.log(bashResult.stdout);

​
Step 7: Manage Sandbox Lifecycle

Control your sandbox state: 
// List all sandboxes
const { sandboxes, meta } = await vr.listSandboxes();
console.log(`Total sandboxes: ${meta.total}`);

// Get a specific sandbox
const existing = await vr.getSandbox('sandbox-id');

// Pause a running sandbox (saves resources)
await sandbox.pause();

// Resume a paused sandbox (< 200ms)
await sandbox.resume();

// Stop a sandbox
await sandbox.stop();

// Start a stopped sandbox
await sandbox.start();

// Delete a sandbox when done
await sandbox.remove();

​
Complete Example

Here’s a complete example that demonstrates the full workflow: 
import { VoidRun } from '@voidrun/sdk';

async function main() {
  // Initialize client
  const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });

  // Create sandbox
  const sandbox = await vr.createSandbox({
    name: 'quickstart-demo',
    cpu: 2,
    mem: 2048,
    templateId: 'ubuntu:22.04'
  });

  console.log(`Created sandbox: ${sandbox.id}`);

  try {
    // Upload a file
    await sandbox.fs.uploadFile('/tmp/data.txt', 'Hello, VoidRun!');

    // Execute a command
    const result = await sandbox.exec({ command: 'cat /tmp/data.txt' });
    console.log('File contents:', result.data?.stdout);

    // Run Python code
    const codeResult = await sandbox.runCode(`
with open('/tmp/data.txt', 'r') as f:
    content = f.read()
    print(f"Read from file: {content}")
`, { language: 'python' });
    console.log('Python output:', codeResult.stdout);

  } finally {
    // Clean up
    await sandbox.remove();
    console.log('Sandbox deleted');
  }
}

main().catch(console.error);

​
What’s Next?

Always clean up sandboxes when you’re done to avoid unnecessary resource usage. Sandboxes auto-sleep after 5 minutes of idle time but remain available until explicitly deleted.
Now that you’ve completed the quickstart, explore these topics:

Core Concepts

Learn about sandbox lifecycle, auto-sleep, and resume behavior.

Code Execution

Deep dive into command execution and code interpreter features.

Custom Images

Create and use custom Docker images for your sandboxes.

Networking

Configure internet access and VPN connectivity.