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 1/3] 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: From 0dc60d8230cafacbdf5bcb93f5674e090a7d6495 Mon Sep 17 00:00:00 2001 From: Tomas Beran Date: Mon, 13 Jul 2026 19:18:00 -0700 Subject: [PATCH 2/3] docs: remove em-dashes and use latest SDK reference alias - Replace em-dashes with periods/commas per project style - Point fromTemplate link at js-sdk/latest alias instead of pinned v2.29.1 --- docs/sandbox/snapshots.mdx | 2 +- docs/template/quickstart.mdx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sandbox/snapshots.mdx b/docs/sandbox/snapshots.mdx index 3e67e420..a53188a7 100644 --- a/docs/sandbox/snapshots.mdx +++ b/docs/sandbox/snapshots.mdx @@ -192,7 +192,7 @@ For workloads where either approach would work, **templates are faster and more - **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. +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 diff --git a/docs/template/quickstart.mdx b/docs/template/quickstart.mdx index 096d024f..fb5f0110 100644 --- a/docs/template/quickstart.mdx +++ b/docs/template/quickstart.mdx @@ -241,7 +241,7 @@ 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. +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. @@ -249,7 +249,7 @@ Compared to [snapshots](/docs/sandbox/snapshots), templates start faster and use ### 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. +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/latest/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. From 5ff3c3c0cb7f6fe8d5086211fff87e7dca34f99d Mon Sep 17 00:00:00 2001 From: Tomas Beran Date: Mon, 13 Jul 2026 22:16:59 -0700 Subject: [PATCH 3/3] docs: address review comments on template scaling section - Rename 'Creating many templates' to 'Scaling templates' - Shorten performance heading to 'Performance' - Soften no-limit claims; note storage pricing is planned - Update cross-link anchor to #scaling-templates --- docs/sandbox/snapshots.mdx | 4 ++-- docs/template/quickstart.mdx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sandbox/snapshots.mdx b/docs/sandbox/snapshots.mdx index a53188a7..8daac3f9 100644 --- a/docs/sandbox/snapshots.mdx +++ b/docs/sandbox/snapshots.mdx @@ -185,14 +185,14 @@ 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 +### Performance 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. +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. Creating many templates is a supported pattern, so this doesn't need to discourage you from using templates per-customer or per-project. See [Scaling templates](/docs/template/quickstart#scaling-templates). ## Use cases diff --git a/docs/template/quickstart.mdx b/docs/template/quickstart.mdx index fb5f0110..1769db60 100644 --- a/docs/template/quickstart.mdx +++ b/docs/template/quickstart.mdx @@ -239,9 +239,9 @@ sbx = Sandbox(template="template-tag") The template name is the identifier that can be used to create a new Sandbox. -## Creating many templates +## Scaling 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. +You can create a large number of templates with low overhead. It's common to have **tens or hundreds of thousands of templates**, for example one template per customer, per project, or per agent run. There's no limit on the number of templates that should discourage this pattern. Pricing for total storage used by templates will be introduced in the future. 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.