Templates

A template is the image a sandbox boots from. E2B builds it remotely into a microVM snapshot, so deploys need no Docker, and a sandbox from it starts in well under a second.

From a registry image

src/Sandbox.ts

import * as E2B from "@alchemy.run/e2b";

export const Python = E2B.Template("Python", { image: "python:3.12-slim" });

From a Dockerfile

src/Sandbox.ts

import * as Dockerfile from "@alchemy.run/docker/Dockerfile";
import * as E2B from "@alchemy.run/e2b";

export const Agent = E2B.Template("Agent", {
  dockerfile: Dockerfile.inline`
    FROM node:22-bookworm
    RUN apt-get update && apt-get install -y git ripgrep
    WORKDIR /work
  `,
});

Point dockerfile at a file instead to use its directory as the build context. COPY sources are uploaded once per content, so a deploy uploads only files that changed.

E2B’s builder runs one stage. A Dockerfile with several FROMs, COPY --from, ADD <url>, heredocs, RUN --mount, or SHELL fails at plan time with UnsupportedDockerfile, listing the lines, before anything is created. EXPOSE, LABEL, VOLUME, HEALTHCHECK, and STOPSIGNAL are ignored, and an ARG becomes an environment variable.

From another template

export const Tools = E2B.Template("Tools", {
  fromTemplate: "base",
  run: ["pip install pandas numpy"],
});

Building on a template reuses its cached layers.

Size

export const Big = E2B.Template("Big", { image: "node:22-bookworm", cpuCount: 8, memoryMB: 16384 });

Every sandbox from the template gets these resources.

A process that is already running

export const Preview = E2B.Template("Preview", {
  image: "node:22-bookworm",
  run: ["npm create vite@latest app -- --template react", "cd app && npm install"],
  startCmd: "cd /home/user/app && npm run dev -- --host 0.0.0.0 --port 3000",
  readyCmd: "curl -sf http://localhost:3000",
});

E2B snapshots the template once readyCmd succeeds, so every sandbox starts with the dev server up. A Dockerfile’s CMD does the same. To run your own Effect program this way, see Template programs.

Private base images

export const Private = E2B.Template("Private", {
  image: "ghcr.io/my-org/base:1",
  registry: { username: "my-org", password: Alchemy.Secret("GHCR_TOKEN") },
});

E2B uses the credentials to pull the base image only. ECR (awsAccessKeyId, awsSecretAccessKey, awsRegion) and Artifact Registry (serviceAccountJson) work the same way.

Build templates at runtime

const templates = yield* E2B.CreateTemplate();
// in fetch:
const template = yield* templates.getOrBuild({
  name: `repo-${slug}`,
  image: "node:22-bookworm",
  files: [{ path: "/home/user/app/package.json", contents: packageJson }],
  run: ["cd /home/user/app && npm install"],
});

A runtime build takes E2B’s own build inputs: a base image or fromTemplate, then env, files from memory, and run steps. getOrBuild builds only when no ready build of the same inputs exists. Delete runtime templates when you no longer need them: destroying the Worker does not.

Deploys and replacement

A deploy starts a new build only when the inputs change; sandboxes already running keep the old build. Changing name replaces the template.