Function Compute：快照（Snapshot）（邀測）

功能介紹

Snapshot 功能當前僅支援第二代運行時。

Snapshot 儲存運行中沙箱在某一時刻的檔案系統與記憶體狀態。建立後的 Snapshot 獨立於源沙箱和源模板：刪除源沙箱或源模板不會刪除 Snapshot；刪除 Snapshot 也不會刪除源沙箱或源模板。

典型用法：在沙箱中安裝依賴、準備工作區後建立一份 Snapshot，之後用這份 Snapshot 秒級啟動同樣狀態的新沙箱，而不必重新構建模板。適用於 Agent 任務斷點續跑、環境預熱和並行複製探索等情境。

Snapshot 自建立起預設保留 7 天，到期後自動到期。到期後不再出現在列表中，也不能用於建立沙箱。Snapshot 留存獨立於源沙箱生命週期：源沙箱終止或逾時回收後，未到期的 Snapshot 仍可使用。

通過 E2B 相容 SDK 調用，相容性說明參見E2B 相容說明。認證與串連參數配置參見使用約束。

API 參考

建立 Snapshot 的執行個體方法與靜態方法語義相同。執行個體方法隱含當前沙箱，無需再傳 sandboxId / sandbox_id。列表與刪除僅提供靜態方法。

使用限制

• 僅可對運行中的沙箱建立 Snapshot。源沙箱已暫停、正在建立 Snapshot，或當前被其他動作佔用時，建立 Snapshot 會失敗。

• 當前僅支援第二代運行時。

• 有名 Snapshot 要求當前 Team 有名稱；Team 無名時只能建立無名 Snapshot。

• 建立過程中源沙箱 state 為 snapshotting，此時不可刪除該沙箱。完成後可繼續使用該沙箱，也可再次建立 Snapshot。

• 建立可能持續數分鐘。SDK 請求逾時建議不少於 300 秒（TypeScript：requestTimeoutMs: 300_000；Python：request_timeout=300）。timeoutMs / timeout 控制的是沙箱生命週期，不是 Snapshot 請求逾時；預設請求逾時通常為 60 秒，不加大時可能在建立完成前失敗。

• 建立 Snapshot 時源模板必須仍存在。建立成功後，即使之後刪除源模板，仍可用該 Snapshot 恢複沙箱。

建立 Snapshot

name 可選。省略時建立無名 Snapshot，此後僅可通過 Snapshot ID 訪問。

同一 Team 內，同一 (短名, tag) 同時只能存在一份可用 Snapshot，與源模板無關。名稱衝突時建立失敗，不覆蓋已有 Snapshot。不同 tag 可並存。刪除後該名稱立即釋放。

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,
)

同一沙箱可建立多份 Snapshot。

列出 Snapshot

返回當前 Team 未刪除且未到期的 Snapshot，按建立時間倒序。

建立成功後立即調用列表介面時，由於索引延遲，可能暫時看不到剛寫入的記錄。按 Snapshot ID 或全名恢複沙箱、刪除 Snapshot 均不受影響，可直接使用建立介面返回的 snapshotId / names。

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"],
)

無名 Snapshot 的 names 為空白，name 過濾不會命中。TypeScript 的 listSnapshots / createSnapshot / deleteSnapshot 靜態調用請通過環境變數配置 E2B_API_URL，不要傳入不受支援的 apiUrl 欄位。

從 Snapshot 建立沙箱

Sandbox.create 的模板參數可以是 Snapshot ID，也可以是有名 Snapshot 的全名。完整建立參數說明參見建立沙箱。

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,
)

解析規則：

1. <Team 名>/<短名> 或 <Team 名>/<短名>:<tag>：僅作為 Snapshot 全名。未找到則失敗，不會回退為模板。

2. 含 / 但形態不合法：失敗。

3. 不含 /：值為 UUID 時先按 Snapshot ID 尋找，未命中則按模板名建立；非 UUID 的普通模板名直接按模板名建立。

允許覆蓋：逾時、空閑逾時、secure、allowInternetAccess、使用者 metadata、autoPause、autoResume、網路、自訂沙箱 ID。

不允許覆蓋（傳入則失敗）：環境變數、卷 / 檔案系統掛載、函數配置、構建 / 鏡像、fc. 首碼的系統 metadata。

從 Snapshot 建立的沙箱會佔用該 Snapshot。佔用期間刪除該 Snapshot 會失敗。

已到期或已刪除的 Snapshot 不能用於建立沙箱。建立 Snapshot 之後刪除源模板，仍可用該 Snapshot 恢複。

刪除 Snapshot

參數為一個字串：Snapshot ID，或 names 中的全名。刪除成功返回 true，不存在返回 false。

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"],
)

• Snapshot 仍被已恢複沙箱佔用：刪除失敗。

• 刪除 Snapshot 不刪除源模板或源沙箱；刪除源沙箱或源模板不刪除 Snapshot。

按全名刪除時，請使用建立或列表返回的 names[0]，或當前 Team 名拼出的全名。不要只傳短名。

源沙箱狀態

建立失敗後，源沙箱仍可使用或刪除。

常見問題

使用建議

• 優先儲存建立返回的 Snapshot ID；有名 Snapshot 同時儲存 names[0]，便於按名恢複和刪除。

• 需要在最長 7 天內重複啟動同一工作區狀態的沙箱時使用 Snapshot；僅需短暫暫停任務時，優先使用暫停與恢複。

• 不用的 Snapshot 及時刪除，避免持續產生儲存費用。

• 從 Snapshot 恢複後，仍應在任務結束時調用 sandbox.kill() 釋放沙箱資源。