feat(sdk): filesystem-only auto-pause via lifecycle.keepMemory

[bchalios]

Filesystem-only auto-pause (lifecycle.keepMemory)

Adds a keepMemory option (keep_memory in Python) to the sandbox lifecycle config. When false and onTimeout is 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.

It's the create-time / auto-pause counterpart to the explicit pause(keepMemory=false) added in #1465: same keepMemory naming, mapped onto the new autoPauseMemory create field.

Behavior & validation

• Only meaningful when onTimeout/on_timeout is pause; rejected client-side otherwise.
• Incompatible with auto-resume — a filesystem-only snapshot can't be auto-resumed by traffic (it would cold-boot), so it must be resumed explicitly; combining keepMemory: false with autoResume is rejected client-side.

Usage

// JS/TS — auto-pause this sandbox filesystem-only on timeout
const sbx = await Sandbox.create({
  lifecycle: { onTimeout: 'pause', keepMemory: false },
})

# Python
sbx = Sandbox(lifecycle={"on_timeout": "pause", "keep_memory": False})

Changes

• spec/openapi.yml: autoPauseMemory on the create body (+ regenerated JS/Python clients).
• JS SandboxLifecycle.keepMemory and Python SandboxLifecycle.keep_memory, wired through createSandbox / _create_sandbox (sync + async) to autoPauseMemory, with the two client-side guards.
• Tests: payload-serialization + validation (offline) and live cold-boot e2e in both SDKs; changeset (e2b + @e2b/python-sdk, minor).

⚠️ Stacked on #1465 — merge that first

This branch is stacked on top of #1465 (feat/pause-filesystem-only); its base is that branch, so the diff here is only the auto-pause commit. #1465 must merge first. There is no conflict between the two — this branch was rebased cleanly on top of #1465 (both touch spec/openapi.yml, the generated clients, and changesets, but in non-overlapping regions, and stacking incorporates #1465's changes first). Once #1465 merges, GitHub auto-retargets this PR's base to main.

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) to be merged and deployed; until then they'll be red in CI. The offline payload/validation tests pass independently.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 09c9826

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]

PR Summary

Medium Risk
Changes sandbox pause/resume semantics for opt-in callers and depends on backend autoPauseMemory support for live e2e tests; defaults preserve prior behavior.

Overview
Adds lifecycle.keepMemory (keep_memory in Python) so timeout auto-pause can take a filesystem-only snapshot instead of a full memory one. When false with onTimeout/on_timeout set to pause, resume cold-boots from disk (processes and connections are lost) while the filesystem is kept. Default stays true, so existing behavior is unchanged.

The create API field autoPauseMemory is added in OpenAPI and generated clients; SDKs map keepMemory → autoPauseMemory only when auto-pause applies. Client-side validation rejects keepMemory: false unless timeout action is pause, and rejects combining it with autoResume.

Tests cover payload serialization, validation errors, and live e2e cold-boot on connect in JS and Python (sync/async). Minor version bumps in the changeset for e2b and @e2b/python-sdk.

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

[github-actions]

Package Artifacts

Built from 57125b4. Download artifacts from this workflow run.

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

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

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

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

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

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

[bchalios]

Addressed the two actionable points from the Cursor summary (pushed):

1. autoPauseMemory sent on every create — now only sent when onTimeout/on_timeout is pause; omitted otherwise (JS sends undefined, Python leaves it UNSET). keepMemory is forced true when not pausing anyway, so this is behavior-preserving and matches the field's contract.
2. Missing test for the keepMemory=false + non-pause guard — added a dedicated offline test in all three SDKs: keepMemory=false requires onTimeout pause (JS) and test_filesystem_only_auto_pause_requires_pause (Python sync + async). Both guards (requires-pause and incompatible-with-auto-resume) now have offline coverage.

The third point (live cold-boot e2e depends on the backend autoPauseMemory support) is the known dependency on e2b-dev/infra#3055 — those tests stay red in CI until it deploys; the offline payload/validation tests pass independently.

JS typecheck/lint and Python ruff all pass.