Agent Sandbox:Snapshot (Preview)

Overview

The Snapshot feature currently supports only the second-generation runtime.

A Snapshot saves the file system and memory state of a running sandbox at a specific point in time. After creation, a Snapshot is independent of its source sandbox and source template. Deleting the source sandbox or source template does not delete the Snapshot, and deleting the Snapshot does not delete the source sandbox or source template.

Typical usage: install dependencies and prepare the workspace in a sandbox, create a Snapshot, and then start new sandboxes in the same state from that Snapshot within seconds without rebuilding the template. This applies to scenarios such as resuming agent tasks from a checkpoint, warming up environments, and parallel clone exploration.

A Snapshot is retained for 7 days from creation by default and expires automatically after that. Expired Snapshots no longer appear in the list and cannot be used to create sandboxes. Snapshot retention is independent of the source sandbox lifecycle: after the source sandbox is terminated or reclaimed due to a timeout, unexpired Snapshots remain available.

Snapshot operations are called through the E2B-compatible SDK. For compatibility details, see E2B compatibility. For authentication and connection parameter configuration, see Usage constraints.

API reference

The instance method and the static method for creating a Snapshot have the same semantics. The instance method implicitly targets the current sandbox, so sandboxId / sandbox_id does not need to be passed. Listing and deletion are available only as static methods.

Limits

• Snapshots can be created only from a running sandbox. Creation fails if the source sandbox is paused, is creating a Snapshot, or is occupied by another operation.

• Only the second-generation runtime is supported.

• Named Snapshots require the current Team to have a name. If the Team has no name, only unnamed Snapshots can be created.

• During creation, the state of the source sandbox is snapshotting, and the sandbox cannot be deleted at this point. After creation completes, the sandbox can continue to be used, or another Snapshot can be created from it.

• Creation can take several minutes. Set the SDK request timeout to at least 300 seconds (TypeScript: requestTimeoutMs: 300_000; Python: request_timeout=300). timeoutMs / timeout controls the sandbox lifetime, not the Snapshot request timeout. The default request timeout is typically 60 seconds; if you do not increase it, the request may fail before creation completes.

• The source template must still exist when the Snapshot is created. After creation succeeds, the Snapshot can still be used to restore a sandbox even if the source template is deleted later.

Create a Snapshot

name is optional. If omitted, an unnamed Snapshot is created and can be accessed only by its Snapshot ID from then on.

Within the same Team, only one available Snapshot can exist at a time for the same (short name, tag) combination, regardless of the source template. On a name conflict, creation fails without overwriting the existing Snapshot. Different tags can coexist. After deletion, the name is released immediately.

import { Sandbox } from "e2b";

const sandbox = await Sandbox.create("code-interpreter-v1", {
  apiKey: process.env.E2B_API_KEY,
  apiUrl: process.env.E2B_API_URL,
  domain: process.env.E2B_DOMAIN,
  timeoutMs: 300_000,
});

await sandbox.files.write("/app/state.json", '{"step": 1}');

const snapshot = await sandbox.createSnapshot({
  name: "deps-ready",
  requestTimeoutMs: 300_000,
});
// snapshot.snapshotId
// snapshot.names === ["demo-team/deps-ready:default"]

const another = await Sandbox.createSnapshot(sandbox.sandboxId, {
  apiKey: process.env.E2B_API_KEY,
  domain: process.env.E2B_DOMAIN,
  requestTimeoutMs: 300_000,
  name: "deps-ready:v1",
});

import os

from e2b import Sandbox

sandbox = Sandbox.create(
    template="code-interpreter-v1",
    api_key=os.environ["E2B_API_KEY"],
    api_url=os.environ["E2B_API_URL"],
    domain=os.environ["E2B_DOMAIN"],
    timeout=300,
)

sandbox.files.write("/app/state.json", '{"step": 1}')

snapshot = sandbox.create_snapshot(
    name="deps-ready",
    request_timeout=300,
)
# snapshot.snapshot_id
# snapshot.names == ["demo-team/deps-ready:default"]

another = Sandbox.create_snapshot(
    sandbox.sandbox_id,
    name="deps-ready:v1",
    api_key=os.environ["E2B_API_KEY"],
    api_url=os.environ["E2B_API_URL"],
    domain=os.environ["E2B_DOMAIN"],
    request_timeout=300,
)

Multiple Snapshots can be created from the same sandbox.

List Snapshots

Returns the Snapshots of the current Team that are neither deleted nor expired, in descending order of creation time.

If the list operation is called immediately after a successful creation, the newly written record may not appear temporarily due to indexing delay. Restoring a sandbox by Snapshot ID or qualified name, and deleting a Snapshot, are not affected. The snapshotId / names returned by the create operation can be used directly.

const paginator = Sandbox.listSnapshots({
  apiKey: process.env.E2B_API_KEY,
  domain: process.env.E2B_DOMAIN,
});
const snapshots = [];
while (paginator.hasNext) {
  snapshots.push(...(await paginator.nextItems()));
}

Sandbox.listSnapshots({
  apiKey: process.env.E2B_API_KEY,
  domain: process.env.E2B_DOMAIN,
  sandboxId: sandbox.sandboxId,
});
Sandbox.listSnapshots({
  apiKey: process.env.E2B_API_KEY,
  domain: process.env.E2B_DOMAIN,
  name: "deps-ready",
});

