# https://github.com/e2b-dev/code-interpreter Project Manual

Generated at: 2026-06-14 00:30:11 UTC

## Table of Contents

- [Overview & Monorepo Architecture](#page-1)
- [Client SDKs: JavaScript & Python APIs](#page-2)
- [Sandbox Template, Kernels & Custom Builds](#page-3)
- [Operations, Lifecycle & Common Failure Modes](#page-4)

<a id='page-1'></a>

## Overview & Monorepo Architecture

### Related Pages

Related topics: [Client SDKs: JavaScript & Python APIs](#page-2), [Sandbox Template, Kernels & Custom Builds](#page-3), [Operations, Lifecycle & Common Failure Modes](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/e2b-dev/code-interpreter/blob/main/README.md)
- [js/package.json](https://github.com/e2b-dev/code-interpreter/blob/main/js/package.json)
- [js/tsup.config.js](https://github.com/e2b-dev/code-interpreter/blob/main/js/tsup.config.js)
- [js/src/messaging.ts](https://github.com/e2b-dev/code-interpreter/blob/main/js/src/messaging.ts)
- [python/e2b_code_interpreter/models.py](https://github.com/e2b-dev/code-interpreter/blob/main/python/e2b_code_interpreter/models.py)
- [template/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/template/README.md)
- [template/build_test.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/build_test.py)
- [template/template.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/template.py)
- [template/ipython_kernel_config.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/ipython_kernel_config.py)
- [template/server/api/models/result.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/server/api/models/result.py)
- [template/server/api/models/context.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/server/api/models/context.py)
- [chart_data_extractor/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/chart_data_extractor/README.md)
</details>

# 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](https://github.com/e2b-dev/code-interpreter/blob/main/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/code-interpreter@2.6.0, @e2b/code-interpreter-python@2.8.0, @e2b/code-interpreter-template@0.4.3)](https://github.com/e2b-dev/code-interpreter/releases). 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](https://github.com/e2b-dev/code-interpreter/blob/main/README.md) and per-package `package.json` / `setup` artifacts.

```mermaid
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](https://github.com/e2b-dev/code-interpreter/blob/main/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](https://github.com/e2b-dev/code-interpreter/blob/main/js/package.json).

| Field | Value |
|---|---|
| Package name | `@e2b/code-interpreter` |
| Version | `2.6.0` |
| Package manager | `pnpm@9.15.9` |
| Node engine | `>=20` |
| Build tool | `tsup` (ESM + CJS, ES2017 target) |
| Type emission | `dist/index.d.ts` (`dts: true`) |

Source: [js/package.json](https://github.com/e2b-dev/code-interpreter/blob/main/js/package.json) and [js/tsup.config.js](https://github.com/e2b-dev/code-interpreter/blob/main/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](https://github.com/e2b-dev/code-interpreter/blob/main/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](https://github.com/e2b-dev/code-interpreter/blob/main/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](https://github.com/e2b-dev/code-interpreter/blob/main/template/ipython_kernel_config.py) and [template/server/api/models/result.py](https://github.com/e2b-dev/code-interpreter/blob/main/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](https://github.com/e2b-dev/code-interpreter/blob/main/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](https://github.com/e2b-dev/code-interpreter/blob/main/template/build_test.py) and [template/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/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](https://github.com/e2b-dev/code-interpreter/releases). However, community issue [#150](https://github.com/e2b-dev/code-interpreter/issues/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](https://github.com/e2b-dev/code-interpreter/issues/147) describes a sandbox disappearing mid-session despite a one-day timeout (an `e2b.exceptions.TimeoutException` on the server side), and issue [#157](https://github.com/e2b-dev/code-interpreter/issues/157) reports that `beta_pause` / `beta_create` deleted sandboxes unexpectedly. Release `@e2b/code-interpreter@2.5.0` removed the beta helpers and folded the `lifecycle` option into `Sandbox.create`, which is the supported API surface today. Source: [release notes for @e2b/code-interpreter@2.5.0](https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter%402.5.0).

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](https://github.com/e2b-dev/code-interpreter/issues/175) and documented in [template/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/template/README.md).

## See Also

- [Python SDK `Result` model reference](#) (see `python/e2b_code_interpreter/models.py`)
- [Sandbox template build & customization](#) (see `template/README.md`)
- [Custom-template quickstart on e2b.dev](https://e2b.dev/docs/template/quickstart)

---

<a id='page-2'></a>

## Client SDKs: JavaScript & Python APIs

### Related Pages

Related topics: [Overview & Monorepo Architecture](#page-1), [Sandbox Template, Kernels & Custom Builds](#page-3), [Operations, Lifecycle & Common Failure Modes](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [python/e2b_code_interpreter/models.py](https://github.com/e2b-dev/code-interpreter/blob/main/python/e2b_code_interpreter/models.py)
- [python/e2b_code_interpreter/sandbox.py](https://github.com/e2b-dev/code-interpreter/blob/main/python/e2b_code_interpreter/sandbox.py)
- [js/src/messaging.ts](https://github.com/e2b-dev/code-interpreter/blob/main/js/src/messaging.ts)
- [js/src/sandbox.ts](https://github.com/e2b-dev/code-interpreter/blob/main/js/src/sandbox.ts)
- [js/src/index.ts](https://github.com/e2b-dev/code-interpreter/blob/main/js/src/index.ts)
- [js/package.json](https://github.com/e2b-dev/code-interpreter/blob/main/js/package.json)
- [js/tsup.config.js](https://github.com/e2b-dev/code-interpreter/blob/main/js/tsup.config.js)
- [chart_data_extractor/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/chart_data_extractor/README.md)
- [README.md](https://github.com/e2b-dev/code-interpreter/blob/main/README.md)
</details>

# 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`](https://www.npmjs.com/package/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]()

```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]()

```ts
// 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
```

```py
# 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.

| 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 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]()

```mermaid
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/code-interpreter@2.5.0 release notes](https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter%402.5.0). Community reports confirm that the legacy `beta_pause`/`beta_create` flow could delete the sandbox outright instead of pausing it ([issue #157](https://github.com/e2b-dev/code-interpreter/issues/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/code-interpreter@2.6.0 release notes](https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter%402.6.0), [@e2b/code-interpreter-python@2.8.0 release notes](https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-python%402.8.0).
- **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/code-interpreter@2.4.2 release notes](https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter%402.4.2).
- **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](https://github.com/e2b-dev/code-interpreter/issues/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](https://github.com/e2b-dev/code-interpreter/issues/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](https://github.com/e2b-dev/code-interpreter/issues/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](template-and-build-pipeline.md) — how `code-interpreter-v1` is assembled and how to fork it.
- [Chart Data Extractor](chart-data-extractor.md) — internal package that backs `Result.chart`.
- [Release Notes Index](release-notes.md) — chronological changelog for the JS and Python SDKs.

---

<a id='page-3'></a>

## Sandbox Template, Kernels & Custom Builds

### Related Pages

Related topics: [Overview & Monorepo Architecture](#page-1), [Client SDKs: JavaScript & Python APIs](#page-2), [Operations, Lifecycle & Common Failure Modes](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [template/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/template/README.md)
- [template/template.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/template.py)
- [template/build_prod.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/build_prod.py)
- [template/build_test.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/build_test.py)
- [template/build_debug.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/build_debug.py)
- [template/build_ci.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/build_ci.py)
- [template/debug_logs.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/debug_logs.py)
- [template/ipython_kernel_config.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/ipython_kernel_config.py)
- [python/e2b_code_interpreter/models.py](https://github.com/e2b-dev/code-interpreter/blob/main/python/e2b_code_interpreter/models.py)
- [js/src/index.ts](https://github.com/e2b-dev/code-interpreter/blob/main/js/src/index.ts)
- [README.md](https://github.com/e2b-dev/code-interpreter/blob/main/README.md)
</details>

# 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](https://pypi.org/project/e2b_code_interpreter) and [JavaScript SDKs](https://www.npmjs.com/package/@e2b/code-interpreter). The image is composed in [template/template.py](https://github.com/e2b-dev/code-interpreter/blob/main/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](https://github.com/e2b-dev/code-interpreter/blob/main/template/README.md). Community discussions such as [Issue #175 (Need UV-based code-interpreter custom template)](https://github.com/e2b-dev/code-interpreter/issues/175) and [Issue #150 (Docker images not versioned - everything is `latest`)](https://github.com/e2b-dev/code-interpreter/issues/150) 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](https://github.com/e2b-dev/code-interpreter/blob/main/template/template.py)).

```mermaid
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](https://github.com/e2b-dev/code-interpreter/blob/main/template/README.md).

## Supported Kernels

The matrix below is sourced directly from the conditional branches in [template/template.py](https://github.com/e2b-dev/code-interpreter/blob/main/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/code-interpreter-template@0.4.1` (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/](https://github.com/e2b-dev/code-interpreter/blob/main/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](https://github.com/e2b-dev/code-interpreter/blob/main/template/build_prod.py)) |
| `build_test.py` | `code-interpreter-dev` | `python`, `javascript` | Uses `default_build_logger(min_level="debug")` ([template/build_test.py](https://github.com/e2b-dev/code-interpreter/blob/main/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](https://github.com/e2b-dev/code-interpreter/blob/main/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](https://github.com/e2b-dev/code-interpreter/blob/main/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](https://github.com/e2b-dev/code-interpreter/blob/main/template/README.md)). Once a debug sandbox is running, [template/debug_logs.py](https://github.com/e2b-dev/code-interpreter/blob/main/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](https://github.com/e2b-dev/code-interpreter/blob/main/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](https://github.com/e2b-dev/code-interpreter/issues/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)](https://github.com/e2b-dev/code-interpreter/issues/147) 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/code-interpreter@2.5.0](https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter%402.5.0)).
- **`beta_pause` / `beta_create` deletion behaviour.** [Issue #157](https://github.com/e2b-dev/code-interpreter/issues/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](https://github.com/e2b-dev/code-interpreter/issues/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](https://e2b.dev/docs/template/quickstart) — official guide for `Template.from_template` extension.
- [template/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/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).

---

<a id='page-4'></a>

## Operations, Lifecycle & Common Failure Modes

### Related Pages

Related topics: [Overview & Monorepo Architecture](#page-1), [Client SDKs: JavaScript & Python APIs](#page-2), [Sandbox Template, Kernels & Custom Builds](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/e2b-dev/code-interpreter/blob/main/README.md)
- [template/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/template/README.md)
- [template/build_ci.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/build_ci.py)
- [template/debug_logs.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/debug_logs.py)
- [template/ipython_kernel_config.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/ipython_kernel_config.py)
- [python/e2b_code_interpreter/models.py](https://github.com/e2b-dev/code-interpreter/blob/main/python/e2b_code_interpreter/models.py)
- [js/src/messaging.ts](https://github.com/e2b-dev/code-interpreter/blob/main/js/src/messaging.ts)
- [js/package.json](https://github.com/e2b-dev/code-interpreter/blob/main/js/package.json)
- [chart_data_extractor/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/chart_data_extractor/README.md)
- [js/tsup.config.js](https://github.com/e2b-dev/code-interpreter/blob/main/js/tsup.config.js)

</details>

# 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`:

```ts
// 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.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 build** — `template/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 templates** — `Template().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 configuration** — `template/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/code-interpreter@2.4.2` 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]().

| 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

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](https://github.com/e2b-dev/code-interpreter/blob/main/template/README.md)
- Result / Execution data model — [python/e2b_code_interpreter/models.py](https://github.com/e2b-dev/code-interpreter/blob/main/python/e2b_code_interpreter/models.py), [js/src/messaging.ts](https://github.com/e2b-dev/code-interpreter/blob/main/js/src/messaging.ts)
- Chart data extraction utility — [chart_data_extractor/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/chart_data_extractor/README.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: e2b-dev/code-interpreter

Summary: 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
- Evidence strength: source_linked
- 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.
- 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
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/e2b-dev/code-interpreter/issues/200

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: @e2b/code-interpreter-python@2.6.2
- User impact: Upgrade or migration may change expected behavior: @e2b/code-interpreter-python@2.6.2
- 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
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: @e2b/code-interpreter@2.4.2
- User impact: Upgrade or migration may change expected behavior: @e2b/code-interpreter@2.4.2
- 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
- Evidence strength: source_linked
- 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
- Evidence: failure_mode_cluster:github_issue | https://github.com/e2b-dev/code-interpreter/issues/200

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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
- Evidence: failure_mode_cluster:github_issue | https://github.com/e2b-dev/code-interpreter/issues/175

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/e2b-dev/code-interpreter/issues/175

## 8. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: @e2b/code-interpreter-python@2.7.0
- User impact: Upgrade or migration may change expected behavior: @e2b/code-interpreter-python@2.7.0
- 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
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: @e2b/code-interpreter@2.5.0
- User impact: Upgrade or migration may change expected behavior: @e2b/code-interpreter@2.5.0
- 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
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | github_repo:770633006 | https://github.com/e2b-dev/code-interpreter

## 11. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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
- Evidence: failure_mode_cluster:github_issue | https://github.com/e2b-dev/code-interpreter/issues/157

## 12. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/e2b-dev/code-interpreter/issues/157

## 13. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/e2b-dev/code-interpreter/issues/147

## 14. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | github_repo:770633006 | https://github.com/e2b-dev/code-interpreter

## 15. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | github_repo:770633006 | https://github.com/e2b-dev/code-interpreter

## 16. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | github_repo:770633006 | https://github.com/e2b-dev/code-interpreter

## 17. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: Docker images are not versioned - everything is `latest`
- User impact: Developers may hit a documented source-backed failure mode: Docker images are not versioned - everything is `latest`
- Evidence: failure_mode_cluster:github_issue | https://github.com/e2b-dev/code-interpreter/issues/150

## 18. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: The sandbox was not found
- User impact: Developers may hit a documented source-backed failure mode: The sandbox was not found
- Evidence: failure_mode_cluster:github_issue | https://github.com/e2b-dev/code-interpreter/issues/147

## 19. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | github_repo:770633006 | https://github.com/e2b-dev/code-interpreter

## 20. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | github_repo:770633006 | https://github.com/e2b-dev/code-interpreter

## 21. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: @e2b/code-interpreter-python@2.8.0
- User impact: Upgrade or migration may change expected behavior: @e2b/code-interpreter-python@2.8.0
- Evidence: failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-python%402.8.0

## 22. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: @e2b/code-interpreter-template@0.4.0
- User impact: Upgrade or migration may change expected behavior: @e2b/code-interpreter-template@0.4.0
- Evidence: failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-template%400.4.0

## 23. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: @e2b/code-interpreter-template@0.4.1
- User impact: Upgrade or migration may change expected behavior: @e2b/code-interpreter-template@0.4.1
- Evidence: failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-template%400.4.1

## 24. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: @e2b/code-interpreter-template@0.4.2
- User impact: Upgrade or migration may change expected behavior: @e2b/code-interpreter-template@0.4.2
- Evidence: failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-template%400.4.2

## 25. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: @e2b/code-interpreter-template@0.4.3
- User impact: Upgrade or migration may change expected behavior: @e2b/code-interpreter-template@0.4.3
- Evidence: failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-template%400.4.3

## 26. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: @e2b/code-interpreter@2.6.0
- User impact: Upgrade or migration may change expected behavior: @e2b/code-interpreter@2.6.0
- Evidence: failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter%402.6.0

<!-- canonical_name: e2b-dev/code-interpreter; human_manual_source: deepwiki_human_wiki -->