E2B Sandbox Helper

Step 1: Analyze Codebase Context

Before providing guidance, understand the project:

# Find SDK version and sandbox usage
grep -r "e2b" package.json requirements.txt pyproject.toml 2>/dev/null
grep -r "Sandbox" --include="*.py" --include="*.ts" --include="*.js" .
grep -r "timeout" --include="*.py" --include="*.ts" --include="*.js" .

Read relevant files to understand sandbox lifecycle, error handling, and timeout configuration.

Step 2: Check Build System

# Detect legacy vs modern build system
find . -name "e2b.Dockerfile" -o -name "e2b.toml" 2>/dev/null
grep -rl "from e2b import Template\|Template()" --include="*.py" . 2>/dev/null

Found	Build System	Action
e2b.Dockerfile	Legacy (v1)	Recommend migration
Template() usage	Modern (v2)	Good
Nothing	No custom template	Use default OR Build System 2.0

IMPORTANT:

• For legacy systems: Suggest e2b template migrate
• For new custom templates: ALWAYS use Build System 2.0 with Template(). NEVER create e2b.Dockerfile or e2b.toml files.

See BUILD-SYSTEM.md for how to build custom templates.

Step 3: Fetch Documentation

1. MCP (preferred) - Check if mcp__e2b-docs__SearchE2BDocs is available. If yes, use it:

mcp__e2b-docs__SearchE2BDocs({ query: "auto pause sandbox" })

If MCP is NOT available, prompt the user:

"I recommend installing the E2B docs MCP for faster lookups. Run: claude mcp add --transport http e2b-docs https://e2b.dev/mcp"

2. WebFetch - Fetch https://e2b.dev/docs/llms.txt first to find the right URL, then fetch the specific page.

Step 4: Code Review

Copy this checklist:

E2B Code Review:
- [ ] Timeout configured (Python: seconds, JS: timeoutMs in ms)
- [ ] Python uses Sandbox.create(), not Sandbox()
- [ ] Exception handling around sandbox.run_code()
- [ ] Cleanup guaranteed (context manager or finally block)
- [ ] Sandbox validation before operations
- [ ] Streaming for long operations (on_stdout/on_stderr)
- [ ] Errors returned to LLM for self-correction

Report Format

## E2B Code Review Results

### Critical Issues
1. **[CRITICAL]** Issue description
   - File: `path:line`
   - Fix: `code example`

Quick Reference

SDK Differences

	Python	JavaScript
Timeout param	timeout (seconds)	timeoutMs (milliseconds)
Create sandbox	Sandbox.create()	Sandbox.create()
5 min timeout	timeout=300	timeoutMs=300000

Common Gotchas

Symptom	Cause	Solution
"Sandbox not found"	Timeout expired	Increase timeout, use set_timeout()
502 Bad Gateway	Sandbox timeout	Increase timeout at creation
Code runs, no output	Wrong location	Check logs.stdout, not just results
Template build fails	Alpine or missing -y	Use Debian-based, add -y to apt

Note: set_timeout() RESETS from now, doesn't ADD to remaining time.

Execution Result Structure

execution = sandbox.run_code(code)

if execution.error:
    execution.error.name       # Error type
    execution.error.value      # Message
    execution.error.traceback  # Full traceback

execution.results    # Jupyter-style outputs (plots, dataframes)
execution.logs.stdout  # print() output
execution.logs.stderr  # Errors, warnings
execution.text       # Main result as string

Detailed References

• Code templates: See TEMPLATES.md
• CLI & Python snippets: See CLI.md
• Custom template building: See BUILD-SYSTEM.md
• File operations (read/write) & advanced patterns: See REFERENCE.md