Doramagic Project Pack · Human Manual

code-interpreter

Python & JS/TS SDK for running AI-generated code/code interpreting in your AI app

Overview & Monorepo Architecture

Related topics: Client SDKs: JavaScript & Python APIs, Sandbox Template, Kernels & Custom Builds, Operations, Lifecycle & Common Failure Modes

Section Related Pages

Continue reading this section for the full explanation and source context.

Section JavaScript / TypeScript SDK (js/)

Continue reading this section for the full explanation and source context.

Section Python SDK (python/)

Continue reading this section for the full explanation and source context.

Section Sandbox Template (template/)

Continue reading this section for the full explanation and source context.

Related topics: Client SDKs: JavaScript & Python APIs, Sandbox Template, Kernels & Custom Builds, Operations, Lifecycle & Common Failure Modes

Overview & Monorepo Architecture

Purpose and Scope

The e2b-dev/code-interpreter repository is the canonical home of E2B's Code Interpreter — a stateful, AI-agent-friendly code execution service that runs arbitrary user code inside secure, isolated cloud sandboxes. The repository packages three independent, versioned artifacts that together form the runtime: a JavaScript/TypeScript client SDK, a Python client SDK, and the sandbox-side template (the Docker image and Jupyter configuration that executes the code). Source: README.md.

The repository is organized as a changesets-driven monorepo with separate version trains per package, evidenced by independent release tags: @e2b/code-interpreter (JS SDK), @e2b/code-interpreter-python (Python SDK), and @e2b/code-interpreter-template (the sandbox template). Source: community release notes (@e2b/[email protected], @e2b/[email protected], @e2b/[email protected]). This separation lets SDK clients move at a different cadence than the on-sandbox server, which historically has shipped multiple patches (e.g., 0.4.1 applying cwd to bash kernel contexts, 0.4.3 pinning jupyter-server root_dir for path-traversal hardening).

Repository Structure

The top-level layout splits the codebase into four logical workspaces. Source: README.md and per-package package.json / setup artifacts.

graph TB
    User["User Application<br/>(JS or Python)"]
    subgraph Repo["e2b-dev/code-interpreter (monorepo)"]
        SDKJS["js/<br/>@e2b/code-interpreter<br/>Node SDK"]
        SDKPY["python/<br/>e2b_code_interpreter<br/>Python SDK"]
        TPL["template/<br/>Sandbox image<br/>(Jupyter + multi-kernel)"]
        CDE["chart_data_extractor/<br/>Chart / DataFrame utilities"]
    end
    E2B["E2B Cloud<br/>Sandbox Infrastructure"]
    User -->|npm install| SDKJS
    User -->|pip install| SDKPY
    SDKJS -->|HTTPS + WS| E2B
    SDKPY -->|HTTPS + WS| E2B
    E2B -.->|provisions| TPL
    CDE -.->|bundled in template| TPL

The three SDK packages are independent and do not import each other at runtime. The chart_data_extractor is a self-contained utility bundled into the sandbox template; it is not a separately published public package. Source: chart_data_extractor/README.md ("This package is a utility used to extract data in the Code Interpreter SDK from, e.g., DataFrames and matplotlib plots").

Key Packages

JavaScript / TypeScript SDK (`js/`)

Published as @e2b/code-interpreter (current 2.6.0). It declares a single runtime dependency on e2b: ^2.28.0, which provides the underlying sandbox transport. Source: js/package.json.

FieldValue
Package name@e2b/code-interpreter
Version2.6.0
Package manager[email protected]
Node engine>=20
Build tooltsup (ESM + CJS, ES2017 target)
Type emissiondist/index.d.ts (dts: true)

Source: js/package.json and js/tsup.config.js. The SDK defines a Result class with rich-format accessors (text, html, markdown, svg, png, jpeg, pdf, latex, json, javascript, data, chart, extra) and an Execution wrapper containing results, logs (stdout/stderr), error, and executionCount. Source: js/src/messaging.ts.

