Skip to main content

​
What are Sandboxes?

Sandboxes are persistent, isolated code execution environments that maintain state across workflow runs. Unlike ephemeral execution, sandboxes preserve files, installed packages, and running processes between invocations.
Note: While sandboxes appear in the integrations browse list, they’re not a typical integration. Instead of calling external APIs, sandboxes provide persistent code execution environments—a fundamentally different capability that warrants special attention.

Persistent State

Files and data survive between workflow runs

Isolated Environment

Each sandbox is a dedicated container

Pause & Resume

Stop to save costs, resume when needed

User-Defined IDs

Retrieve the same sandbox across runs
Sandbox Templates - Browse available templates including Context7 MCP, Magic Component Platform, MCP Server Chart, ArXiv MCP Server, DBHub, ElevenLabs MCP Server, context-portal, actors-mcp-server, Twitter MCP Server, BioMCP, OSP Marketing Tools, mcp-reddit, mcp-linkedin, Replicate MCP Server, DigitalOcean MCP Server
Sandbox Templates - Browse available templates including Context7 MCP, Magic Component Platform, MCP Server Chart, ArXiv MCP Server, DBHub, ElevenLabs MCP Server, context-portal, actors-mcp-server, Twitter MCP Server, BioMCP, OSP Marketing Tools, mcp-reddit, mcp-linkedin, Replicate MCP Server, DigitalOcean MCP Server
In this example:
  • Browse tab shows available sandbox templates (518 total)
  • Your Templates tab (32) shows custom templates
  • Search bar to find specific templates
  • Filter options: Featured, Category, Docker Template
  • Grid of template cards with:
    • MCP Servers: Context7, Magic Component Platform, MCP Server Chart, ArXiv, ElevenLabs, actors-mcp-server, Twitter, Replicate, DigitalOcean
    • Database Tools: DBHub (MySQL, PostgreSQL, SQLite, DuckDB)
    • Data Science & ML: BioMCP (PubMed/PMC access), Replicate
    • Web Scraping: actors-mcp-server (3,000+ Apify tools)
    • Social Media: mcp-reddit, mcp-linkedin, Twitter MCP Server
    • Marketing: OSP Marketing Tools (LLM integration)
    • Other: context-portal
  • Each card shows category/tags (mcp, Learning & Documentation, Design Tools, etc.)
  • Star icons for featured/favorite templates
  • Pin icons for template actions

​
How Sandboxes Work

1

Create Sandbox

Workflow creates a sandbox from a templateExample: Ubuntu 22.04 with Python 3.11 pre-installedSandbox spins up as a Docker container
2

Execute Code

Workflow sends code to sandbox for executionExample: Install packages, create files, run scriptsAll changes persist in the container
3

Save State

Files written to /workspace are preservedExample: Download data, generate reports, store modelsState survives workflow completion
4

Resume Later

Next workflow run retrieves the same sandbox by IDExample: Continue from where last run left offAll files, packages, and state intact
5

Pause When Idle

Sandbox automatically pauses after timeoutExample: After 20 minutes of inactivitySaves costs while preserving state
6

Destroy When Done

Manually destroy or auto-destroy after expirationExample: Delete after 7 days of inactivitySoft delete allows recovery

​
Sandbox Lifecycle

Active execution stateCharacteristics:
  • Container is running
  • Can execute code immediately
  • Incurs compute costs
  • Has timeout (auto-pauses after inactivity)
When to use:
  • During active workflow execution
  • When frequent access is needed
Transitions:
  • → Paused (after timeout)
  • → Destroyed (manual deletion)

​
Sandbox Components

​
Sandbox Template

A template defines the base image and configuration for sandboxes. Template Properties:
  • Base Image: Docker image (Ubuntu, Python, Node.js, etc.)
  • Pre-installed Packages: Tools, libraries, dependencies
  • Environment Variables: Configuration settings
  • Resource Limits: CPU, memory, disk quotas
Example Templates:
  • Python 3.11 + Data Science (pandas, numpy, scikit-learn)
  • Node.js 20 + Web Tools (Playwright, Puppeteer)
  • Ubuntu 22.04 + Build Tools (gcc, make, cmake)

​
User Sandbox Instance

An instance is a running or paused sandbox. Instance Properties: 
{
  "id": "uuid-123",
  "sandbox_id": "e2b_sandbox_xyz",
  "status": "paused",
  "user_defined_id": "my_data_processor",
  "user_id": "user-uuid",
  "workflow_version_id": "workflow-uuid",
  "user_sandbox_template_id": "template-uuid",
  "timeout_at": "2025-10-22T14:00:00Z",
  "last_resumed_at": "2025-10-22T10:30:00Z"
}
Key Fields:
  • user_defined_id: Your custom identifier (retrieve across runs)
  • status: running, paused, destroyed
  • timeout_at: When sandbox auto-pauses
  • last_resumed_at: Last time sandbox was activated

​
Creating Sandboxes

​
In Workflows