paginator = Sandbox.list_snapshots(
    api_key=os.environ["E2B_API_KEY"],
    api_url=os.environ["E2B_API_URL"],
    domain=os.environ["E2B_DOMAIN"],
)
snapshots = []
while paginator.has_next:
    snapshots.extend(paginator.next_items())

Sandbox.list_snapshots(
    sandbox_id=sandbox.sandbox_id,
    api_key=os.environ["E2B_API_KEY"],
    api_url=os.environ["E2B_API_URL"],
    domain=os.environ["E2B_DOMAIN"],
)
Sandbox.list_snapshots(
    name="deps-ready",
    api_key=os.environ["E2B_API_KEY"],
    api_url=os.environ["E2B_API_URL"],
    domain=os.environ["E2B_DOMAIN"],
)

The names field of an unnamed Snapshot is empty, so name filtering does not match it. For listSnapshots / createSnapshot / deleteSnapshot static calls in TypeScript, configure E2B_API_URL through environment variables, and do not pass the unsupported apiUrl field.

Create a sandbox from a Snapshot

The template parameter of Sandbox.create can be a Snapshot ID or the qualified name of a named Snapshot. For a complete description of the creation parameters, see Create a Sandbox.

await Sandbox.create(snapshot.snapshotId, {
  apiKey: process.env.E2B_API_KEY,
  apiUrl: process.env.E2B_API_URL,
  domain: process.env.E2B_DOMAIN,
  timeoutMs: 300_000,
});

await Sandbox.create("demo-team/deps-ready", {
  apiKey: process.env.E2B_API_KEY,
  apiUrl: process.env.E2B_API_URL,
  domain: process.env.E2B_DOMAIN,
  timeoutMs: 300_000,
});

Sandbox.create(
    template=snapshot.snapshot_id,
    api_key=os.environ["E2B_API_KEY"],
    api_url=os.environ["E2B_API_URL"],
    domain=os.environ["E2B_DOMAIN"],
    timeout=300,
)

Sandbox.create(
    template="demo-team/deps-ready",
    api_key=os.environ["E2B_API_KEY"],
    api_url=os.environ["E2B_API_URL"],
    domain=os.environ["E2B_DOMAIN"],
    timeout=300,
)

Resolution rules:

1. <Team name>/<short name> or <Team name>/<short name>:<tag>: treated only as a Snapshot qualified name. If it is not found, the operation fails without falling back to a template.

2. Contains / but is malformed: the operation fails.

3. Does not contain /: the value is looked up as a Snapshot ID only when it is a UUID; if that lookup misses, it is created as a template name. A regular template name that is not a UUID is created as a template directly.

Can be overridden: timeout, idle timeout, secure, allowInternetAccess, user metadata, autoPause, autoResume, network, and custom sandbox ID.

Cannot be overridden (the operation fails if passed): environment variables, volume or file system mounts, function configuration, build or image, and system metadata with the fc. prefix.

A sandbox created from a Snapshot occupies that Snapshot. Deleting the Snapshot while it is occupied fails.

Expired or deleted Snapshots cannot be used to create sandboxes. If the source template is deleted after the Snapshot is created, the Snapshot can still be used to restore a sandbox.

Delete a Snapshot

The parameter is a single string: a Snapshot ID, or a qualified name from names. Deletion returns true on success and false if the Snapshot does not exist.

await Sandbox.deleteSnapshot(snapshot.snapshotId, {
  apiKey: process.env.E2B_API_KEY,
  domain: process.env.E2B_DOMAIN,
});
await Sandbox.deleteSnapshot(snapshot.names[0], {
  apiKey: process.env.E2B_API_KEY,
  domain: process.env.E2B_DOMAIN,
});

Sandbox.delete_snapshot(
    snapshot.snapshot_id,
    api_key=os.environ["E2B_API_KEY"],
    api_url=os.environ["E2B_API_URL"],
    domain=os.environ["E2B_DOMAIN"],
)
Sandbox.delete_snapshot(
    snapshot.names[0],
    api_key=os.environ["E2B_API_KEY"],
    api_url=os.environ["E2B_API_URL"],
    domain=os.environ["E2B_DOMAIN"],
)

• The Snapshot is still occupied by a restored sandbox: deletion fails.

• Deleting a Snapshot does not delete the source template or the source sandbox; deleting the source sandbox or the source template does not delete the Snapshot.

When deleting by qualified name, use names[0] returned by the create or list operation, or a qualified name assembled from the current Team name. Do not pass only the short name.

Source sandbox state

After creation fails, the source sandbox can still be used or deleted.

FAQ

Recommendations

• Prefer storing the Snapshot ID returned by the create operation. For a named Snapshot, also store names[0] to facilitate name-based restoration and deletion.

• Use a Snapshot when the same workspace state needs to be started repeatedly within up to 7 days. To pause a task only briefly, prefer Pause and Resume.

• Promptly delete Snapshots that are no longer needed to avoid ongoing storage fees.

• After restoring from a Snapshot, still call sandbox.kill() at the end of the task to release sandbox resources.