Python SDK (`python/`)

Published as e2b_code_interpreter on PyPI. Its Result model mirrors the JS SDK's Result and exposes the same MIME-style fields (text, html, markdown, svg, png, jpeg, pdf, latex, json, javascript) plus Jupyter-style _repr_html_, _repr_markdown_, _repr_png_, _repr_jpeg_, _repr_pdf_, _repr_latex_, _repr_json_, _repr_javascript_ methods that render directly in notebook front-ends. Source: python/e2b_code_interpreter/models.py.

Sandbox Template (`template/`)

This is the server-side image that runs inside each E2B sandbox. It bundles Jupyter, an IPython kernel configured via a shipped profile, a FastAPI-style server exposing /result and /context models, and the multi-language kernels users select at sandbox-creation time. Source: template/ipython_kernel_config.py and template/server/api/models/result.py.

The template's Context Pydantic model exposes id, language, and cwd — the canonical execution-context tuple used by both kernels and the client SDK. Source: template/server/api/models/context.py.

A first-class build script (build_prod.py) builds the production template, while build_test.py builds a code-interpreter-dev alias with explicit kernel selection (["python", "javascript"]) for CI and local iteration. Source: template/build_test.py and template/README.md.

Build, Distribution, and Lifecycle

Production templates are versioned implicitly through the code-interpreter-template changesets package (recent patches 0.4.00.4.3 cover Deno-kernel removal, deferred heavy imports, cwd propagation, and jupyter-server root_dir pinning). Source: release notes for @e2b/code-interpreter-template. However, community issue #150 notes that published Docker images are tagged only as latest, making rollback impossible without a built-in version pin — a known architectural gap.

The sandbox lifecycle itself has been a frequent source of community questions. Issue #147 describes a sandbox disappearing mid-session despite a one-day timeout (an e2b.exceptions.TimeoutException on the server side), and issue #157 reports that beta_pause / beta_create deleted sandboxes unexpectedly. Release @e2b/[email protected] removed the beta helpers and folded the lifecycle option into Sandbox.create, which is the supported API surface today. Source: release notes for @e2b/[email protected].

For users who need faster cold starts than pip install allows, the recommended path is a custom template derived from code-interpreter-v1 via the E2B Template builder (e.g., swapping in uv as the default installer), as requested in community issue #175 and documented in template/README.md.

See Also

Source: https://github.com/e2b-dev/code-interpreter / Human Manual

Client SDKs: JavaScript & Python APIs

Related topics: Overview & Monorepo Architecture, Sandbox Template, Kernels & Custom Builds, Operations, Lifecycle & Common Failure Modes

Section Related Pages

Continue reading this section for the full explanation and source context.

Section 2.1 JavaScript package

Continue reading this section for the full explanation and source context.

Section 2.2 Python package

Continue reading this section for the full explanation and source context.

Related topics: Overview & Monorepo Architecture, Sandbox Template, Kernels & Custom Builds, Operations, Lifecycle & Common Failure Modes

Client SDKs: JavaScript & Python APIs

1. Overview and Scope

The e2b-dev/code-interpreter repository ships two language-specific client SDKs that wrap the upstream e2b core SDK and expose a higher-level Sandbox interface for running code inside a managed Jupyter-backed sandbox. The Python package is published as e2b_code_interpreter and the JavaScript/TypeScript package as @e2b/code-interpreter; both are thin, type-safe façades that target the same remote sandbox server and the same on-disk template (code-interpreter-v1).

Source: README.md

The SDKs' responsibilities are deliberately narrow:

  • Manage the sandbox lifecycle (create, kill, pause, connect) through Sandbox.create / Sandbox.beta_create and the underlying e2b primitives. Source: README.md
  • Execute user code via a Jupyter kernel and return a structured Execution object. Source: python/e2b_code_interpreter/models.py, js/src/messaging.ts
  • Project execution output in the rich formats that the Jupyter kernel emits (text, HTML, images, charts, JSON, LaTeX, etc.) so notebooks, web apps, and agents can consume them. Source: python/e2b_code_interpreter/models.py, js/src/messaging.ts

