docs: clarify templates vs snapshots performance and many-template usage#250
Open
mintlify[bot] wants to merge 5 commits into
Open
docs: clarify templates vs snapshots performance and many-template usage#250mintlify[bot] wants to merge 5 commits into
mintlify[bot] wants to merge 5 commits into
Conversation
Contributor
Author
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
beran-t
reviewed
Jun 15, 2026
|
|
||
| ## 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. |
Contributor
There was a problem hiding this comment.
I don't like telling customers that there is no limit, while we plan to release pricing for this in the future, afaik.
Usually, when customers ask about it, I mention that pricing for total space used will be introduced, but there are no limits planned.
mishushakov
reviewed
Jun 15, 2026
| 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 |
| - **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. |
Member
There was a problem hiding this comment.
i'd soften this "There is no limit that should discourage you from creating many templates — see [Creating many templates]"
there will be possibly limits in the future?
|
|
||
| ## 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. |
Member
There was a problem hiding this comment.
this may change so I would not promise it 100%
| The template name is the identifier that can be used to create a new Sandbox. | ||
| </Note> | ||
|
|
||
| ## Creating many templates |
Member
There was a problem hiding this comment.
maybe rename to "Scaling templates" or something that makes it clear that you can have n of them with lower overhead
|
|
||
| ### 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. |
Member
There was a problem hiding this comment.
you can use https://e2b.dev/docs/sdk-reference/js-sdk/latest/template#fromtemplate
it will point to the latest SDK version
- Replace em-dashes with periods/commas per project style - Point fromTemplate link at js-sdk/latest alias instead of pinned v2.29.1
- 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
mishushakov
reviewed
Jul 15, 2026
|
|
||
| ## Scaling templates | ||
|
|
||
| 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. |
Member
There was a problem hiding this comment.
hundreds of thousands of templates is actually uncommon
mishushakov
reviewed
Jul 15, 2026
|
|
||
| ## Scaling templates | ||
|
|
||
| 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. |
mishushakov
reviewed
Jul 15, 2026
| // Per-customer template built on top of a shared base template | ||
| export const template = Template() | ||
| .fromTemplate('my-base-template') | ||
| .copyDirectory('./customers/acme', '/app/config') |
Member
There was a problem hiding this comment.
there's no method called .copyDirectory
mishushakov
reviewed
Jul 15, 2026
| template = ( | ||
| Template() | ||
| .from_template("my-base-template") | ||
| .copy_directory("./customers/acme", "/app/config") |
- Replace nonexistent copyDirectory/copy_directory with copy() (per SDK reference) - Drop 'hundreds of thousands' claim; state currently no limit, storage pricing may come
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds guidance under sandbox snapshots explaining why templates are typically faster and more resource-efficient (compact memory after guest OS restart, more effective prefetching), and adds a "Creating many templates" section in the template quickstart covering per-customer/per-project usage at scale and layering templates with
fromTemplate.docs/sandbox/snapshots.mdx: new "Performance: prefer templates when possible" subsection under Snapshots vs. Templates.docs/template/quickstart.mdx: new "Creating many templates" section with afromTemplateexample.