feat(sdk): fork via v2 endpoint, leave the count limit to the API, add keepMemory

[devin-ai-integration]

Summary

Moves SDK/CLI fork to POST /v2/sandboxes/{sandboxID}/fork (added in https://github.com/e2b-dev/belt/pull/4036) and removes the client-side fork count caps. The only limit left is the server's per-team fork limit (team limits: 20 on Hobby and Pro, custom on Enterprise). Adds a keepMemory / keep_memory fork option that maps to the v2 request's memory field.

• JS SandboxApi.forkSandbox: POST('/sandboxes/{sandboxID}/fork') becomes POST('/v2/sandboxes/{sandboxID}/fork'); MAX_FORK_COUNT / validateForkCount removed.
• Python sync/async _cls_fork: post_sandboxes_sandbox_id_fork + SandboxForkRequest becomes post_v_2_sandboxes_sandbox_id_fork + SandboxForkRequestV2; MAX_FORK_COUNT / validate_fork_count removed.
• keepMemory, named after the existing pause({ keepMemory }) option:

  await sandbox.fork({ count: 2, keepMemory: false }) // body: { count: 2, memory: false }

  sandbox.fork(count=2, keep_memory=False)

  With false, only the filesystem is captured: the forks cold-boot from disk and the source keeps running. When the option is omitted, memory is left off the request and the forks restore the source's memory as before. Unsupported environments return an API error (400/409); the server never quietly turns the request into a memory fork.
• CLI --count: still has to be a positive integer, but the <= 20 check is removed. The CLI doesn't expose keepMemory.
• spec/openapi.yml: v2 fork path + SandboxForkRequestV2 (including memory) taken from belt#4036, v1 marked deprecated. JS schema.gen.ts and the Python client regenerated with generate:api / make generate-api.
• The unreleased .changeset/cli-fork-max-count.md (client-side cap at 20, from Cap sandbox fork count at 20 #1909) is replaced by .changeset/fork-v2-server-limit.md.

Behavior change: omitting timeout/timeoutMs now gets the v2 default of 300s (v1 used 15s). Omitted count is still left off the request.

Tests: apiDefaults.test.ts and test_api_defaults.py check that memory is absent when unset and false when passed, for sync and async.

Risk & rollout

Blocked on https://github.com/e2b-dev/belt/pull/4036:

• Generated files fails because spec/openapi.yml has to match e2b-dev/runtime at the spec/runtime-ref pin, which doesn't include the v2 fork route yet. After belt#4036 is mirrored to runtime, bump spec/runtime-ref and re-run make codegen. The regenerated spec should match what's here.
• The JS/Python fork integration tests (production/staging) fail with no matching operation was found because the v2 route isn't deployed yet. All other SDK tests pass.
• keepMemory: false also needs the server's filesystem-only-checkpoint flag enabled for the team.

Merge and release only after belt#4036 is deployed.

Link to Devin session: https://app.devin.ai/sessions/f375710619bb49c9b79e537736121bda
Open in Devin Desktop: https://app.devin.ai/desktop/session/f375710619bb49c9b79e537736121bda?variant=devin
Requested by: @mishushakov

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[changeset-bot]

🦋 Changeset detected

Latest commit: 57811c6

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

This PR includes changesets to release 3 packages

Name	Type
@e2b/cli	Minor
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

[github-actions]

Package Artifacts

Built from 401513d. Download artifacts from this workflow run.

JS SDK (e2b@2.52.1-devin-1790766635-fork-v2.0):

npm install ./e2b-2.52.1-devin-1790766635-fork-v2.0.tgz

CLI (@e2b/cli@2.21.1-devin-1790766635-fork-v2.0):

npm install ./e2b-cli-2.21.1-devin-1790766635-fork-v2.0.tgz

Code Interpreter JS SDK (@e2b/code-interpreter@2.8.1-devin-1790766635-fork-v2.0):

npm install ./e2b-code-interpreter-2.8.1-devin-1790766635-fork-v2.0.tgz

Desktop JS SDK (@e2b/desktop@2.4.1-devin-1790766635-fork-v2.0):

npm install ./e2b-desktop-2.4.1-devin-1790766635-fork-v2.0.tgz

Python SDK (e2b==2.52.0+devin.1790766635.fork.v2):

pip install ./e2b-2.52.0+devin.1790766635.fork.v2-py3-none-any.whl

Code Interpreter Python SDK (e2b-code-interpreter==2.10.1+devin.1790766635.fork.v2):

pip install ./e2b_code_interpreter-2.10.1+devin.1790766635.fork.v2-py3-none-any.whl

Desktop Python SDK (e2b-desktop==2.6.0+devin.1790766635.fork.v2):

pip install ./e2b_desktop-2.6.0+devin.1790766635.fork.v2-py3-none-any.whl

[devin-ai-integration]

TASTE.md review of the fork v2 migration.

Checked: T-1/T-2 (JS, sync Python, and async Python stay in step: all three move to v2 and drop the cap together), T-3a, T-6, T-18 (SandboxForkRequestV2 stays internal), T-33, T-46 (signal is still passed through getSignal), T-52, T-59, T-60/T-61, T-62, T-69, T-74.

Violations: 1 (T-62/T-69), in 3 places. The count docs in JS and in both Python mirrors no longer say which error an over-limit count produces. Details are in the inline comments.

The main change fits T-52. Removing MAX_FORK_COUNT / validate_fork_count means the SDK no longer copies a backend business rule that the per-team max-fork-count flag has already outgrown. The CLI keeps its --count positive-integer parse, which counts as input parsing that produces a clear error (T-52b), not a mirrored limit.

Non-blocking note: the new timeout / timeoutMs docs state the server default ("300 seconds" / "5 minutes"). This isn't validation, so it's not counted as a violation. It is the same kind of copied server value that the count docs now avoid, though, and it will go stale if the API default changes.

[mishushakov]

check comments