Home / Docs / Templates · also: Quickstart

Templates

A template is the image a sandbox starts from. Sandbox.create() with no template argument uses the default, agent-full. The authoritative list is GET /templates on the API (your own templates, then the platform templates); the table below lists the platform aliases that endpoint returns. GPU sandboxes are separate — see GPU templates.

CPU templates

Choose a CPU template

Pass the alias at create time. Omit it and you get agent-full.

# Python — e2b==2.40.0
from e2b import Sandbox

sbx = Sandbox.create(template="agent-full")   # or any CPU alias from the table

sbx.kill()

// JavaScript / TypeScript — e2b@2.26.0
import { Sandbox } from "e2b";

const sbx = await Sandbox.create("agent-full");   // or any CPU alias from the table

await sbx.kill();

GPU templates

GPU sandboxes are created with an accel object rather than a top-level template argument:

# POST /sandboxes — REST, not the E2B SDK
{"accel": {"class": "<gpu-class>", "vram_gb": 4, "template": "<gpu-template>"}}

Omit accel.template to get the default GPU stack. Named GPU templates are operator-defined per deployment, so only pass a name you were given; there is no way to name an image from a request. accel.vram_gb is the VRAM slice in GiB and accel.class optionally pins a GPU class. Do not pass a top-level templateID on an accel create — it is ignored there (it is a CPU-plane knob). GPU lease ids (gl-…) are driven over the REST verbs, not the E2B SDK. The GPU sandboxes guide walks through the whole lifecycle: create, exec, pause and resume, files, billing and errors.

GPU lease files

GPU leases have no network unless you create them with accel.network: "internet", which works only on nodes where the operator enabled egress (see the guide). Upload input bytes with PUT /sandboxes/{sandbox_id}/files/{name}, authenticated with your API key. The path is relative to the job’s OUTPUT_DIR, and missing parent directories are created there. The reply is {"name","size","sha256"}. Both local and node modes stream in chunks and publish atomically: a failed upload keeps the old file.

curl -H "X-API-Key: $SBX_API_KEY" --upload-file input.bin \
  "$API/sandboxes/$GPU_ID/files/inputs/input.bin"
# In POST /sandboxes/{id}/exec code:
data = open(f"{OUTPUT_DIR}/inputs/input.bin", "rb").read()

Names follow the download rules: relative paths only, at most five components and 1024 characters, each component at most 255 characters; no empty, ., .., NUL or backslash components. Symlinked roots, parents and existing destinations are refused (404). Both front and node enforce GATEWAY_GPU_MAX_UPLOAD_BYTES (default 512 MiB); an over-cap upload returns 413. There is no dedicated per-lease disk quota; disk-write failure returns 507. Paused, frozen or transitioning leases return 409, so resume explicitly before uploading. Dead, unknown and another key's leases return 404.

Downloads and listings, GET /sandboxes/{id}/files[/{name}], read the same OUTPUT_DIR uploads land in (PUT files/result.bin then GET files/result.bin round-trips) and remain available while paused. The download cap is separate (default 256 MiB).

At the start of every exec, report is reset to {}; other Python variables persist across execs and pause/resume. report is your data channel: report["exit_code"] = 1 does not change ok:true when the Python job returns normally. Raise an exception to fail the job; a timeout also fails the job.

Add packages at runtime

The default template ships the languages and agent CLIs but not data-science libraries. This applies to agent-full and desktop; manim, math-agent and wine are offline by design, so runtime installs fail there. Install what you need inside the sandbox with pip install --user — the packages land in the sandbox's own home and survive for that sandbox's lifetime without changing the image:

# Python — e2b==2.40.0
sbx = Sandbox.create()   # agent-full
out = sbx.commands.run("pip install --user pandas matplotlib", timeout=600)
print(out.stdout)
sbx.kill()

// JavaScript / TypeScript — e2b@2.26.0
const sbx = await Sandbox.create();   // agent-full
const out = await sbx.commands.run("pip install --user pandas matplotlib", { timeoutMs: 600_000 });
console.log(out.stdout);
await sbx.kill();

Verified 2026-10-10 in a live default-template sandbox: pandas 3.0.6 and matplotlib 3.11.2 installed and imported (the default template ships neither). Install time counts as running time — see limits.

Next: quickstart · GPU sandboxes · coding agents · limits and network policy