Skip to main content

​
Sandbox Lifecycle

VoidRun sandboxes are designed for long-running workloads with intelligent resource management. Unlike traditional serverless functions that timeout, VoidRun sandboxes can run indefinitely while optimizing costs through smart hibernation.

​
Infinite Running

VoidRun sandboxes are designed to run forever. There’s no maximum execution time limit, making them ideal for:
  • Long-running AI agent workflows
  • Persistent development environments
  • Multi-step code execution pipelines
  • Background processing tasks

♾️ No Timeouts

Sandboxes don’t have a maximum execution time. Run tasks for minutes, hours, or days.

💰 Cost Efficient

Auto-sleep ensures you only pay for active compute time, not idle time.

⚡ Instant Resume

Resume sleeping sandboxes in under 200ms, maintaining the illusion of always-on availability.

​
Auto-Sleep & Resume

VoidRun automatically optimizes resource usage by putting idle sandboxes to sleep.

​
How Auto-Sleep Works

1

Activity Monitoring

VoidRun monitors sandbox activity (command execution, file operations, network requests).
2

Idle Detection

After 5 minutes of inactivity, the sandbox enters sleep mode.
3

State Preservation

The sandbox state is preserved—files, environment variables, and running processes are saved.
4

Resource Release

Compute resources are released, reducing costs while the sandbox remains available.
The 5-minute idle timeout is configurable at the organization level. Contact support to adjust this setting for your use case.

​
Lightning-Fast Resume

When you interact with a sleeping sandbox, it resumes automatically in under 200ms:
  • Transparent: Resume happens automatically—no manual wake-up needed
  • Fast: Sub-200ms resume time feels instantaneous
  • Stateful: All files, environment variables, and configurations are preserved

​
Resume Time Comparison

PlatformCold StartResume Time
VoidRun~2s (new sandbox)< 200ms
AWS Lambda~1-5sN/A
Traditional VMs~30-60s~10-30s
Containers~5-15s~2-5s

​
Manual Lifecycle Controls

Take full control over sandbox state with manual lifecycle operations.

​
Pause a Sandbox

Manually pause a running sandbox to release resources while preserving state: 
import { VoidRun } from '@voidrun/sdk';

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

// Pause the sandbox
await sandbox.pause();
console.log('Sandbox paused');

​
Resume a Sandbox

Resume a paused or sleeping sandbox: 
import { VoidRun } from '@voidrun/sdk';

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

// Resume the sandbox (< 200ms)
await sandbox.resume();
console.log('Sandbox resumed and ready');

​
Stop a Sandbox

Stop a running sandbox completely (stronger than pause): 
import { VoidRun } from '@voidrun/sdk';

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

// Stop the sandbox
await sandbox.stop();
console.log('Sandbox stopped');

​
Start a Sandbox

Start a stopped sandbox: 
import { VoidRun } from '@voidrun/sdk';

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

// Start the sandbox
await sandbox.start();
console.log('Sandbox started');

​
Terminate a Sandbox

Permanently delete a sandbox and all its data:
Termination is permanent. All files, environment variables, and state will be lost. Make sure to download any important data before terminating.
import { VoidRun } from '@voidrun/sdk';

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

// Permanently delete the sandbox
await sandbox.remove();
console.log('Sandbox terminated');

​
Lifecycle States

StateDescriptionBillingResume Time
RunningSandbox is active and processingBilled at full rateN/A
PausedManually paused, state preservedBilled at reduced rate< 200ms
SleepingAuto-slept due to inactivityNot billed< 200ms
StoppedManually stoppedNot billed~2s (cold start)

​
Best Practices

​
Cost Optimization

Let sandboxes auto-sleep when not in use. The sub-200ms resume time means there’s virtually no latency penalty, while you save on compute costs.

​
Long-Running Workflows

For workflows that need to maintain state over long periods:
  1. Use persistent storage: Critical data should be persisted to files or external storage
  2. Handle resume gracefully: Design your code to handle potential pauses
  3. Use health checks: Implement periodic health checks for critical long-running processes

​
Example: Long-Running AI Agent

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

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

async function runAIAgent() {
  // Create sandbox - will run indefinitely
  const sandbox = await vr.createSandbox({
    name: 'ai-agent-session',
    cpu: 4,
    mem: 4096
  });

  try {
    // Install dependencies
    await sandbox.exec({ command: 'pip install openai langchain' });

    // Upload agent code
    await sandbox.fs.uploadFile('/app/agent.py', agentCode);

    // Run the agent (can run for hours/days)
    const result = await sandbox.exec({
      command: 'python3 /app/agent.py',
      timeout: 86400 // 24 hours
    });

    console.log(result.data?.stdout);
  } finally {
    // Clean up when truly done
    await sandbox.remove();
  }
}

​
Next Steps

Code Execution

Learn how to execute commands and code inside sandboxes.

File System

Understand file storage and operations in sandboxes.