Skip to content

armgit / E2B

Public Imported from GitHub
0

Open-source, secure environment with real-world tools for enterprise-grade agents.

Cap sandbox fork count at 20 (#1909)

Jakub Dobry2de0cc392173
diff --git a/.changeset/cli-fork-max-count.md b/.changeset/cli-fork-max-count.md
new file mode 100644
index 000000000..3582e2325
--- /dev/null
+++ b/.changeset/cli-fork-max-count.md
@@ -0,0 +1,7 @@
+---
+'@e2b/cli': minor
+'e2b': minor
+'@e2b/python-sdk': minor
+---
+
+Cap sandbox fork count at 20. `e2b sandbox fork --count`, JavaScript `Sandbox.fork({ count })`, and Python `Sandbox.fork(count=...)` reject a count outside 1–20 before the API call. Counts from 21 through 100 used to reach the API. Omitting count still leaves the field off the request so the API default applies.
diff --git a/packages/cli/src/commands/sandbox/fork.ts b/packages/cli/src/commands/sandbox/fork.ts
index d6880bde4..054ba98b2 100644
--- a/packages/cli/src/commands/sandbox/fork.ts
+++ b/packages/cli/src/commands/sandbox/fork.ts
@@ -6,7 +6,7 @@ import { ensureAPIKey } from 'src/api'
import { asBold } from 'src/utils/format'
import { parseTimeout } from './create'
-const MAX_COUNT = 100
+const MAX_COUNT = 20
function parseCount(countRaw: string): number {
const count = Number(countRaw)
diff --git a/packages/cli/tests/commands/sandbox/fork.test.ts b/packages/cli/tests/commands/sandbox/fork.test.ts
index 4d6b22412..a20a941b4 100644
--- a/packages/cli/tests/commands/sandbox/fork.test.ts
+++ b/packages/cli/tests/commands/sandbox/fork.test.ts
@@ -114,11 +114,27 @@ describe('sandbox fork', () => {
expect(exitSpy).toHaveBeenCalledWith(1)
})
- test.each(['0', '101', '1.5', 'abc'])(
+ test('accepts the maximum count', async () => {
+ mocks.fork.mockResolvedValue(
+ Array.from({ length: 20 }, (_, index) => ({
+ sandboxId: `fork-${index + 1}`,
+ }))
+ )
+
+ const { exitSpy } = await runFork(['source-id', '--count', '20'])
+
+ expect(mocks.fork).toHaveBeenCalledWith('source-id', {
+ apiKey: 'test-api-key',
+ count: 20,
+ })
+ expect(exitSpy).toHaveBeenCalledWith(0)
+ })
+
+ test.each(['0', '-1', '21', '101', '1.5', 'abc'])(
'rejects count %s',
async (count: string) => {
await expect(runFork(['source-id', '--count', count])).rejects.toThrow(
- '--count must be an integer between 1 and 100'
+ '--count must be an integer between 1 and 20'
)
expect(mocks.fork).not.toHaveBeenCalled()
}
diff --git a/packages/js-sdk/src/sandbox/sandboxApi.ts b/packages/js-sdk/src/sandbox/sandboxApi.ts
index c14486353..c9c011fad 100644
--- a/packages/js-sdk/src/sandbox/sandboxApi.ts
+++ b/packages/js-sdk/src/sandbox/sandboxApi.ts
@@ -537,7 +537,8 @@ export interface SandboxPauseOpts extends SandboxApiOpts {
*/
export interface SandboxForkOpts extends ConnectionOpts {
/**
- * Number of forked sandboxes to create.
+ * Number of forked sandboxes to create. Must be an integer between 1 and 20.
+ * When omitted, the field is left off the request and the API default applies.
*
* All forks boot from the same snapshot — the snapshot is captured once
* regardless of count. Each fork succeeds or fails independently; the
@@ -558,6 +559,19 @@ export interface SandboxForkOpts extends ConnectionOpts {
* from starting. Per-fork error codes map to the same error classes as other
* API errors (e.g. 429 to `RateLimitError`).
*/
+const MAX_FORK_COUNT = 20
+
+function validateForkCount(count: number | undefined) {
+ if (count === undefined) {
+ return
+ }
+ if (!Number.isInteger(count) || count < 1 || count > MAX_FORK_COUNT) {
+ throw new InvalidArgumentError(
+ `count must be an integer between 1 and ${MAX_FORK_COUNT}`
+ )
+ }
+}
+
type SandboxForkResponse =
| {
sandboxId: string
@@ -1762,6 +1776,8 @@ export class SandboxApi extends ClientFactory {
count?: number,
opts?: SandboxApiOpts
): Promise<SandboxForkResponse[]> {
+ validateForkCount(count)
+
const apiOpts = this.resolveOpts(opts)
const config = new ConnectionConfig(apiOpts)
const client = new ApiClient(config)
diff --git a/packages/js-sdk/tests/sandbox/apiDefaults.test.ts b/packages/js-sdk/tests/sandbox/apiDefaults.test.ts
index 91459cc6d..750f4f948 100644
--- a/packages/js-sdk/tests/sandbox/apiDefaults.test.ts
+++ b/packages/js-sdk/tests/sandbox/apiDefaults.test.ts
@@ -1,7 +1,7 @@
import { afterAll, afterEach, beforeAll, expect, test } from 'vitest'
import { http, HttpResponse } from 'msw'
-import { Sandbox } from '../../src'
+import { InvalidArgumentError, Sandbox } from '../../src'
import { TEST_API_KEY, apiUrl } from '../setup'
import { setupMockApi } from '../mockApi'
@@ -103,6 +103,27 @@ test('Sandbox.fork sends explicit timeout and count', async () => {
expect(lastForkBody?.count).toBe(2)
})
+test('Sandbox.fork sends the maximum count', async () => {
+ await Sandbox.fork('test-sandbox-id', {
+ apiKey: TEST_API_KEY,
+ count: 20,
+ })
+
+ expect(lastForkBody?.count).toBe(20)
+})
+
+test.each([0, -1, 21, 101, 1.5])(
+ 'Sandbox.fork rejects count %s',
+ async (count) => {
+ await expect(
+ Sandbox.fork('test-sandbox-id', { apiKey: TEST_API_KEY, count })
+ ).rejects.toThrow(
+ new InvalidArgumentError('count must be an integer between 1 and 20')
+ )
+ expect(lastForkBody).toBeUndefined()
+ }
+)
+
test('Sandbox.pause omits memory when keepMemory is unset', async () => {
await Sandbox.pause('test-sandbox-id', { apiKey: TEST_API_KEY })
diff --git a/packages/python-sdk/e2b/sandbox/sandbox_api.py b/packages/python-sdk/e2b/sandbox/sandbox_api.py
index f58da89a4..71b5b600c 100644
--- a/packages/python-sdk/e2b/sandbox/sandbox_api.py
+++ b/packages/python-sdk/e2b/sandbox/sandbox_api.py
@@ -73,6 +73,27 @@ from e2b.sandbox.network import ALL_TRAFFIC
from e2b.paginator import PaginatorBase
+MAX_FORK_COUNT = 20
+
+
+def validate_fork_count(count: Any) -> None:
+ """Reject a fork count the SDK will not send.
+
+ ``None`` is left off the request so the API default applies.
+ """
+ if count is None:
+ return
+ if (
+ isinstance(count, bool)
+ or not isinstance(count, int)
+ or count < 1
+ or count > MAX_FORK_COUNT
+ ):
+ raise InvalidArgumentException(
+ f"count must be an integer between 1 and {MAX_FORK_COUNT}"
+ )
+
+
class GitHubMcpServerConfig(TypedDict):
"""
Configuration for a GitHub-based MCP server.
diff --git a/packages/python-sdk/e2b/sandbox_async/main.py b/packages/python-sdk/e2b/sandbox_async/main.py
index a5eac9264..32dd2ba2e 100644
--- a/packages/python-sdk/e2b/sandbox_async/main.py
+++ b/packages/python-sdk/e2b/sandbox_async/main.py
@@ -414,7 +414,7 @@ class AsyncSandbox(SandboxApi):
(e.g. 429 to `RateLimitException`).
:param timeout: Timeout for the forked sandboxes in **seconds**.
- :param count: Number of forked sandboxes to create.
+ :param count: Number of forked sandboxes to create. An integer between 1 and 20. Omitted, the API default applies.
:return: List with one entry per requested fork — a sandbox instance or an exception
@@ -453,7 +453,7 @@ class AsyncSandbox(SandboxApi):
:param sandbox_id: Sandbox ID
:param timeout: Timeout for the forked sandboxes in **seconds**.
- :param count: Number of forked sandboxes to create.
+ :param count: Number of forked sandboxes to create. An integer between 1 and 20. Omitted, the API default applies.
:param logger: Logger used for request and response logging for the forked sandboxes. Accepts any standard library `logging.Logger`. When omitted, no request/response logging is emitted.
:return: List with one entry per requested fork — a sandbox instance or an exception
@@ -490,7 +490,7 @@ class AsyncSandbox(SandboxApi):
(e.g. 429 to `RateLimitException`).
:param timeout: Timeout for the forked sandboxes in **seconds**.
- :param count: Number of forked sandboxes to create.
+ :param count: Number of forked sandboxes to create. An integer between 1 and 20. Omitted, the API default applies.
:return: List with one entry per requested fork — a sandbox instance or an exception
diff --git a/packages/python-sdk/e2b/sandbox_async/sandbox_api.py b/packages/python-sdk/e2b/sandbox_async/sandbox_api.py
index ca0de6417..ef12afba5 100644
--- a/packages/python-sdk/e2b/sandbox_async/sandbox_api.py
+++ b/packages/python-sdk/e2b/sandbox_async/sandbox_api.py
@@ -62,6 +62,7 @@ from e2b.sandbox.sandbox_api import (
build_iam_config,
build_lifecycle_config,
build_network_config,
+ validate_fork_count,
)
from e2b.sandbox_async.paginator import AsyncSandboxPaginator
@@ -445,6 +446,7 @@ class SandboxApi(SandboxBase):
logger: Optional[logging.Logger] = None,
**opts: Unpack[ApiParams],
) -> List[Union[SandboxCreateResponse, Exception]]:
+ validate_fork_count(count)
config = ConnectionConfig(logger=logger, **cls._resolve_api_params(**opts))
api_client = get_api_client(config)
diff --git a/packages/python-sdk/e2b/sandbox_sync/main.py b/packages/python-sdk/e2b/sandbox_sync/main.py
index 5dfae376f..22d57c5e6 100644
--- a/packages/python-sdk/e2b/sandbox_sync/main.py
+++ b/packages/python-sdk/e2b/sandbox_sync/main.py
@@ -409,7 +409,7 @@ class Sandbox(SandboxApi):
(e.g. 429 to `RateLimitException`).
:param timeout: Timeout for the forked sandboxes in **seconds**.
- :param count: Number of forked sandboxes to create.
+ :param count: Number of forked sandboxes to create. An integer between 1 and 20. Omitted, the API default applies.
:return: List with one entry per requested fork — a sandbox instance or an exception
@@ -448,7 +448,7 @@ class Sandbox(SandboxApi):
:param sandbox_id: Sandbox ID
:param timeout: Timeout for the forked sandboxes in **seconds**.
- :param count: Number of forked sandboxes to create.
+ :param count: Number of forked sandboxes to create. An integer between 1 and 20. Omitted, the API default applies.
:param logger: Logger used for request and response logging for the forked sandboxes. Accepts any standard library `logging.Logger`. When omitted, no request/response logging is emitted.
:return: List with one entry per requested fork — a sandbox instance or an exception
@@ -485,7 +485,7 @@ class Sandbox(SandboxApi):
(e.g. 429 to `RateLimitException`).
:param timeout: Timeout for the forked sandboxes in **seconds**.
- :param count: Number of forked sandboxes to create.
+ :param count: Number of forked sandboxes to create. An integer between 1 and 20. Omitted, the API default applies.
:return: List with one entry per requested fork — a sandbox instance or an exception
diff --git a/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py b/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py
index 07f65f5e3..d351e0928 100644
--- a/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py
+++ b/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py
@@ -61,6 +61,7 @@ from e2b.sandbox.sandbox_api import (
build_iam_config,
build_lifecycle_config,
build_network_config,
+ validate_fork_count,
)
from e2b.sandbox_sync.paginator import SandboxPaginator, get_api_client
@@ -399,6 +400,7 @@ class SandboxApi(SandboxBase):
logger: Optional[logging.Logger] = None,
**opts: Unpack[ApiParams],
) -> List[Union[SandboxCreateResponse, Exception]]:
+ validate_fork_count(count)
config = ConnectionConfig(logger=logger, **cls._resolve_api_params(**opts))
api_client = get_api_client(config)
diff --git a/packages/python-sdk/tests/shared/sandbox/test_api_defaults.py b/packages/python-sdk/tests/shared/sandbox/test_api_defaults.py
index 1ab0b5779..2c1c3678a 100644
--- a/packages/python-sdk/tests/shared/sandbox/test_api_defaults.py
+++ b/packages/python-sdk/tests/shared/sandbox/test_api_defaults.py
@@ -2,7 +2,9 @@ from types import SimpleNamespace
from typing import Any, Dict
from unittest.mock import AsyncMock, Mock
-from e2b import AsyncSandbox, Sandbox
+import pytest
+
+from e2b import AsyncSandbox, InvalidArgumentException, Sandbox
from e2b.api.client.api.sandboxes import (
post_v2_sandboxes,
post_v_2_sandboxes_sandbox_id_connect,
@@ -128,6 +130,26 @@ def test_fork_sends_explicit_timeout_and_count(monkeypatch, test_api_key):
assert body["count"] == 2
+def test_fork_sends_the_maximum_count(monkeypatch, test_api_key):
+ body = _sync_fork_body(monkeypatch, test_api_key, count=20)
+
+ assert body["count"] == 20
+
+
[email protected]("count", [0, -1, 21, 101, 1.5, True, "abc"])
+def test_fork_rejects_count_outside_1_to_20(monkeypatch, test_api_key, count):
+ request = Mock(return_value=SimpleNamespace(status_code=200, parsed=[]))
+ monkeypatch.setattr(post_sandboxes_sandbox_id_fork, "sync_detailed", request)
+
+ with pytest.raises(
+ InvalidArgumentException,
+ match="count must be an integer between 1 and 20",
+ ):
+ Sandbox.fork("sbx-test", api_key=test_api_key, count=count)
+
+ request.assert_not_called()
+
+
async def test_async_fork_omits_timeout_and_count_when_unset(monkeypatch, test_api_key):
body = await _async_fork_body(monkeypatch, test_api_key)
@@ -142,6 +164,28 @@ async def test_async_fork_sends_explicit_timeout_and_count(monkeypatch, test_api
assert body["count"] == 2
+async def test_async_fork_sends_the_maximum_count(monkeypatch, test_api_key):
+ body = await _async_fork_body(monkeypatch, test_api_key, count=20)
+
+ assert body["count"] == 20
+
+
[email protected]("count", [0, -1, 21, 101, 1.5, True, "abc"])
+async def test_async_fork_rejects_count_outside_1_to_20(
+ monkeypatch, test_api_key, count
+):
+ request = AsyncMock(return_value=SimpleNamespace(status_code=200, parsed=[]))
+ monkeypatch.setattr(post_sandboxes_sandbox_id_fork, "asyncio_detailed", request)
+
+ with pytest.raises(
+ InvalidArgumentException,
+ match="count must be an integer between 1 and 20",
+ ):
+ await AsyncSandbox.fork("sbx-test", api_key=test_api_key, count=count)
+
+ request.assert_not_called()
+
+
def _sync_pause_body(monkeypatch, api_key: str, **kwargs) -> Dict[str, Any]:
request = Mock(return_value=SimpleNamespace(status_code=204, parsed=None))
monkeypatch.setattr(post_sandboxes_sandbox_id_pause, "sync_detailed", request)