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
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
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| TPLThe 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.
| Field | Value |
|---|---|
| Package name | @e2b/code-interpreter |
| Version | 2.6.0 |
| Package manager | [email protected] |
| Node engine | >=20 |
| Build tool | tsup (ESM + CJS, ES2017 target) |
| Type emission | dist/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.0–0.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
- Python SDK
Resultmodel reference (seepython/e2b_code_interpreter/models.py) - Sandbox template build & customization (see
template/README.md) - Custom-template quickstart on e2b.dev
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
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
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) throughSandbox.create/Sandbox.beta_createand the underlyinge2bprimitives. Source: README.md - Execute user code via a Jupyter kernel and return a structured
Executionobject. 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 ofResultobjects produced by the cell (one per displayed value).logs— anything the kernel printed tostdout/stderrwhile the cell ran.error— an optionalExecutionErrorwhen 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.
| Field | Type | Purpose |
|---|---|---|
text / html / markdown | string | Human-readable representations of the value. |
svg / png / jpeg / pdf | string | Base64-encoded binary representations for inline display. |
latex / javascript / json | string | Domain-specific encodings (math, JS, structured data). |
data | object | Raw DataFrame-style payload. |
chart | object | Extracted chart data (see chart_data_extractor). |
extra | object | Vendor / non-standard MIME payloads. |
isMainResult | bool | Marks 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 aResult. Source: js/src/messaging.ts, python/e2b_code_interpreter/models.pytoJSON()— 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) andSandbox.beta_create(Python) were removed. The earlierlifecyclebeta was promoted ontoSandbox.create. Source: @e2b/[email protected] release notes. Community reports confirm that the legacybeta_pause/beta_createflow could delete the sandbox outright instead of pausing it (issue #157); the migration is to use thelifecycleoption onSandbox.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
e2bSDK version was raised, which is why the JSpackage.jsonnow requirese2b ^2.28.0. Source: @e2b/[email protected] release notes. - Sandbox timeouts — users have reported
TimeoutException: The sandbox was not foundafter short idle periods even whentimeoutis 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, thelifecycleoption onSandbox.createis the supported alternative. - Image versioning — the published sandbox template is
code-interpreter-v1; community concern (issue #150) about un-versioned Dockerlatesttags 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-v1is 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
Continue reading this section for the full explanation and source context.
Related Pages
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.
| Kernel | Install mechanism | Notes |
|---|---|---|
python (always on) | ipython kernel install --name 'python3' --user | Required for SDK runCode to work. |
javascript (always on) | npm install --unsafe-perm git+https://github.com/e2b-dev/ijavascript.git + ijsinstall --install=global | Pulls the patched fork e2b-dev/ijavascript from GitHub. |
r | apt_install r-base=4.5.* r-base-dev + IRkernel::installspec(name='r', displayname='R') | Installs IRkernel from CRAN. |
bash | pip install bash_kernel + python -m bash_kernel.install | cwd is honoured since template @e2b/[email protected] (community release notes). |
java | OpenJDK 11 + IJava 1.3.0 | Java 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:
| Script | Alias | Kernels | Notable flags |
|---|---|---|---|
build_prod.py | code-interpreter-v1 | defaults (all five) | SKIP_CACHE=true forces a clean rebuild ignoring the layer cache (template/build_prod.py) |
build_test.py | code-interpreter-dev | python, javascript | Uses default_build_logger(min_level="debug") (template/build_test.py) |
build_debug.py | code-interpreter-debug (or $E2B_DEBUG_TEMPLATE) | python, javascript | ready=wait_for_timeout(60_000), debug=True (template/build_debug.py) |
build_ci.py | $E2B_TESTS_TEMPLATE | defaults | Writes 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 thelifecycleoption that replaced the removedSandbox.beta_create/Sandbox.betaCreate(release @e2b/[email protected]). beta_pause/beta_createdeletion behaviour. Issue #157 documented that the now-removed beta API deleted sandboxes; current code should useSandbox.create(..., lifecycle=...)per the migration note in2.5.0.- Unversioned templates. Because template builds publish only to mutable aliases, Issue #150 recommends pinning the resolved
template_id(the same value emitted bybuild_ci.pyintoGITHUB_OUTPUT) rather than the alias.
See Also
- E2B Template docs — official guide for
Template.from_templateextension. - template/README.md — authoritative build instructions used in CI and releases.
- Release notes for
@e2b/code-interpreter-templatetrack 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
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
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 entrypoint —
template/build_ci.pycallsTemplate.build(make_template(), alias=os.environ["E2B_TESTS_TEMPLATE"], cpu_count=2, memory_mb=2048, ...)and writes the resultingtemplate_idto$GITHUB_OUTPUTfor downstream CI jobs. Source: template/build_ci.py:1-12. - End-to-end build —
template/README.mddocuments installingrequirements-dev.txt, settingE2B_API_KEYin.env, and runningpython build_prod.py.SKIP_CACHE=trueforces a clean rebuild that bypasses the layer cache. Source: template/README.md:30-80. - Custom templates —
Template().from_template("code-interpreter-v1")lets you fork the official image;Template.buildaccepts the samecpu_count/memory_mbknobs. Source: template/README.md:50-90. - Kernel configuration —
template/ipython_kernel_config.pycontrolsZMQInteractiveShell, 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 supportede2bSDK version, and the JavaScript side pinse2b ^2.28.0inpackage.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.
| Probe | What it checks |
|---|---|
systemctl --no-pager status jupyter | Jupyter systemd unit health |
systemctl --no-pager status code-interpreter | Code interpreter service health |
journalctl --no-pager -u jupyter | Jupyter logs |
journalctl --no-pager -u code-interpreter | Code interpreter logs |
curl http://localhost:8888/api/status | Jupyter HTTP probe |
curl http://localhost:49999/health | Code 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:
| Failure | Symptom | Mitigation |
|---|---|---|
| Sandbox disappears mid-session | e2b.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.0 | beta_pause / beta_create deletes the sandbox (issue #157) | Migrate to Sandbox.create(..., lifecycle=...) |
| Unversioned images | latest 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 sandboxes | Cold-start dominated by dependency installation (issue #175) | Build a UV-based custom template derived from code-interpreter-v1 |
| Jupyter 2.18.0 path-traversal hardening | Session creation fails | Pinned in template 0.4.3 — root_dir=/home/user |
cwd ignored by bash kernel | pwd returns / regardless of request | Fixed in template 0.4.1 |
| Deno kernel | Removed | Template 0.4.0 no longer ships Deno |
Operational Checklist
- Pin templates by
template_id, not by thelatestalias. - Wrap
Sandbox.createcalls in retry logic; treatTimeoutExceptionas recoverable. - For deep investigation, build with
make debug-templateand run thedebug_logs.pyprobe list. - 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.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
Upgrade or migration may change expected behavior: @e2b/[email protected]
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.
Count of project-level external discussion links exposed on this manual page.
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.
- Dependency Dashboard - github / github_issue
- Docker images are not versioned - everything is
latest- github / github_issue - The sandbox was not found - github / github_issue
- The beta_pause and beta_create delete my sandbox directly - github / github_issue
- Need UV-based code-interpreter custom template - github / github_issue
- @e2b/[email protected] - github / github_release
- @e2b/[email protected] - github / github_release
- @e2b/[email protected] - github / github_release
- @e2b/[email protected] - github / github_release
- @e2b/[email protected] - github / github_release
- @e2b/[email protected] - github / github_release
- @e2b/[email protected] - github / github_release
Source: Project Pack community evidence and pitfall evidence