Skip to main content

​
Custom Images

VoidRun supports custom Docker images, allowing you to pre-configure environments with your specific dependencies, tools, and configurations. All while maintaining the signature under 200ms resume time and MicroVM isolation.

​
How Custom Images Work

VoidRun uses a template system that maps to pre-built root filesystems. When you create a sandbox with a custom image, VoidRun:
  1. Pulls the image (if not cached)
  2. Creates an isolated MicroVM with the image’s root filesystem
  3. Maintains the same performance characteristics as standard images

🚀 Fast Resume

Custom images maintain the same under 200ms resume time as standard images.

🔒 Full Isolation

Each sandbox runs in its own MicroVM, regardless of the base image.

📦 Docker Compatible

Use images from Docker Hub or private registries.

​
Available Templates

VoidRun provides several built-in templates:
Template IDDescriptionUse Case
debianDebian-based Linux (default)General purpose, AI/ML workloads
ubuntuUbuntu-based LinuxDevelopment, CI/CD
nodeNode.js pre-installedJavaScript/TypeScript applications
pythonPython pre-installedData science, AI agents
The default template is debian. If you don’t specify a templateId, the sandbox will use the Debian-based image.

​
Using a Custom Image

​
Specify Template at Creation

Pass the templateId parameter when creating a sandbox: 
import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });

// Create sandbox with Node.js template
const sandbox = await vr.createSandbox({
  name: 'node-app',
  templateId: 'node',  // Use Node.js image
  cpu: 2,
  mem: 2048
});

console.log('Sandbox ID:', sandbox.id);
console.log('Template:', sandbox.templateId);

// Node.js is ready to use
const result = await sandbox.exec({ command: 'node --version' });
console.log('Node version:', result.data?.stdout);

await sandbox.remove();

​
Python Template

Create a sandbox with Python pre-installed: 
import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });

// Create sandbox with Python template
const sandbox = await vr.createSandbox({
  name: 'python-app',
  templateId: 'python',
  cpu: 2,
  mem: 4096
});

// Python is ready to use
const result = await sandbox.exec({ command: 'python3 --version' });
console.log('Python version:', result.data?.stdout);

// Run Python code immediately
const codeResult = await sandbox.runCode(`
import sys
print(f"Python {sys.version}")
`, { language: 'python' });

console.log(codeResult.stdout);

await sandbox.remove();

​
Creating Custom Images

For advanced use cases, you can register custom images with the Images API: 
import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });

// Register a custom image
// Note: This requires the image to be available on the VoidRun server
// TODO: Verify exact API method for custom image registration
const imagesApi = vr.images; // Access to ImagesApi

// Create image record
await imagesApi.createImage({
  createImageRequest: {
    name: 'my-custom-image',
    version: '1.0.0',
    path: '/path/to/rootfs'
  }
});

// Then use it when creating a sandbox
const sandbox = await vr.createSandbox({
  name: 'custom-app',
  templateId: 'my-custom-image',
  cpu: 2,
  mem: 2048
});

​
Image Caching & Performance

VoidRun caches images on the host server. The first sandbox creation with a new image may take longer as the image is pulled and prepared. Subsequent sandboxes using the same image will be fast.

​
How Caching Works

  1. First Use: Image is pulled and cached on the host (may take 10-60 seconds)
  2. Subsequent Uses: Image is served from cache (fast creation)
  3. Auto-Sleep Interaction: Sleeping sandboxes retain their image; resume is always under 200ms

​
Performance Characteristics

OperationFirst UseCached
Create Sandbox10-60s2-5s
Resume from SleepN/Aunder 200ms
Execute CommandInstantInstant
Custom images are cached per-region. If you’re using multiple regions, the first sandbox in each region will experience the longer “first use” creation time.

​
Best Practices

​
Choose the Right Base Image

✅ Do

  • Use python template for Python workloads
  • Use node template for JavaScript/TypeScript
  • Start with debian for maximum compatibility

❌ Don't

  • Install heavy packages on every sandbox creation
  • Use oversized images when a minimal one works
  • Re-create sandboxes unnecessarily

​
Image Selection Guide

Use CaseRecommended TemplateWhy
AI/ML DevelopmentpythonPython pre-installed, pip ready
Web ServicesnodeNode.js runtime ready
General ScriptsdebianMinimal, flexible
CI/CD Pipelinesdebian or ubuntuFull Linux environment

​
Environment Variables

Set environment variables when creating sandboxes with custom images: 
import { VoidRun } from '@voidrun/sdk';

const vr = new VoidRun({ apiKey: process.env.VOIDRUN_API_KEY });

const sandbox = await vr.createSandbox({
  name: 'configured-app',
  templateId: 'python',
  cpu: 2,
  mem: 2048,
  envVars: {
    NODE_ENV: 'production',
    DATABASE_URL: 'postgres://localhost:5432/mydb',
    API_KEY: 'secret-key-123'
  }
});

// Environment variables are available
const result = await sandbox.exec({ command: 'echo $DATABASE_URL' });
console.log(result.data?.stdout);

​
Next Steps

Package Management

Install packages dynamically at runtime.

Code Execution

Execute code in your custom environment.