@e2b/code-interpreter

@e2b/code-interpreter is the JS/TS client for E2B’s Code Interpreter, a purpose-built sandbox template for executing untrusted or AI-generated code safely. It wraps the base E2B Sandbox SDK with a Jupyter-kernel-backed execution layer, so calling sandbox.runCode() runs Python, JavaScript, TypeScript, R, Java, or Bash inside an isolated cloud VM and streams back stdout, stderr, rich results (charts, images, dataframes), and structured errors.

Because each sandbox keeps a persistent kernel context, variables and imports declared in one runCode call are still available in the next - letting an LLM agent iteratively build up state (load a dataset, then transform it, then plot it) the same way a human would in a notebook, without re-executing setup code on every turn.

What You Get

• A Sandbox.create() / sandbox.runCode() API built on top of E2B’s isolated cloud VMs, extending the base e2b Sandbox class
• Stateful Jupyter-kernel execution contexts - variables and imports persist across multiple runCode calls in the same sandbox
• Multi-language support out of the box: Python, JavaScript, TypeScript, R, Java, and Bash
• Structured onStdout/onStderr/onResult/onError callbacks plus rich Result objects for charts, images, and other Jupyter display data
• Runtime coverage across Node, Bun, and Deno, verified by dedicated per-runtime test suites

Common Use Cases

• Letting an LLM agent execute Python data-analysis code it generated, then read back computed results, tables, or matplotlib charts
• Building AI code-assistant products that need to actually run and verify generated code rather than just display it
• Iterative, notebook-style agent workflows where state (loaded data, defined functions) must persist across several tool calls
• Safely executing user-submitted or untrusted code in a fully isolated VM instead of the host process

Under The Hood

Architecture - The package is a thin, purpose-built layer over the base e2b Sandbox SDK: sandbox.ts extends BaseSandbox and adds runCode/createCodeContext, messaging.ts defines the Result/Execution/OutputMessage wire types and parses Jupyter-style output messages into them, and charts.ts normalizes matplotlib/plotly-style chart output into a consistent JS representation. Execution requests are proxied to a Jupyter kernel running inside the sandboxed VM over the JUPYTER_PORT defined in consts.ts, with utils.ts handling connection-closed detection and line-based streaming reads. Tech Stack - TypeScript compiled with tsup to dual ESM/CJS output, built on the e2b npm package (^2.28.0) as its only runtime dependency, tested with Vitest plus dedicated Bun and Deno test runs to guarantee cross-runtime compatibility, linted with ESLint and formatted with Prettier. Code Quality - The js/tests/ directory has 33+ test files covering execution semantics (statefulness, execution count, interrupts, reconnects), specific data/display types (charts, images, env vars), and runtime-specific behavior (tests/runtimes/bun, tests/runtimes/deno), indicating deliberate attention to correctness across execution edge cases and multiple JS runtimes. API Design - The public surface mirrors familiar async patterns (await Sandbox.create(), await sbx.runCode(...)) with optional streaming callbacks for stdout/stderr/results, keeping the common case to two or three lines of code while still exposing execution contexts and rich result objects for more advanced multi-step agent workflows.