From 97cd4c79ba05653473db7a1809d4e6ce10bd6090 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 13 Jun 2026 00:09:31 +0000 Subject: [PATCH] docs: explain templates vs snapshots performance and scaling to many templates --- docs/sandbox/snapshots.mdx | 9 +++++++++ docs/template/quickstart.mdx | 38 ++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+) diff --git a/docs/sandbox/snapshots.mdx b/docs/sandbox/snapshots.mdx index 8e28303d..3e67e420 100644 --- a/docs/sandbox/snapshots.mdx +++ b/docs/sandbox/snapshots.mdx @@ -185,6 +185,15 @@ Both snapshots and [templates](/docs/template/quickstart) create reusable starti Use templates when every sandbox should start from an identical, known state — pre-installed tools, fixed configurations, consistent environments. Use snapshots when you need to capture or fork live runtime state that depends on what happened during execution. +### Performance: prefer templates when possible + +For workloads where either approach would work, **templates are faster and more resource-efficient** than snapshots: + +- **Compact memory.** During a template build, the guest OS is restarted before the long-running process is captured. Memory is compact and any setup-time processes that aren't needed at runtime are gone, so sandboxes start with less memory pressure and fewer resources. +- **More effective prefetching.** E2B optimistically prefetches data needed to start a sandbox. For templates this prefetching is highly effective; for snapshots its effectiveness is significantly lower due to memory fragmentation and general memory pressure from the captured live state. + +If you can express the state you need as a declarative template build, you'll generally get faster cold starts and lower overhead than capturing the equivalent state as a snapshot. There is no limit that should discourage you from creating many templates — see [Creating many templates](/docs/template/quickstart#creating-many-templates) for using templates per-customer or per-project. + ## Use cases - **Checkpointing agent work** — an AI agent has loaded data and produced partial results in memory. Snapshot it so you can resume or fork from that point later. diff --git a/docs/template/quickstart.mdx b/docs/template/quickstart.mdx index 7dcba7df..e67855b5 100644 --- a/docs/template/quickstart.mdx +++ b/docs/template/quickstart.mdx @@ -239,6 +239,44 @@ sbx = Sandbox(template="template-tag") The template name is the identifier that can be used to create a new Sandbox. +## Creating many templates + +There is no practical limit on how many templates you can have. It's perfectly fine to create **tens or hundreds of thousands of templates** — for example, one template per customer, per project, or per agent run. + +The template build environment is a full sandbox environment, so you can do anything during the build that you can do inside a running sandbox, including running Docker containers as part of the setup. + +Compared to [snapshots](/docs/sandbox/snapshots), templates start faster and use fewer resources because the guest OS is restarted before the long-running process is captured and prefetching is significantly more effective. If your workload involves spinning up many per-customer or per-project environments, prefer templates over snapshots. + +### Layering templates with `fromTemplate` + +When you build many similar templates (e.g. a customer-specific template per customer that all share the same base setup), use [`fromTemplate`](/docs/sdk-reference/js-sdk/v2.29.1/template#fromtemplate) to start from an existing template instead of rebuilding the shared layers from scratch each time. This keeps per-customer builds fast and reuses the cached base. + + + +```typescript JavaScript & TypeScript +import { Template } from 'e2b' + +// Per-customer template built on top of a shared base template +export const template = Template() + .fromTemplate('my-base-template') + .copyDirectory('./customers/acme', '/app/config') + .setEnvs({ CUSTOMER_ID: 'acme' }) +``` + +```python Python +from e2b import Template + +# Per-customer template built on top of a shared base template +template = ( + Template() + .from_template("my-base-template") + .copy_directory("./customers/acme", "/app/config") + .set_envs({"CUSTOMER_ID": "acme"}) +) +``` + + + ## Build limits Template builds are subject to the following limits: