feat(sdk): filesystem-only snapshots (pause memory:false) by bchalios · Pull Request #1465 · e2b-dev/E2B

bchalios · 2026-06-19T14:26:25Z

Summary

Adds an optional memory flag to pause in both the JS and Python SDKs. When memory is false, the pause captures only the filesystem (no memory snapshot); resuming such a snapshot cold-boots (reboots) the sandbox from disk — losing in-memory state, running processes, and open connections. Defaults to true (full memory snapshot), so existing callers are unaffected.

This is the SDK surface for the filesystem-only snapshot feature on the infra side.

Usage

// JS / TS
const sbx = await Sandbox.create()
await sbx.pause({ memory: false })   // filesystem-only snapshot
const resumed = await sbx.connect()  // resumes by cold-booting from disk

# Python (sync)
sbx = Sandbox()
sbx.pause(memory=False)              # filesystem-only snapshot
resumed = sbx.connect()              # resumes by cold-booting from disk

# Python (async)
sbx = await AsyncSandbox.create()
await sbx.pause(memory=False)
resumed = await sbx.connect()

memory defaults to true — pause() / pause({}) behave exactly as before.

What changed

spec: optional memory: boolean (default true) on POST /sandboxes/{sandboxID}/pause (SandboxPauseRequest); both API clients regenerated via make codegen.
JS: Sandbox.pause / betaPause accept { memory } → SandboxApi.pause sends the request body.
Python: pause(memory=...) / beta_pause → _cls_pause (sync + async) sends SandboxPauseRequest(memory=...).
Tests: filesystem-only pause+resume reboots the guest while the filesystem survives — JS (tests/sandbox/snapshot.test.ts) and Python sync + async. All pass against a local stack; format / lint / typecheck clean.
Changeset: minor for e2b and @e2b/python-sdk.

Note (related infra observation, not addressed here)

While testing, a filesystem-only resume cold-boots into a different default exec context (root / /root) than a memory resume (user / /home/user). The filesystem itself is fully intact; tests use absolute paths to be robust to this. Worth confirming on the infra reboot path whether the template's default user should be restored after a cold boot.

🤖 Generated with Claude Code

changeset-bot · 2026-06-19T14:26:30Z

🦋 Changeset detected

Latest commit: f259b02

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
e2b	Minor
@e2b/python-sdk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

cursor · 2026-06-19T14:26:31Z

PR Summary

Medium Risk
Pause/resume semantics change when callers opt out of memory snapshots; wrong docs would send users to a non-existent memory SDK option.

Overview
The PR description and title show pause({ memory: false }) and pause(memory=False), but the JS and Python SDKs in this diff expose keepMemory and keep_memory, mapped to the API body field memory.

^{Reviewed by Cursor Bugbot for commit f259b02. Bugbot is set up for automated code reviews on this repo. Configure here.}

github-actions · 2026-06-19T14:27:29Z

Package Artifacts

Built from 0177a12. Download artifacts from this workflow run.

JS SDK (e2b@2.30.7-feat-pause-filesystem-only.0):

npm install ./e2b-2.30.7-feat-pause-filesystem-only.0.tgz

CLI (@e2b/cli@2.13.1-feat-pause-filesystem-only.0):

npm install ./e2b-cli-2.13.1-feat-pause-filesystem-only.0.tgz

Python SDK (e2b==2.29.6+feat-pause-filesystem-only):

pip install ./e2b-2.29.6+feat.pause.filesystem.only-py3-none-any.whl

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4b7cf94857

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d54797f. Configure here.}

mishushakov

everything looks good - only thing is that i believe the envd token should be persistent across pause/resume cycle.
please use SandboxPauseOpts consistently.

mishushakov · 2026-06-19T14:55:01Z

   * ```
   */
-  async pause(opts?: ConnectionOpts): Promise<boolean> {
+  async pause(opts?: ConnectionOpts & { memory?: boolean }): Promise<boolean> {


we're not using the SandboxPauseOpts here

This was anchored to the pre-amend commit — it's addressed in the latest commit (57674a071): both pause and betaPause now take the exported SandboxPauseOpts (and the static SandboxApi.pause/betaPause too), matching how createSnapshot uses CreateSnapshotOpts. resolveApiOpts spreads the opts through, so memory reaches SandboxApi.pause.

mishushakov · 2026-06-19T14:55:02Z

  /**
   * @deprecated Use {@link Sandbox.pause} instead.
   */
-  async betaPause(opts?: ConnectionOpts): Promise<boolean> {


we're not using SandboxPauseOpts here

bchalios · 2026-06-19T16:34:45Z

Per offline feedback from @mishushakov, renamed the SDK-facing parameter to make the drop-on-false semantics explicit:

JS/TS: pause({ keepMemory: false })
Python: pause(keep_memory=False)

The wire/spec field stays memory (the contract with the API in the infra PR is unchanged) — the SDK simply maps keepMemory/keep_memory onto the memory body field with identical semantics (true = keep the full memory snapshot). No generated files changed. Typecheck/lint/format pass for both SDKs; changeset and docstrings updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Babis Chalios <babis.chalios@e2b.dev>

chatgpt-codex-connector · 2026-06-25T07:31:37Z

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

@returns

- Re-export SandboxPauseOpts from the package root so callers can `import { SandboxPauseOpts } from 'e2b'` (the point of the named type). - Fix Sandbox.pause @returns JSDoc: it returns a boolean (paused/already paused), not a sandbox ID. - Correct the resume test comments: connect() returns the same handle and its credentials stay valid across a filesystem-only resume (no stale handle). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

mishushakov

all looks good - in the tests you can use sandbox.files.read instead of cat, but i am fine with either

bchalios · 2026-06-25T10:30:27Z

Done in 1bed5d8 — switched the reads to files.read (and the marker write to files.write) in both Python tests and the JS test. I checked your instinct on cat for the boot id: files.read("/proc/sys/kernel/random/boot_id") returns the full UUID against a live stack (envd streams proc files fine), so no cat fallback is needed there either. Both Python tests pass live; JS typecheck/lint clean.

Per review (mishushakov): dogfood the SDK's filesystem API in its own tests. The rootfs marker and the kernel boot id are now written/read via files.write/files.read instead of echo/cat, in both Python tests and the JS test. files.read returns the full content for the /proc boot_id pseudo-file (verified against a live stack), so no cat fallback is needed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…form (#1471) ## Filesystem-only auto-pause (`onTimeout` object form) Adds an object form to the sandbox **lifecycle** `onTimeout` (`on_timeout` in Python) that controls the snapshot kind taken when a sandbox auto-pauses on timeout, via `keepMemory` (`keep_memory`). `onTimeout` now accepts either the existing bare action (`'pause'` / `'kill'`) or the object form `{ action, keepMemory }`. When `keepMemory` is `false` (with `action: 'pause'`), a timeout auto-pause takes a **filesystem-only** snapshot (no memory) instead of a full memory one, so the sandbox cold-boots (reboots) from disk on resume — losing running processes and open connections. Defaults to `true` (full memory snapshot), so existing callers are unaffected. **The bare string form is unchanged.** It's the create-time / auto-pause counterpart to the explicit `pause(keepMemory=false)` from #1465: same `keepMemory` naming, mapped onto the `autoPauseMemory` create field. ### Type safety The object form is a **discriminated union** on `action`: `keepMemory` is only valid with `action: 'pause'`. Pairing it with `action: 'kill'` is a **compile-time type error** (TS) / static error (`ty`), and is additionally rejected at runtime (`InvalidArgumentError` / `InvalidArgumentException`) for untyped callers. ### Behavior & validation - `keepMemory` only applies to a `pause` action. - **Incompatible with auto-resume** — auto-resume wakes a paused sandbox on inbound traffic by restoring its memory snapshot in place; a filesystem-only snapshot has no memory to restore (resuming cold-boots it), so it must be resumed explicitly via `connect()`. Combining `keepMemory: false` with `autoResume` is rejected client-side. ### Usage ```ts // JS/TS — filesystem-only auto-pause on timeout const sbx = await Sandbox.create({ lifecycle: { onTimeout: { action: 'pause', keepMemory: false } }, }) // bare string form still works (full memory snapshot) const sbx2 = await Sandbox.create({ lifecycle: { onTimeout: 'pause' } }) ``` ```python # Python sbx = Sandbox.create( lifecycle={"on_timeout": {"action": "pause", "keep_memory": False}} ) ``` ### Changes - `spec/openapi.yml`: `autoPauseMemory` on the create body (+ regenerated JS/Python clients). - JS `SandboxOnTimeout` discriminated union (`'pause' | 'kill' | { action: 'pause'; keepMemory? } | { action: 'kill' }`) and the Python `SandboxOnTimeoutPause` / `SandboxOnTimeoutKill` TypedDicts, wired through `createSandbox` / `_create_sandbox` (sync + async) to `autoPauseMemory`, with the client-side guards. - Tests: payload serialization + validation (offline, incl. the `action: 'kill'` type/runtime guard) and live cold-boot e2e in both SDKs; changeset (`e2b` + `@e2b/python-sdk`, minor). ### Backend dependency The live e2e tests exercise the real auto-pause→cold-boot path and require the infra-side `autoPauseMemory` support (e2b-dev/infra#3055), now merged and deployed. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Signed-off-by: Babis Chalios <babis.chalios@e2b.dev> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

bchalios requested review from ValentaTomas, jakubno and mishushakov as code owners June 19, 2026 14:26

cla-bot Bot added the cla-signed label Jun 19, 2026

bchalios force-pushed the feat/pause-filesystem-only branch from 4b7cf94 to d434332 Compare June 19, 2026 14:30

chatgpt-codex-connector Bot reviewed Jun 19, 2026

View reviewed changes

Comment thread packages/js-sdk/src/sandbox/index.ts Outdated

bchalios force-pushed the feat/pause-filesystem-only branch from d434332 to d54797f Compare June 19, 2026 14:35

cursor Bot reviewed Jun 19, 2026

View reviewed changes

Comment thread packages/js-sdk/src/sandbox/index.ts Outdated

bchalios marked this pull request as draft June 19, 2026 14:43

bchalios force-pushed the feat/pause-filesystem-only branch from d54797f to 57674a0 Compare June 19, 2026 14:52

mishushakov reviewed Jun 19, 2026

View reviewed changes

bchalios force-pushed the feat/pause-filesystem-only branch from 57674a0 to 59a8378 Compare June 19, 2026 16:34

mishushakov approved these changes Jun 19, 2026

View reviewed changes

feat(sdk): add keepMemory option to pause for filesystem-only snapshots

a6d3323

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Babis Chalios <babis.chalios@e2b.dev>

bchalios force-pushed the feat/pause-filesystem-only branch from 9e798d5 to a6d3323 Compare June 22, 2026 10:42

bchalios mentioned this pull request Jun 22, 2026

feat(sdk): filesystem-only auto-pause via lifecycle.onTimeout object form #1471

Merged

bchalios added 2 commits June 23, 2026 13:59

Merge branch 'main' into feat/pause-filesystem-only

37e70de

Merge branch 'main' into feat/pause-filesystem-only

172a00f

bchalios marked this pull request as ready for review June 25, 2026 07:31

claude Bot reviewed Jun 25, 2026

View reviewed changes

Comment thread packages/js-sdk/src/sandbox/sandboxApi.ts

Comment thread packages/js-sdk/tests/sandbox/snapshot.test.ts

Comment thread packages/js-sdk/src/sandbox/index.ts Outdated

mishushakov approved these changes Jun 25, 2026

View reviewed changes

bchalios force-pushed the feat/pause-filesystem-only branch from 4a0e4c2 to 1bed5d8 Compare June 25, 2026 10:30

bchalios force-pushed the feat/pause-filesystem-only branch from 1bed5d8 to f259b02 Compare June 25, 2026 10:33

bchalios enabled auto-merge (squash) June 25, 2026 10:33

bchalios merged commit cb5a387 into main Jun 25, 2026
28 of 29 checks passed

bchalios deleted the feat/pause-filesystem-only branch June 25, 2026 10:42

Uh oh!

Conversation

bchalios commented Jun 19, 2026

Summary

Usage

What changed

Note (related infra observation, not addressed here)

Uh oh!

changeset-bot Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

cursor Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

github-actions Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Package Artifacts

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mishushakov left a comment

Choose a reason for hiding this comment

Uh oh!

mishushakov Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

bchalios Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

mishushakov Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

bchalios commented Jun 19, 2026

Uh oh!

chatgpt-codex-connector Bot commented Jun 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mishushakov left a comment

Choose a reason for hiding this comment

Uh oh!

bchalios commented Jun 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot Bot commented Jun 19, 2026 •

edited

Loading

cursor Bot commented Jun 19, 2026 •

edited

Loading

github-actions Bot commented Jun 19, 2026 •

edited

Loading