Sandboxes are created automatically when workflows reference them:
1

Add Tool Node

Add a Sandbox Execution tool node to your workflow
2

Configure Sandbox

Settings:
  • Template: Choose pre-configured template
  • User Defined ID: Set custom identifier
  • Timeout: Set auto-pause duration (e.g., 20 minutes)
Example:
{
  "user_defined_id": "data_analysis_env",
  "template_id": "python311_datascience",
  "timeout_minutes": 30
}
3

Write Code

Specify code to execute in the sandboxExample:
import pandas as pd

# Load data from previous run (persisted)
try:
    df = pd.read_csv('/workspace/data.csv')
except FileNotFoundError:
    df = pd.DataFrame()

# Append new data
new_data = {'col1': [1, 2], 'col2': [3, 4]}
df = pd.concat([df, pd.DataFrame(new_data)])

# Save for next run
df.to_csv('/workspace/data.csv', index=False)
4

First Run Creates Sandbox

When workflow executes:
  • Checks if sandbox with user_defined_id exists
  • If not, creates new sandbox from template
  • Executes code in sandbox
  • Sandbox persists after workflow completes
5

Subsequent Runs Reuse Sandbox

Next workflow execution:
  • Finds sandbox by user_defined_id
  • Resumes sandbox (if paused)
  • Executes code in same environment
  • Previous files still available

​
Sandbox Operations

​
Pause Sandbox

When: Automatically after timeout or manually Effect:
  • Container stops
  • State saved to disk
  • No compute costs
  • Can resume instantly
Use case: Save money between workflow runs

​
Resume Sandbox

When: Workflow needs sandbox again Effect:
  • Container starts from saved state
  • Files and packages intact
  • Execution continues
Timing: Usually < 5 seconds

​
Destroy Sandbox

When: No longer needed or expired Effect:
  • Soft delete (can recover briefly)
  • Container removed
  • State lost
Use case: Cleanup after workflow completion

​
Use Cases

Stateful Agents

AI agents with persistent memory
  • Store conversation history
  • Cache knowledge bases
  • Maintain tool results across sessions
  • Build up state over time
Example: Customer support agent remembers context

Data Processing Pipelines

Incremental data processing
  • Download large datasets once
  • Process in chunks over multiple runs
  • Store intermediate results
  • Resume from last checkpoint
Example: ETL pipeline processes daily updates

ML Model Training

Train and serve models
  • Install ML frameworks once
  • Train models incrementally
  • Save checkpoints
  • Load models for inference
Example: Fine-tune LLM over multiple workflow runs

Web Scraping

Stateful browser automation
  • Maintain browser state
  • Store cookies and sessions
  • Cache scraped data
  • Resume interrupted scrapes
Example: Scrape site that requires login state

​
Cost Optimization

Pause quickly when idle❌ Timeout: 60 minutes (wasteful)✅ Timeout: 10 minutes (saves money)Sandbox pauses soon after workflow completes
Reuse same sandbox for related workflows
  • Use same user_defined_id
  • Multiple workflows access same files
  • Amortize setup costs
Example: Multiple analytics workflows share data sandbox
Clean up when done
  • Manually destroy completed sandboxes
  • Set auto-destroy policies
  • Review sandbox list periodically
Prevents storage cost buildup
Choose minimal base images❌ Full Ubuntu with GUI (large, slow)✅ Alpine Linux with Python (small, fast)Faster startup, lower storage costs

​
Best Practices

Descriptive user_defined_id❌ sandbox_1✅ customer_analytics_prodEasy to identify and manage
First run might not have files
try:
    data = pd.read_csv('/workspace/data.csv')
except FileNotFoundError:
    data = pd.DataFrame()  # Initialize empty
Pre-install common dependencies
  • Faster execution (no install wait)
  • More reliable (no network issues)
  • Better cost (install once)
Use custom templates for frequent packages
Track costs and activity
  • Review running sandboxes regularly
  • Check timeout settings
  • Monitor storage usage
  • Set alerts for long-running sandboxes

​
Troubleshooting

Symptoms: Can’t create sandboxSolutions:
  • Check template exists and is valid
  • Verify account has sandbox quota
  • Try different template
  • Check network connectivity
Symptoms: Files disappear between runsSolutions:
  • Ensure writing to /workspace/
  • Check disk space limits
  • Verify sandbox not being destroyed
  • Check if using correct user_defined_id
Symptoms: Sandbox pauses during executionSolutions:
  • Increase timeout setting
  • Optimize code to run faster
  • Split work into smaller chunks
  • Use manual pause/resume
Symptoms: Unexpected storage billsSolutions:
  • Check sandbox count and sizes
  • Clean up old files in /workspace
  • Destroy unused sandboxes
  • Compress large data files

​
What’s Next?

Sandbox Documentation

Detailed sandbox features and API

Code Execution

Run Python, JavaScript, and more

File Management

Upload, download, and organize files

Templates

Create custom sandbox templates