Skip to main content
Sandbox provides a full Linux compute environment for running complex workloads. Install packages, use system tools, and execute long-running processes.

Key Features

  • Full Linux Environment - Ubuntu with bash shell
  • Package Management - pip (Python), npm (Node.js)
  • System Tools - curl, wget, git, ffmpeg, imagemagick, and more
  • Persistent Session - Files persist within same session
  • Higher Limits - 5-minute default timeout, up to 12GB memory

How to Enable

For Agents

  1. Agents > Select Agent > Settings > Capabilities
  2. Attach Sandbox

For MCP Gateways

  1. Gateways > Select Gateway > Capabilities
  2. Attach Sandbox

Usage Examples

Install and Use Package

#!/bin/bash
pip install requests beautifulsoup4
python3 << 'EOF'
import requests
from bs4 import BeautifulSoup

response = requests.get("https://example.com")
soup = BeautifulSoup(response.content, "html.parser")
print(len(soup.find_all("a")))
EOF

Process Images

#!/bin/bash
# Convert and resize image
convert input.jpg -resize 200x200 output.jpg
identify output.jpg

Complex Data Pipeline

#!/bin/bash
pip install pandas numpy scikit-learn

python3 << 'EOF'
import pandas as pd
import numpy as np

data = pd.read_csv("data.csv")
processed = data.dropna()
print(f"Rows: {len(processed)}")
print(processed.describe())
EOF

Environment Details

Available Languages

  • Python 3.11 - Full stdlib + pip
  • Node.js 20 - npm/yarn support
  • Bash/Shell - Full command line access
  • Other tools - git, curl, wget, ffmpeg, etc.

Size Tiers

SizevCPUsMemoryDisk
XS0.251 GB4 GB
SM (default)0.54 GB8 GB
MD1.06 GB12 GB
LG2.08 GB16 GB
XL4.012 GB20 GB

Storage

  • Session-scoped - Data deleted after session ends
  • Files capability - Persistent storage (separate)

Resource Limits

LimitValueNotes
Command Timeout5 min default, 30 min maxConfigurable per execution
Max Lifetime60 minutesAuto-terminates after 1 hour
Idle Timeout20 minutesAuto-terminates if idle
Containers per Session1One active at a time
Default SizeSM0.5 vCPU, 4 GB RAM, 8 GB disk
NetworkOutbound onlyNo inbound connections
Package InstallationUnlimitedAny language packages

Difference from Code Runner

FeatureCode RunnerSandbox
Timeout30 seconds5 min default, 30 min max
Memory128MB1 GB – 12 GB (by size)
StorageNone4 GB – 20 GB (by size)
PackagesNonepip, npm
System toolsNonecurl, ffmpeg, etc.
CostLowHigher
Use Code Runner for: Quick calculations, simple tasks Use Sandbox for: Package installation, heavy computation, external tools

Common Use Cases

Data Processing

pip install pandas
python3 << 'EOF'
import pandas as pd
df = pd.read_csv("data.csv")
result = df.groupby("category").sum()
print(result)
EOF

Web Scraping

pip install beautifulsoup4 requests
python3 << 'EOF'
import requests
from bs4 import BeautifulSoup
# Scrape and parse HTML
EOF

Image/Video Processing

ffmpeg -i input.mp4 -vf scale=320:240 output.mp4
convert image.jpg -blur 0x8 blurred.jpg

Database Operations

pip install psycopg2 sqlalchemy
python3 << 'EOF'
import psycopg2
# Connect and query database
EOF

Cost

For current pricing details, see Pricing. Monitor in Account > Usage dashboard.

Best Practices

Install Strategically

Only install packages you need:
pip install --no-deps package-name  # Skip dependencies if not needed

Set Resource Limits

Prevent runaway processes:
timeout 30 python3 script.py  # Auto-kill after 30 seconds

Use Virtual Environments

Avoid conflicts with environment setup:
python3 -m venv venv
source venv/bin/activate
pip install requirements

Monitor Output

Keep track of what’s happening:
set -x  # Enable debug output
python3 script.py 2>&1 | head -100

Troubleshooting

Session Timeout

Command exceeded timeout (5 min default, 30 min max). Break into smaller tasks or optimize code.

Out of Memory

Exceeded memory for your size tier. Scale up or process in batches.

Package Installation Fails

  • Check package name is correct
  • Ensure compatible Python/Node version
  • Try installing dependencies separately

File Not Found

Session storage is temporary. Use Files capability for persistent storage.

Next Steps