Save a sandbox as a template
Sandboxes are in private preview, by invitation. Saving a sandbox as a template is enabled on request, per account, for accounts that have Sandboxes (see Access). On an account without it, a save gets 403 edge_template_builds_disabled. Limits and prices may change during the preview; changes will be announced in the release notes.
Set a sandbox up once (install packages, clone a repository, warm a cache, start a service) and save it as a template. Every sandbox you then create from that template starts exactly where the saved one was, in a fraction of the time the setup took. The template is private to your account.
This is the E2B SDKs' own feature, the snapshot: the calls below are the official E2B SDK's, version 2.63.0, with no change for Serenity Edge. Building a template from a Dockerfile (e2b template build) is not available.
Save, create, list and delete
Deleting a template by the snapshot id that the SDKs return, <your account>/data-env:default, fails for now: the / of the id, which the SDKs send encoded as %2F, arrives decoded, so the delete is answered 404 edge_route_not_available and the SDKs return False (the template is not deleted). Until the fix, delete by the bare name, without your account's namespace: Sandbox.delete_snapshot("data-env") or Sandbox.delete_snapshot("data-env:default"), as the examples below do. The fix will be announced in the release notes.
Python
from e2b import Sandbox
# Set a sandbox up once.
sandbox = Sandbox.create(timeout=600)
sandbox.commands.run("pip install --user pandas", timeout=300)
sandbox.files.write("/home/user/config.json", '{"ready": true}')
# Save it as a template. The sandbox pauses briefly and goes on running.
snapshot = sandbox.create_snapshot(name="data-env")
print(snapshot.snapshot_id) # "<your account>/data-env:default"
# Create as many sandboxes as you need from it.
worker = Sandbox.create(snapshot.snapshot_id, timeout=300)
print(worker.files.read("/home/user/config.json"))
# List your templates, then delete one.
for info in Sandbox.list_snapshots().next_items():
print(info.snapshot_id)
worker.kill()
sandbox.kill()
# Delete by the bare name, without your account's namespace (see the known issue above).
Sandbox.delete_snapshot("data-env") # True, or False if it was not found
JavaScript
import { Sandbox } from "e2b";
const sandbox = await Sandbox.create({ timeoutMs: 600_000 });
await sandbox.commands.run("pip install --user pandas", { timeoutMs: 300_000 });
await sandbox.files.write("/home/user/config.json", '{"ready": true}');
const snapshot = await sandbox.createSnapshot({ name: "data-env" });
const worker = await Sandbox.create(snapshot.snapshotId, { timeoutMs: 300_000 });
console.log(await worker.files.read("/home/user/config.json"));
const paginator = Sandbox.listSnapshots();
while (paginator.hasNext) {
for (const info of await paginator.nextItems()) console.log(info.snapshotId);
}
await worker.kill();
await sandbox.kill();
// Delete by the bare name, without your account's namespace (see the known issue above).
await Sandbox.deleteSnapshot("data-env");
Over HTTP
| Call | Route |
|---|---|
| Save a sandbox as a template | POST /sandboxes/{sandboxID}/snapshots, body {"name": "data-env"} or {} |
| Create a sandbox from a template | POST /sandboxes with the snapshot id as templateID |
| List your templates | GET /snapshots |
| Delete a template | DELETE /templates/{name}, with the bare name, without your account's namespace, percent-encoded as one path segment: DELETE /templates/data-env%3Adefault (: as %3A). Until the fix of the known issue above, the full snapshot id with its namespace (/ as %2F, as the SDKs send it) gets 404 edge_route_not_available |
Names and versions
- A name is optional. Without one, the snapshot id is the template's own id with the tag
default, such asabc123xyz:default. - A name is lowercase letters, digits,
-and_, at most 64 characters, optionally followed by:and a tag. Send it without a namespace: your account's namespace is added for you, so the snapshot id comes back as<your account>/<name>:<tag>. - Saving again under a name you already have adds a new version to that template. With a new tag (
data-env:v2) both versions stay usable; under the same tag the new version replaces the old one for new sandboxes, and the old one is deleted in the periodic clean-up once nothing needs it any more (a new version can build on the stored data of the one before). A new version is not a new template for the limits below, but what it stores counts. - The names of Serenity Edge's own templates, such as
baseandedge-agents, cannot be used (400 edge_template_name_reserved). - Deleting deletes the whole template, every tag:
delete_snapshot("data-env:v2")also deletesdata-env:default. Save under different names what you want to delete separately. - Templates belong to the account, not to a key: every API key of your account can use, list and delete them.
What a template holds
A template is the sandbox as it was when you saved it, memory and disk:
- the files on its disk, the packages you installed and the changes you made to the system;
- its memory: the processes that were running go on running in every sandbox created from it, with their state, their environment variables and anything they held in memory.
So a template holds whatever you put in the sandbox, secrets included. Do not save a sandbox that holds credentials, tokens or personal data you would not want stored. Pass credentials to each sandbox after you create it, for example as environment variables on create, rather than before you save it.
Generate secrets after create, not before you save. Every sandbox created from a template starts with the same memory. The system's random number generator is reseeded in each new sandbox, but a key, a token or a random seed that a program generated before you saved the template is the same in every sandbox created from it.
What a template does not hold:
- Network connections. Each new sandbox has its own network and its own access tokens. A connection the saved sandbox had open is closed in the new one: programs that keep connections must be able to reconnect.
- The clock is set when the sandbox is created, not when the template was saved.
Templates that hold only the disk, and restart their processes (mode="filesystem" in Python, mode: "filesystem" in JavaScript), are not available: such a request gets HTTP 400 with error_code: "snapshot_filesystem_only_disabled". Every template holds memory and disk.
While you save
- The sandbox pauses briefly while it is saved, then goes on running with its processes and connections. The more memory and disk it changed since it was created, the longer the pause and the save.
- The call returns when the template is stored. For a sandbox that changed several GiB, saving can take minutes. The SDKs give up after 60 seconds by default, and the control API answers within 90 seconds, so for large templates give the call a timeout of 95 seconds (
create_snapshot(name="data-env", request_timeout=95)in Python,createSnapshot({ name: "data-env", requestTimeoutMs: 95_000 })in JavaScript); a longer one does not help. - A save that takes longer is not lost. When your call times out, or is answered with an error such as
503 edge_upstream_timeoutor a closed connection, the save goes on and the template appears in your list when it is stored. List your templates (list_snapshots) before you retry, or save under a name: saving again under the same name adds a version to that template instead of making a second one. - A failure of the platform while a sandbox is being saved can end that sandbox. The call then answers HTTP 500, and the sandbox is lost with its memory and disk, as after any platform failure (see No service level). Keep anything you need outside the sandbox before you save it.
Limits
| Default per account, in each site | |
|---|---|
| Templates | 10 |
| Total stored by your templates | 20 GiB |
The limits can be raised on request. A save beyond them is refused and nothing is saved; your existing templates are never deleted for a limit.
- A sandbox created from a template has the size of the sandbox it was saved from, and counts toward your account's limits on running sandboxes like any other (see Per-account limits). Do not send
cpuCountormemoryMBwith it (400 edge_shape_limit). - A template can only be deleted while no sandbox created from it is running or paused: kill those first. Otherwise the delete answers HTTP 400.
Prices
| What is billed | Price |
|---|---|
| Each GiB a template stores | 0.08 USD per GiB-month, the price of a paused sandbox |
- What a template stores is measured, not estimated: the memory and the changes to the disk of the saved sandbox, as stored. The content of Serenity Edge's template underneath and the free disk are not counted. Every version that is still stored counts.
- Each stored byte is billed once. When a template and a paused sandbox, or two of your templates, share stored data, that data is billed once.
- From the save to the delete, in hourly intervals, like a paused sandbox (see How usage is recorded). Billing stops when you delete the template, not when its data is cleaned up afterwards.
- A sandbox created from a template is billed as any sandbox, for the vCPUs and memory of its size, per second, while it runs.
- Where you see it. Template storage is billed to your account, not to the key that saved it: it is in your account's usage records and on its invoice, and not in a key's
GET /v1/usage, which lists the usage of the sandboxes that key created.
Data lifetime
| Data | What happens to it |
|---|---|
| A template you delete | No longer usable or listed from the delete, and no longer billed. Its stored data is deleted in a periodic clean-up, after the last sandbox created from it ends if one is still running or paused. |
| A template from which no sandbox was created for 90 days | May be deleted, as if you had deleted it. The 90 days count from the last sandbox created from it, or from the save if none was. Create a sandbox from a template you want to keep at least once every 90 days. |
| Templates of an account whose access was revoked | Deleted with its paused sandboxes, 7 days after the revocation (see Data lifetime). |
A deleted template cannot be recovered. Serenity Edge does not read your templates: what is logged about them is what is logged about any request to the control API, with the route as a pattern and never the template's name (see What is logged).
Isolation
A template is private to your account. No other account can create a sandbox from it, see it in a list, read it or delete it, whatever id or name it sends: such a create gets 403 edge_template_not_allowed and such a delete is answered as for a template that does not exist. There are no public templates of customers.
Errors
| Status | error_code | When | What to do |
|---|---|---|---|
| 400 | edge_template_name_reserved | The name is one of Serenity Edge's own templates. | Choose another name. |
| 400 | edge_invalid_request | The name has a namespace, capital letters or other characters, or memory is not a boolean. | Send a bare name, lowercase. |
| 400 | edge_field_not_supported | The save carries a field other than name and memory. | Remove the field. |
| 403 | edge_template_limit | Your account already keeps its maximum of templates in this site. | Delete a template you no longer need, or ask for a higher limit. Saving under a name you already have still works. |
| 403 | edge_template_size_limit | Your templates already store your account's maximum in this site. | Delete templates or versions you no longer need, or ask for a higher limit. |
| 403 | edge_template_not_allowed | The templateID of a create is neither Serenity Edge's template nor one of your account's templates, or Serenity Edge's template was named in a delete. | Check the snapshot id with list_snapshots. |
| 403 | edge_template_builds_disabled | Templates are not enabled for your account. | Ask for them (see Access). |
| 404 | edge_template_not_found | A delete of a template your account does not have. The SDKs return False. | Check the snapshot id with list_snapshots. |
| 404 | edge_route_not_available | A delete by the full snapshot id, with your account's namespace (the known issue above). The SDKs return False. | Delete by the bare name, such as data-env or data-env:default. |
| 429 | edge_snapshot_in_progress | A save of your account is in progress and others already wait for it. | Retry after the Retry-After seconds, or when your saves in progress end. |
| 429 | edge_template_sizing_pending | Your account saved several templates since their storage was last measured (every few minutes). | Retry after the Retry-After seconds. |
| 503 | edge_template_size_unavailable | The storage of your templates cannot be measured right now, so no template can be saved. Your templates and the sandboxes created from them are not affected. | Retry after the Retry-After seconds. |
Errors without an edge_ code come from the sandbox runtime, as on every route (see Errors from the sandbox runtime).