The SDKs are the only piece of the codebase a typical consumer links against; the Docker template, the kernel config, and the chart extractor package are build-time and server-side concerns.

2. Package Layout and Build

2.1 JavaScript package

The JavaScript SDK is a TypeScript-first module published from the js/ directory. Its package.json declares a peer runtime of node >= 20 and a single runtime dependency, the upstream e2b SDK, currently pinned at ^2.28.0. Source: js/package.json

"engines": { "node": ">=20" },
"dependencies": { "e2b": "^2.28.0" }

Build output is produced by tsup and is configured to emit both ESM and CommonJS bundles for the es2017 target, alongside .d.ts type definitions and sourcemaps, so the package can be consumed from both modern bundlers and older Node runtimes. Source: js/tsup.config.js

2.2 Python package

The Python package mirrors the JavaScript surface from python/e2b_code_interpreter/. The data-model module ships dataclasses with rich Jupyter _*repr*_ methods (_repr_html_, _repr_markdown_, _repr_svg_, _repr_png_, _repr_jpeg_, _repr_pdf_, _repr_latex_, _repr_json_, _repr_javascript_) so that Result objects render directly inside a notebook. Source: python/e2b_code_interpreter/models.py

3. Core API: `Sandbox` and `runCode`

Both SDKs expose a Sandbox class as the primary entry point. The README's quick-start shows the symmetric shape across languages. Source: README.md

// JavaScript / TypeScript
import { Sandbox } from '@e2b/code-interpreter'

const sbx = await Sandbox.create()
await sbx.runCode('x = 1')
const execution = await sbx.runCode('x+=1; x')
console.log(execution.text)  // outputs 2
# Python
from e2b_code_interpreter import Sandbox

with Sandbox.create() as sandbox:
    sandbox.run_code("x = 1")
    execution = sandbox.run_code("x+=1; x")
    print(execution.text)  # outputs 2

runCode is asynchronous in both SDKs and returns an Execution value that bundles:

  • results — the list of Result objects produced by the cell (one per displayed value).
  • logs — anything the kernel printed to stdout/stderr while the cell ran.
  • error — an optional ExecutionError when the cell raised.
  • executionCount — the cell's counter, matching the Jupyter protocol.

Source: js/src/messaging.ts, python/e2b_code_interpreter/models.py

The chart-data extractor sibling package converts matplotlib / DataFrame payloads into structured data that the SDKs return as Result.chart and Result.data. Source: chart_data_extractor/README.md

4. Data Model: `Result` and `Logs`

Result is the common envelope that carries a kernel output across all media types. The field set is the same in both SDKs and reflects the MIME types Jupyter can emit.

FieldTypePurpose
text / html / markdownstringHuman-readable representations of the value.
svg / png / jpeg / pdfstringBase64-encoded binary representations for inline display.
latex / javascript / jsonstringDomain-specific encodings (math, JS, structured data).
dataobjectRaw DataFrame-style payload.
chartobjectExtracted chart data (see chart_data_extractor).
extraobjectVendor / non-standard MIME payloads.
isMainResultboolMarks the value bound to the cell's last expression.

Source: js/src/messaging.ts, python/e2b_code_interpreter/models.py

Both SDKs expose:

  • formats() — returns the list of MIME-type strings actually populated on a Result. Source: js/src/messaging.ts, python/e2b_code_interpreter/models.py
  • toJSON() — a stable, serializable projection suitable for caching or sending over the wire. Source: js/src/messaging.ts, python/e2b_code_interpreter/models.py

Logs is a trivial { stdout: string[], stderr: string[] } container; the Python dataclass adds a to_json() helper. Source: python/e2b_code_interpreter/models.py

