Skip to main content

​
Package Management

VoidRun allows you to install packages dynamically at runtime. Whether you need system-level dependencies, Python libraries, or Node.js modules, you can install them on-demand inside your sandbox.

​
Dynamic Package Management

Developers and AI agents can install packages at runtime without pre-baking them into custom images. This provides flexibility for:
  • Ad-hoc dependencies: Install packages as needed during execution
  • AI agent workflows: Let AI agents install required tools dynamically
  • Rapid prototyping: Test new libraries without rebuilding images
  • Version flexibility: Install specific versions on demand

🐧 System Packages

Ubuntu/Debian packages via apt-get for OS-level dependencies.

🐍 Python Packages

pip for Python libraries and frameworks.

📦 Node.js Modules

npm/yarn for JavaScript/TypeScript packages.

​
System Packages (Ubuntu/Debian)

Install OS-level dependencies using apt-get: 
import { VoidRun } from '@voidrun/sdk';

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

// Update package lists
await sandbox.exec({ command: 'apt-get update' });

// Install system packages (e.g., ffmpeg, git, curl)
const result = await sandbox.exec({ 
  command: 'apt-get install -y ffmpeg git curl',
  timeout: 120  // May take a while
});

console.log('Install output:', result.data?.stdout);

// Verify installation
const verify = await sandbox.exec({ command: 'ffmpeg -version' });
console.log('FFmpeg version:', verify.data?.stdout);

await sandbox.remove();

​
Common System Packages

PackageUse Case
ffmpegAudio/video processing
gitVersion control
curl, wgetHTTP requests
imagemagickImage manipulation
postgresql-clientDatabase access
redis-toolsRedis CLI

​
Python Packages

Install Python libraries using pip: 
import { VoidRun } from '@voidrun/sdk';

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

// Install Python packages
const result = await sandbox.exec({ 
  command: 'pip install pandas numpy scikit-learn matplotlib',
  timeout: 120
});

console.log('Install output:', result.data?.stdout);

// Use the installed packages
const codeResult = await sandbox.runCode(`
import pandas as pd
import numpy as np

# Create a DataFrame
df = pd.DataFrame({
    'name': ['Alice', 'Bob', 'Charlie'],
    'score': [85, 92, 78]
})

print(df.describe())
`, { language: 'python' });

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

await sandbox.remove();

​
Installing Specific Versions

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

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

// Install specific version
await sandbox.exec({ 
  command: 'pip install tensorflow==2.15.0' 
});

// Install version range
await sandbox.exec({ 
  command: 'pip install "numpy>=1.20,<2.0"' 
});

​
requirements.txt

Install from a requirements file: 
import { VoidRun } from '@voidrun/sdk';

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

// Upload requirements.txt
const requirements = `
pandas==2.0.0
numpy>=1.20
requests
scikit-learn
`;

await sandbox.fs.uploadFile('/app/requirements.txt', requirements);

// Install from requirements.txt
await sandbox.exec({ 
  command: 'pip install -r /app/requirements.txt',
  timeout: 180
});

​
Node.js Packages

Install JavaScript/TypeScript modules using npm or yarn: 
import { VoidRun } from '@voidrun/sdk';

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

// Initialize npm project
await sandbox.exec({ command: 'mkdir -p /app && cd /app && npm init -y' });

// Install npm packages
const result = await sandbox.exec({ 
  command: 'cd /app && npm install express axios lodash',
  timeout: 120
});

console.log('Install output:', result.data?.stdout);

// Use the installed packages
const codeResult = await sandbox.runCode(`
const express = require('express');
const axios = require('axios');
const _ = require('lodash');

const numbers = [1, 2, 3, 4, 5];
console.log('Sum:', _.sum(numbers));
`, { language: 'javascript' });

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

await sandbox.remove();

​
package.json

Install from package.json: 
import { VoidRun } from '@voidrun/sdk';

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

// Upload package.json
const packageJson = {
  name: 'my-app',
  version: '1.0.0',
  dependencies: {
    express: '^4.18.0',
    axios: '^1.6.0',
    lodash: '^4.17.21'
  }
};

await sandbox.fs.uploadFile('/app/package.json', JSON.stringify(packageJson, null, 2));

// Install dependencies
await sandbox.exec({ 
  command: 'cd /app && npm install',
  timeout: 120
});

​
Best Practices

Installing heavy packages on every sandbox creation can significantly slow down your workflow. Consider the trade-offs between dynamic installation and custom images.

​
When to Install Dynamically

✅ Good for Dynamic Install

  • Small packages (under 50MB)
  • Version-specific requirements
  • Ad-hoc AI agent needs
  • Development/testing
  • Infrequently used dependencies

❌ Better to Bake into Image

  • Large packages (over 100MB)
  • Complex system dependencies
  • Frequently used in production
  • Slow-to-install packages
  • CUDA/GPU dependencies

​
Performance Comparison

ApproachFirst RunSubsequent RunsBest For
Dynamic InstallSlow (30s-5min)Slow (30s-5min)Flexibility, ad-hoc needs
Custom ImageSlow (first only)Fast (2-5s)Production, frequent use

​
Example: AI Agent Workflow

For AI agents that need to install packages dynamically: 
import { VoidRun } from '@voidrun/sdk';

async function aiAgentWithDeps(userRequest: string) {
  const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });
  const sandbox = await vr.createSandbox({ 
    templateId: 'python',
    cpu: 4, 
    mem: 4096 
  });

  try {
    // AI decides what packages are needed
    const requiredPackages = ['requests', 'beautifulsoup4'];
    
    // Install packages
    await sandbox.exec({ 
      command: `pip install ${requiredPackages.join(' ')}`,
      timeout: 60
    });

    // Execute AI-generated code
    const result = await sandbox.runCode(`
import requests
from bs4 import BeautifulSoup

# AI-generated code to fulfill user request
response = requests.get('https://example.com')
soup = BeautifulSoup(response.text, 'html.parser')
print(soup.title.string)
`, { language: 'python' });

    return result.stdout;
  } finally {
    await sandbox.remove();
  }
}

​
Next Steps

Custom Images

Learn how to create pre-configured images with dependencies baked in.

Code Execution

Execute code using your installed packages.