flowchart LR
    UserCode[User code string] --> RunCode[Sandbox.runCode]
    RunCode --> Kernel[Remote Jupyter kernel]
    Kernel --> Exec[Execution]
    Exec --> Results[Result[]]
    Exec --> Logs[Logs]
    Exec --> Error[ExecutionError?]
    Results --> Render{formats() / repr_* methods}
    Render --> Text[text / html / markdown]
    Render --> Img[svg / png / jpeg / pdf]
    Render --> Data[chart / data / json]

5. Recent Changes and Migration Notes

Several breaking changes and additions in recent releases directly affect SDK consumers:

  • v2.5.0 (Feb 2025)Sandbox.betaCreate (JS) and Sandbox.beta_create (Python) were removed. The earlier lifecycle beta was promoted onto Sandbox.create. Source: @e2b/[email protected] release notes. Community reports confirm that the legacy beta_pause/beta_create flow could delete the sandbox outright instead of pausing it (issue #157); the migration is to use the lifecycle option on Sandbox.create.
  • v2.6.0 (JS) / v2.8.0 (Python) — the SDKs were bumped to expose API-only custom header options for both the JavaScript and Python clients. Source: @e2b/[email protected] release notes, @e2b/[email protected] release notes.
  • v2.4.2 — the minimum supported e2b SDK version was raised, which is why the JS package.json now requires e2b ^2.28.0. Source: @e2b/[email protected] release notes.
  • Sandbox timeouts — users have reported TimeoutException: The sandbox was not found after short idle periods even when timeout is set to a day; this points to sandbox recycling on the server side, not an SDK bug (issue #147). For workloads that need warm environments, the lifecycle option on Sandbox.create is the supported alternative.
  • Image versioning — the published sandbox template is code-interpreter-v1; community concern (issue #150) about un-versioned Docker latest tags is tracked but does not affect the SDK API.

For users who need a different runtime (e.g. uv for faster dependency installs per issue #175), the SDKs accept a custom template argument that points at a user-built template derived from code-interpreter-v1 via the E2B Template SDK. Source: template/README.md

See Also

  • Template and Build Pipeline — how code-interpreter-v1 is assembled and how to fork it.
  • Chart Data Extractor — internal package that backs Result.chart.
  • Release Notes Index — chronological changelog for the JS and Python SDKs.

Source: https://github.com/e2b-dev/code-interpreter / Human Manual

Sandbox Template, Kernels & Custom Builds

Related topics: Overview & Monorepo Architecture, Client SDKs: JavaScript & Python APIs, Operations, Lifecycle & Common Failure Modes

Section Related Pages

Continue reading this section for the full explanation and source context.

Related topics: Overview & Monorepo Architecture, Client SDKs: JavaScript & Python APIs, Operations, Lifecycle & Common Failure Modes

Sandbox Template, Kernels & Custom Builds

Overview and Purpose

The Code Interpreter repository ships a single, layered sandbox image — currently aliased as code-interpreter-v1 — that powers every interactive code-execution surface exposed by the Python and JavaScript SDKs. The image is composed in template/template.py by a single builder function, make_template(), which deterministically assembles a Debian-based container on top of python:3.13, installs a configurable set of language kernels, and finalises against the code-interpreter HTTP server.

Users who need extra packages, a faster Python package manager, or pre-baked datasets extend (rather than fork) the image through the E2B Template API, as described in template/README.md. Community discussions such as Issue #175 (Need UV-based code-interpreter custom template) and Issue #150 (Docker images not versioned - everything is latest) have driven recurring improvements around install speed and reproducible versioning of these templates.

Template Architecture (`make_template`)

make_template() accepts four keyword arguments: kernels, is_docker, ready, and debug. The function always enables python and javascript, then unions that baseline with the caller-supplied kernels list. The default kernel set is ["python", "r", "javascript", "bash", "java"] (see template/template.py).

flowchart TD
    A["from_image('python:3.13')<br/>set_user('root') / set_workdir('/root')"] --> B["apt_install base packages<br/>+ NodeSource Node.js 20"]
    B --> C["copy requirements.txt<br/>pip_install -r requirements.txt"]
    C --> D{kernels union}
    D -->|python| E["ipython kernel install --name 'python3'"]
    D -->|r| F["apt r-base + IRkernel"]
    D -->|javascript| G["npm i ijavascript (git)<br/>+ ijsinstall --install=global"]
    D -->|bash| H["pip bash_kernel<br/>+ python -m bash_kernel.install"]
    D -->|java| I["OpenJDK + IJava"]
    E & F & G & H & I --> J["ReadyCmd wait_for_url<br/>or wait_for_timeout in debug"]

The base layer pins several environment variables to make Python installs predictable on slow networks (PIP_DEFAULT_TIMEOUT=100, PIP_DISABLE_PIP_VERSION_CHECK=1, PIP_NO_CACHE_DIR=1) and pins language toolchain versions (JAVA_VERSION=11, R_VERSION=4.5.*, IJAVA_VERSION=1.3.0) so the produced image is reproducible across rebuilds. The ready argument plugs into E2B's readiness signalling: by default the build waits on the server's /health endpoint, but build_debug.py passes wait_for_timeout(60_000) so a crash-looping server still finalises the image, as called out in template/README.md.

Supported Kernels

The matrix below is sourced directly from the conditional branches in template/template.py.

KernelInstall mechanismNotes
python (always on)ipython kernel install --name 'python3' --userRequired for SDK runCode to work.
javascript (always on)npm install --unsafe-perm git+https://github.com/e2b-dev/ijavascript.git + ijsinstall --install=globalPulls the patched fork e2b-dev/ijavascript from GitHub.
rapt_install r-base=4.5.* r-base-dev + IRkernel::installspec(name='r', displayname='R')Installs IRkernel from CRAN.
bashpip install bash_kernel + python -m bash_kernel.installcwd is honoured since template @e2b/[email protected] (community release notes).
javaOpenJDK 11 + IJava 1.3.0Java home pinned to /usr/lib/jvm/jdk-${JAVA_VERSION}.

Two historical kernels have been removed: the Deno kernel was dropped in template 0.4.0 ("remove Deno kernel"), and releases have continued to refine the Jupyter surface, e.g. pinning jupyter-server root_dir to /home/user in 0.4.3 to keep working with jupyter-server 2.18.0's path-traversal hardening.

Build Pipelines

The repository ships four entry points under template/, each producing a distinct alias:

ScriptAliasKernelsNotable flags
build_prod.pycode-interpreter-v1defaults (all five)SKIP_CACHE=true forces a clean rebuild ignoring the layer cache (template/build_prod.py)
build_test.pycode-interpreter-devpython, javascriptUses default_build_logger(min_level="debug") (template/build_test.py)
build_debug.pycode-interpreter-debug (or $E2B_DEBUG_TEMPLATE)python, javascriptready=wait_for_timeout(60_000), debug=True (template/build_debug.py)
build_ci.py$E2B_TESTS_TEMPLATEdefaultsWrites template_id to $GITHUB_OUTPUT for downstream CI jobs (template/build_ci.py)

The debug pipeline is the recommended escape hatch when the server inside the sandbox is failing to start. It (a) bypasses the /health probe so the image finalises even during a crash loop, and (b) installs a systemd drop-in that routes Jupyter's stdout to journalctl, leaving production builds with StandardOutput=null (template/README.md). Once a debug sandbox is running, template/debug_logs.py spawns it with a 600 s timeout and runs systemctl status, journalctl, and the two probe curls (jupyter :8888/api/status, server :49999/health) for triage.

Creating a Custom Template

Per template/README.md, the supported extension path is Template().from_template("code-interpreter-v1"), then Template.build(...) with an alias, cpu_count, memory_mb, and on_build_logs=default_build_logger(). Credentials must be present in .env as E2B_API_KEY. This pattern is what addresses requests like Issue #175: instead of waiting on pip install inside every runCode call, the dependency graph is baked into a custom image and reused across sandboxes.

Common Failure Modes

  • Sandbox disappears mid-session. Reported in Issue #147 (The sandbox was not found) as e2b.exceptions.TimeoutException. The root cause is usually an idle timeout shorter than the actual usage window; the SDK surfaces the timeout through the lifecycle option that replaced the removed Sandbox.beta_create / Sandbox.betaCreate (release @e2b/[email protected]).
  • beta_pause / beta_create deletion behaviour. Issue #157 documented that the now-removed beta API deleted sandboxes; current code should use Sandbox.create(..., lifecycle=...) per the migration note in 2.5.0.
  • Unversioned templates. Because template builds publish only to mutable aliases, Issue #150 recommends pinning the resolved template_id (the same value emitted by build_ci.py into GITHUB_OUTPUT) rather than the alias.

See Also

  • E2B Template docs — official guide for Template.from_template extension.
  • template/README.md — authoritative build instructions used in CI and releases.
  • Release notes for @e2b/code-interpreter-template track template-side changes (cwd handling, dependency pin, perf).

Source: https://github.com/e2b-dev/code-interpreter / Human Manual

Operations, Lifecycle & Common Failure Modes

Related topics: Overview & Monorepo Architecture, Client SDKs: JavaScript & Python APIs, Sandbox Template, Kernels & Custom Builds

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Stable vs. Deprecated API Surface

Continue reading this section for the full explanation and source context.

Section Operational Checklist

Continue reading this section for the full explanation and source context.

Related topics: Overview & Monorepo Architecture, Client SDKs: JavaScript & Python APIs, Sandbox Template, Kernels & Custom Builds

Operations, Lifecycle & Common Failure Modes

This page covers the operational surface of the E2B Code Interpreter: how a sandbox is created, executed against, and torn down; how the production and debug templates are built and observed; and the failure modes reported by users in the issue tracker and changelog.

Sandbox Lifecycle and Data Envelopes

The Code Interpreter SDK wraps the underlying E2B sandbox primitive with execution primitives (runCode), kernel state, and rich result envelopes. Operationally, every interaction follows a simple lifecycle: instantiate → execute → observe → terminate.

The Result class on both the Python and JavaScript sides exposes a uniform set of MIME-typed representations — text, html, markdown, svg, png, jpeg, pdf, latex, json, javascript, data, chart, plus an extra bag — so consumers can pick the representation best suited to their UI or log pipeline. Source: python/e2b_code_interpreter/models.py:1-80, js/src/messaging.ts:1-80.

The Execution envelope wraps results[], logs = { stdout: string[], stderr: string[] }, an optional ExecutionError carrying name, value, and traceback, and an executionCount mirroring Jupyter semantics. Source: js/src/messaging.ts:80-160.

Stable vs. Deprecated API Surface

Recent SDK releases (2.5.0 / 2.7.0) removed the beta lifecycle methods in favor of a unified lifecycle option on Sandbox.create:

// before
await Sandbox.betaCreate({ /* ... */ })
// after
await Sandbox.create({ /* ... */, lifecycle: { /* ... */ } })

A community report (issue #157) showed that calling the removed beta_pause / beta_create deletes the sandbox outright. Operators still on those code paths should migrate to Sandbox.create(..., lifecycle=...) before upgrading.

Production Template Operations

The template/ directory owns the sandbox image that is deployed as code-interpreter-v1.

  • CI build entrypointtemplate/build_ci.py calls Template.build(make_template(), alias=os.environ["E2B_TESTS_TEMPLATE"], cpu_count=2, memory_mb=2048, ...) and writes the resulting template_id to $GITHUB_OUTPUT for downstream CI jobs. Source: template/build_ci.py:1-12.
  • End-to-end buildtemplate/README.md documents installing requirements-dev.txt, setting E2B_API_KEY in .env, and running python build_prod.py. SKIP_CACHE=true forces a clean rebuild that bypasses the layer cache. Source: template/README.md:30-80.
  • Custom templatesTemplate().from_template("code-interpreter-v1") lets you fork the official image; Template.build accepts the same cpu_count / memory_mb knobs. Source: template/README.md:50-90.
  • Kernel configurationtemplate/ipython_kernel_config.py controls ZMQInteractiveShell, session, and kernel-app behavior. The banner confirms IPython 8.22.2 ships with the image. Source: template/ipython_kernel_config.py:1-30.
  • SDK dependency floor@e2b/[email protected] raised the minimum supported e2b SDK version, and the JavaScript side pins e2b ^2.28.0 in package.json. Source: js/package.json:1-40.

In-Sandbox Observability and Debug Operations

The repository ships a first-class debug workflow rather than asking users to attach to a black box.

template/debug_logs.py boots a sandbox from the code-interpreter-debug alias, runs a curated probe list, and prints the results locally before kill()-ing the sandbox. The probe list inspects both systemd units and the two HTTP services. Source: template/debug_logs.py:1-30.

ProbeWhat it checks
systemctl --no-pager status jupyterJupyter systemd unit health
systemctl --no-pager status code-interpreterCode interpreter service health
journalctl --no-pager -u jupyterJupyter logs
journalctl --no-pager -u code-interpreterCode interpreter logs
curl http://localhost:8888/api/statusJupyter HTTP probe
curl http://localhost:49999/healthCode interpreter HTTP probe

make debug-template automates the same workflow: it produces a debug template gated on a fixed timeout (so the template finalizes even if the server is crash-looping), spawns a sandbox, and prints the probe output. The debug build also drops in a systemd unit that routes Jupyter's stdout to the journal, whereas the production template keeps StandardOutput=null. Source: template/README.md:1-30.

Common Failure Modes

The community thread and changelog surface a recurring set of failure modes that operators should anticipate:

FailureSymptomMitigation
Sandbox disappears mid-sessione2b.exceptions.TimeoutException "The sandbox was not found" (issue #147)Confirm the timeout you passed, account for sandbox auto-pause/resume, and re-create on miss
Beta lifecycle API used post-2.5.0beta_pause / beta_create deletes the sandbox (issue #157)Migrate to Sandbox.create(..., lifecycle=...)
Unversioned imageslatest tag is overwritten on rebuild (issue #150)Pin to a specific template_id from the build output; track template_id in CI artifacts (see build_ci.py)
Slow pip install in fresh sandboxesCold-start dominated by dependency installation (issue #175)Build a UV-based custom template derived from code-interpreter-v1
Jupyter 2.18.0 path-traversal hardeningSession creation failsPinned in template 0.4.3 — root_dir=/home/user
cwd ignored by bash kernelpwd returns / regardless of requestFixed in template 0.4.1
Deno kernelRemovedTemplate 0.4.0 no longer ships Deno

Operational Checklist

  1. Pin templates by template_id, not by the latest alias.
  2. Wrap Sandbox.create calls in retry logic; treat TimeoutException as recoverable.
  3. For deep investigation, build with make debug-template and run the debug_logs.py probe list.
  4. Track SDK and template versions together — template patches (0.4.0–0.4.3) have shipped alongside SDK minors (2.4.2–2.6.0).

See Also

  • Custom Templates & build pipeline — template/README.md
  • Result / Execution data model — python/e2b_code_interpreter/models.py, js/src/messaging.ts
  • Chart data extraction utility — chart_data_extractor/README.md

Source: https://github.com/e2b-dev/code-interpreter / Human Manual

Doramagic Pitfall Log

Source-linked risks stay visible on the manual page so the preview does not read like a recommendation.

high Installation risk requires verification

May increase setup, validation, or first-run risk for the user.

high Security or permission risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Installation risk requires verification

Upgrade or migration may change expected behavior: @e2b/[email protected]

medium Installation risk requires verification

Upgrade or migration may change expected behavior: @e2b/[email protected]

Doramagic Pitfall Log

Found 26 structured pitfall item(s), including 2 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

  • Severity: high
  • Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/e2b-dev/code-interpreter/issues/150

2. Security or permission risk: Security or permission risk requires verification

  • Severity: high
  • Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/e2b-dev/code-interpreter/issues/200

3. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Developers should check this installation risk before relying on the project: @e2b/[email protected]
  • User impact: Upgrade or migration may change expected behavior: @e2b/[email protected]
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: @e2b/[email protected]. Context: Observed when using python
  • Evidence: failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-python%402.6.2

4. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Developers should check this installation risk before relying on the project: @e2b/[email protected]
  • User impact: Upgrade or migration may change expected behavior: @e2b/[email protected]
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: @e2b/[email protected]. Context: Source discussion did not expose a precise runtime context.
  • Evidence: failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter%402.4.2

5. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Developers should check this installation risk before relying on the project: Dependency Dashboard
  • User impact: Developers may fail before the first successful local run: Dependency Dashboard
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Dependency Dashboard. Context: Observed when using node, python, docker, linux
  • Evidence: failure_mode_cluster:github_issue | https://github.com/e2b-dev/code-interpreter/issues/200

6. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Developers should check this installation risk before relying on the project: Need UV-based code-interpreter custom template
  • User impact: Developers may fail before the first successful local run: Need UV-based code-interpreter custom template
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Need UV-based code-interpreter custom template. Context: Observed when using python
  • Evidence: failure_mode_cluster:github_issue | https://github.com/e2b-dev/code-interpreter/issues/175

7. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/e2b-dev/code-interpreter/issues/175

8. Configuration risk: Configuration risk requires verification

  • Severity: medium
  • Finding: Developers should check this configuration risk before relying on the project: @e2b/[email protected]
  • User impact: Upgrade or migration may change expected behavior: @e2b/[email protected]
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: @e2b/[email protected]. Context: Observed when using python
  • Evidence: failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-python%402.7.0

9. Configuration risk: Configuration risk requires verification

  • Severity: medium
  • Finding: Developers should check this configuration risk before relying on the project: @e2b/[email protected]
  • User impact: Upgrade or migration may change expected behavior: @e2b/[email protected]
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: @e2b/[email protected]. Context: Observed when using python
  • Evidence: failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter%402.5.0

10. Capability evidence risk: Capability evidence risk requires verification

  • Severity: medium
  • Finding: README/documentation is current enough for a first validation pass.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: capability.assumptions | github_repo:770633006 | https://github.com/e2b-dev/code-interpreter

11. Runtime risk: Runtime risk requires verification

  • Severity: medium
  • Finding: Developers should check this runtime risk before relying on the project: The beta_pause and beta_create delete my sandbox directly
  • User impact: Developers may hit a documented source-backed failure mode: The beta_pause and beta_create delete my sandbox directly
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: The beta_pause and beta_create delete my sandbox directly. Context: Observed when using python
  • Evidence: failure_mode_cluster:github_issue | https://github.com/e2b-dev/code-interpreter/issues/157

12. Runtime risk: Runtime risk requires verification

  • Severity: medium
  • Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/e2b-dev/code-interpreter/issues/157

Source: Doramagic discovery, validation, and Project Pack records

Community Discussion Evidence

These external discussion links are review inputs, not standalone proof that the project is production-ready.

Sources 12

Count of project-level external discussion links exposed on this manual page.

Use Review before install

Open the linked issues or discussions before treating the pack as ready for your environment.

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using code-interpreter with real data or production workflows.

Source: Project Pack community evidence and pitfall evidence