Skip to content

armgit / E2B

Public Imported from GitHub
0

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

fix(sdk): omit autoResume from the create request when unset (#1694)

cursor[bot]53676931b89b
diff --git a/.changeset/omit-unset-auto-resume.md b/.changeset/omit-unset-auto-resume.md
new file mode 100644
index 000000000..65a51d7fd
--- /dev/null
+++ b/.changeset/omit-unset-auto-resume.md
@@ -0,0 +1,26 @@
+---
+'e2b': patch
+'@e2b/python-sdk': patch
+---
+
+Omit `autoResume` from the `POST /sandboxes` request when `lifecycle.autoResume` / `lifecycle["auto_resume"]` is not configured, instead of sending the SDK's local default as `{ "autoResume": { "enabled": false } }`. The API can now tell an unset preference from an explicit opt-out and own the default itself. Explicit values are unchanged on the wire.
+
+```ts
+import { Sandbox } from 'e2b'
+
+// autoResume is left out of the request entirely — the API's default applies
+await Sandbox.create({ lifecycle: { onTimeout: 'pause' } })
+
+// an explicit choice is still sent as before
+await Sandbox.create({ lifecycle: { onTimeout: 'pause', autoResume: true } })
+```
+
+```python
+from e2b import Sandbox
+
+# auto_resume is left out of the request entirely — the API's default applies
+Sandbox.create(lifecycle={"on_timeout": "pause"})
+
+# an explicit choice is still sent as before
+Sandbox.create(lifecycle={"on_timeout": "pause", "auto_resume": True})
+```
diff --git a/packages/js-sdk/src/sandbox/sandboxApi.ts b/packages/js-sdk/src/sandbox/sandboxApi.ts
index 5d8842633..5e6f31177 100644
--- a/packages/js-sdk/src/sandbox/sandboxApi.ts
+++ b/packages/js-sdk/src/sandbox/sandboxApi.ts
@@ -460,7 +460,9 @@ export type SandboxLifecycle = {
/**
* Auto-resume enabled flag.
- * @default false
+ *
+ * Leave unset to let the API pick the behavior. Set `false` to opt out
+ * explicitly and keep auto-resume off even if the API's default changes.
* Can be `true` only when `onTimeout` is `pause`. Not supported when
* `keepMemory` is `false` (a filesystem-only snapshot must be resumed
* explicitly via `connect()`).
@@ -1585,7 +1587,10 @@ export class SandboxApi {
typeof onTimeout !== 'string' && 'keepMemory' in onTimeout
? (onTimeout.keepMemory ?? true)
: true
- const autoResume = opts?.lifecycle?.autoResume ?? false
+ // A missing autoResume (or an explicit null from an untyped caller) is left
+ // out of the request entirely, so the API keeps ownership of the default
+ // instead of receiving the SDK's local one as an explicit opt-out.
+ const autoResume = opts?.lifecycle?.autoResume ?? undefined
if (hasKeepMemory && action !== 'pause') {
throw new InvalidArgumentError(
@@ -1622,7 +1627,8 @@ export class SandboxApi {
autoPause: onTimeoutConfigured ? action === 'pause' : undefined,
autoPauseMemory:
action === 'pause' && hasKeepMemory ? keepMemory : undefined,
- autoResume: { enabled: autoResume },
+ autoResume:
+ autoResume === undefined ? undefined : { enabled: autoResume },
}
if (opts?.volumeMounts) {
diff --git a/packages/js-sdk/tests/sandbox/lifecycleRequest.test.ts b/packages/js-sdk/tests/sandbox/lifecycleRequest.test.ts
index 03fad1990..e3c5bb6ce 100644
--- a/packages/js-sdk/tests/sandbox/lifecycleRequest.test.ts
+++ b/packages/js-sdk/tests/sandbox/lifecycleRequest.test.ts
@@ -35,6 +35,7 @@ test('Sandbox.create omits autoPause when no lifecycle is configured', async ()
expect(lastCreateBody).toBeDefined()
expect(lastCreateBody).not.toHaveProperty('autoPause')
expect(lastCreateBody).not.toHaveProperty('autoPauseMemory')
+ expect(lastCreateBody).not.toHaveProperty('autoResume')
})
test('Sandbox.create sends autoPause: false for an explicit kill', async () => {
@@ -45,6 +46,7 @@ test('Sandbox.create sends autoPause: false for an explicit kill', async () => {
expect(lastCreateBody?.autoPause).toBe(false)
expect(lastCreateBody).not.toHaveProperty('autoPauseMemory')
+ expect(lastCreateBody).not.toHaveProperty('autoResume')
})
test('Sandbox.create sends autoPause: true for an explicit pause', async () => {
@@ -56,6 +58,7 @@ test('Sandbox.create sends autoPause: true for an explicit pause', async () => {
expect(lastCreateBody?.autoPause).toBe(true)
// Bare 'pause' expresses no preference about the snapshot kind.
expect(lastCreateBody).not.toHaveProperty('autoPauseMemory')
+ expect(lastCreateBody).not.toHaveProperty('autoResume')
})
test('Sandbox.create omits autoPauseMemory when pause omits keepMemory', async () => {
@@ -66,6 +69,7 @@ test('Sandbox.create omits autoPauseMemory when pause omits keepMemory', async (
expect(lastCreateBody?.autoPause).toBe(true)
expect(lastCreateBody).not.toHaveProperty('autoPauseMemory')
+ expect(lastCreateBody).not.toHaveProperty('autoResume')
})
test('Sandbox.create sends the pause snapshot kind alongside autoPause', async () => {
@@ -76,6 +80,7 @@ test('Sandbox.create sends the pause snapshot kind alongside autoPause', async (
expect(lastCreateBody?.autoPause).toBe(true)
expect(lastCreateBody?.autoPauseMemory).toBe(false)
+ expect(lastCreateBody).not.toHaveProperty('autoResume')
await Sandbox.create('base', {
apiKey: TEST_API_KEY,
@@ -84,6 +89,7 @@ test('Sandbox.create sends the pause snapshot kind alongside autoPause', async (
expect(lastCreateBody?.autoPause).toBe(true)
expect(lastCreateBody?.autoPauseMemory).toBe(true)
+ expect(lastCreateBody).not.toHaveProperty('autoResume')
})
test('Sandbox.create omits autoPause for a lifecycle without onTimeout', async () => {
@@ -96,6 +102,7 @@ test('Sandbox.create omits autoPause for a lifecycle without onTimeout', async (
expect(lastCreateBody).toBeDefined()
expect(lastCreateBody).not.toHaveProperty('autoPause')
+ expect(lastCreateBody?.autoResume).toEqual({ enabled: false })
await Sandbox.create('base', {
apiKey: TEST_API_KEY,
@@ -104,6 +111,7 @@ test('Sandbox.create omits autoPause for a lifecycle without onTimeout', async (
expect(lastCreateBody).toBeDefined()
expect(lastCreateBody).not.toHaveProperty('autoPause')
+ expect(lastCreateBody).not.toHaveProperty('autoResume')
})
test('Sandbox.create rejects autoResume without a timeout action', async () => {
@@ -118,3 +126,31 @@ test('Sandbox.create rejects autoResume without a timeout action', async () => {
expect(lastCreateBody).toBeUndefined()
})
+
+test('an explicit autoResume: false is sent', async () => {
+ await Sandbox.create('base', {
+ apiKey: TEST_API_KEY,
+ lifecycle: { onTimeout: 'pause', autoResume: false },
+ })
+
+ expect(lastCreateBody?.autoResume).toEqual({ enabled: false })
+})
+
+test('an explicit autoResume: true is sent', async () => {
+ await Sandbox.create('base', {
+ apiKey: TEST_API_KEY,
+ lifecycle: { onTimeout: 'pause', autoResume: true },
+ })
+
+ expect(lastCreateBody?.autoResume).toEqual({ enabled: true })
+})
+
+test('an explicit null autoResume from an untyped caller is omitted', async () => {
+ await Sandbox.create('base', {
+ apiKey: TEST_API_KEY,
+ // @ts-expect-error null is not a valid autoResume value
+ lifecycle: { onTimeout: 'pause', autoResume: null },
+ })
+
+ expect(lastCreateBody).not.toHaveProperty('autoResume')
+})
diff --git a/packages/python-sdk/e2b/sandbox/sandbox_api.py b/packages/python-sdk/e2b/sandbox/sandbox_api.py
index dc5b46e0e..c13d0d28b 100644
--- a/packages/python-sdk/e2b/sandbox/sandbox_api.py
+++ b/packages/python-sdk/e2b/sandbox/sandbox_api.py
@@ -531,7 +531,7 @@ class SandboxLifecycle(TypedDict):
"""
Sandbox lifecycle configuration; defines post-timeout behavior and auto-resume
settings. An omitted `on_timeout` leaves the choice to the API (currently
- `"kill"`); `auto_resume` defaults to `False`.
+ `"kill"`); an omitted `auto_resume` leaves the choice to the API.
"""
on_timeout: SandboxOnTimeout
@@ -546,10 +546,11 @@ class SandboxLifecycle(TypedDict):
auto_resume: NotRequired[bool]
"""
- Whether activity should cause the sandbox to resume when paused. Defaults to `False`.
- Can be `True` only when `on_timeout` is `pause`. Not supported when
- `keep_memory` is `False` (a filesystem-only snapshot must be resumed
- explicitly via `connect()`).
+ Whether activity should cause the sandbox to resume when paused. Leave unset
+ to let the API pick the behavior. Set `False` to opt out explicitly and keep
+ auto-resume off even if the API's default changes. Can be `True` only when
+ `on_timeout` is `pause`. Not supported when `keep_memory` is `False`
+ (a filesystem-only snapshot must be resumed explicitly via `connect()`).
"""
@@ -795,7 +796,7 @@ class SandboxLifecycleBody:
auto_pause: Union[Unset, bool]
auto_pause_memory: Union[Unset, bool]
- auto_resume: ClientSandboxAutoResumeConfig
+ auto_resume: Union[Unset, ClientSandboxAutoResumeConfig]
def build_lifecycle_config(
@@ -841,7 +842,7 @@ def build_lifecycle_config(
# actually provided.
if keep_memory is None:
keep_memory = True
- auto_resume = lifecycle.get("auto_resume", False) if lifecycle else False
+ auto_resume = lifecycle.get("auto_resume") if lifecycle else None
if auto_resume and on_timeout != "pause":
raise InvalidArgumentException(
@@ -860,7 +861,11 @@ def build_lifecycle_config(
auto_pause_memory=(
keep_memory if on_timeout == "pause" and keep_memory_provided else UNSET
),
- auto_resume=ClientSandboxAutoResumeConfig(enabled=auto_resume),
+ auto_resume=(
+ ClientSandboxAutoResumeConfig(enabled=auto_resume)
+ if auto_resume is not None
+ else UNSET
+ ),
)
diff --git a/packages/python-sdk/e2b/sandbox_async/main.py b/packages/python-sdk/e2b/sandbox_async/main.py
index 67121bf67..7e8cb3aa0 100644
--- a/packages/python-sdk/e2b/sandbox_async/main.py
+++ b/packages/python-sdk/e2b/sandbox_async/main.py
@@ -196,7 +196,7 @@ class AsyncSandbox(SandboxApi):
:param mcp: MCP server to enable in the sandbox
:param network: Sandbox network configuration. ``allow_out``/``deny_out`` may also be a callable receiving a :class:`SandboxNetworkSelectorContext` (``ctx.all_traffic``, ``ctx.rules``) and returning a list of strings. Per-host transform rules are nested under ``network.rules``; a rule's ``transform`` may be a callable receiving a :class:`SandboxNetworkTransformContext` of placeholder strings (``ctx.iam.tokens[name]``).
:param iam: Sandbox workload identity configuration. A non-empty ``tokens`` map enables workload identity for the sandbox; token definitions can be created with :meth:`Secret.iam_token`. Example: ``{"tokens": {"aws": Secret.iam_token(audience="sts.amazonaws.com", token_type="JWT-SVID")}}``. Registered tokens are exposed to ``network.rules`` ``transform`` callables as ``ctx.iam.tokens[name]`` placeholders, which the egress proxy resolves per request
- :param lifecycle: Sandbox lifecycle configuration — ``on_timeout``: ``"kill"`` or ``"pause"`` (omitted from the request when unset, leaving the API's default, currently ``"kill"``, in effect), or an object ``{"action": "pause"|"kill", "keep_memory": bool}`` where ``keep_memory`` set to ``False`` makes a timeout auto-pause filesystem-only (cold-boots on resume; cannot be combined with ``auto_resume``); an omitted ``keep_memory`` leaves the snapshot kind to the API; ``auto_resume``: ``False`` (default) or ``True`` (only when ``on_timeout`` action is ``"pause"``). Example: ``{"on_timeout": {"action": "pause", "keep_memory": False}}``
+ :param lifecycle: Sandbox lifecycle configuration — ``on_timeout``: ``"kill"`` or ``"pause"`` (omitted from the request when unset, leaving the API's default, currently ``"kill"``, in effect), or an object ``{"action": "pause"|"kill", "keep_memory": bool}`` where ``keep_memory`` set to ``False`` makes a timeout auto-pause filesystem-only (cold-boots on resume; cannot be combined with ``auto_resume``); an omitted ``keep_memory`` leaves the snapshot kind to the API; ``auto_resume``: leave unset to let the API pick the behavior, set ``False`` to opt out explicitly, or ``True`` (only when ``on_timeout`` action is ``"pause"``). Example: ``{"on_timeout": {"action": "pause", "keep_memory": False}}``
:param volume_mounts: Dictionary mapping mount paths to AsyncVolume instances or volume names
:param logger: Logger used for request and response logging for this sandbox. Accepts any standard library `logging.Logger`. When omitted, no request/response logging is emitted.
diff --git a/packages/python-sdk/e2b/sandbox_sync/main.py b/packages/python-sdk/e2b/sandbox_sync/main.py
index 03a11dc34..d831b44cf 100644
--- a/packages/python-sdk/e2b/sandbox_sync/main.py
+++ b/packages/python-sdk/e2b/sandbox_sync/main.py
@@ -192,7 +192,7 @@ class Sandbox(SandboxApi):
:param mcp: MCP server to enable in the sandbox
:param network: Sandbox network configuration. ``allow_out``/``deny_out`` may also be a callable receiving a :class:`SandboxNetworkSelectorContext` (``ctx.all_traffic``, ``ctx.rules``) and returning a list of strings. Per-host transform rules are nested under ``network.rules``; a rule's ``transform`` may be a callable receiving a :class:`SandboxNetworkTransformContext` of placeholder strings (``ctx.iam.tokens[name]``).
:param iam: Sandbox workload identity configuration. A non-empty ``tokens`` map enables workload identity for the sandbox; token definitions can be created with :meth:`Secret.iam_token`. Example: ``{"tokens": {"aws": Secret.iam_token(audience="sts.amazonaws.com", token_type="JWT-SVID")}}``. Registered tokens are exposed to ``network.rules`` ``transform`` callables as ``ctx.iam.tokens[name]`` placeholders, which the egress proxy resolves per request
- :param lifecycle: Sandbox lifecycle configuration — ``on_timeout``: ``"kill"`` or ``"pause"`` (omitted from the request when unset, leaving the API's default, currently ``"kill"``, in effect), or an object ``{"action": "pause"|"kill", "keep_memory": bool}`` where ``keep_memory`` set to ``False`` makes a timeout auto-pause filesystem-only (cold-boots on resume; cannot be combined with ``auto_resume``); an omitted ``keep_memory`` leaves the snapshot kind to the API; ``auto_resume``: ``False`` (default) or ``True`` (only when ``on_timeout`` action is ``"pause"``). Example: ``{"on_timeout": {"action": "pause", "keep_memory": False}}``
+ :param lifecycle: Sandbox lifecycle configuration — ``on_timeout``: ``"kill"`` or ``"pause"`` (omitted from the request when unset, leaving the API's default, currently ``"kill"``, in effect), or an object ``{"action": "pause"|"kill", "keep_memory": bool}`` where ``keep_memory`` set to ``False`` makes a timeout auto-pause filesystem-only (cold-boots on resume; cannot be combined with ``auto_resume``); an omitted ``keep_memory`` leaves the snapshot kind to the API; ``auto_resume``: leave unset to let the API pick the behavior, set ``False`` to opt out explicitly, or ``True`` (only when ``on_timeout`` action is ``"pause"``). Example: ``{"on_timeout": {"action": "pause", "keep_memory": False}}``
:param volume_mounts: Dictionary mapping mount paths to Volume instances or volume names
:param logger: Logger used for request and response logging for this sandbox. Accepts any standard library `logging.Logger`. When omitted, no request/response logging is emitted.
diff --git a/packages/python-sdk/tests/shared/sandbox/test_lifecycle_request.py b/packages/python-sdk/tests/shared/sandbox/test_lifecycle_request.py
index 8446809da..e52bab1eb 100644
--- a/packages/python-sdk/tests/shared/sandbox/test_lifecycle_request.py
+++ b/packages/python-sdk/tests/shared/sandbox/test_lifecycle_request.py
@@ -145,3 +145,51 @@ async def test_async_create_rejects_auto_resume_without_a_timeout_action(
):
with pytest.raises(InvalidArgumentException):
await AsyncSandbox.create(api_key=test_api_key, lifecycle=lifecycle)
+
+
+# `None` expects autoResume to be absent from the payload: an unconfigured
+# preference is not an explicit opt-out, so the API keeps ownership of the
+# default instead of receiving {"enabled": False}.
+AUTO_RESUME_CASES = [
+ pytest.param(None, None, id="no-lifecycle"),
+ pytest.param({"on_timeout": "pause"}, None, id="only-on-timeout"),
+ pytest.param(
+ {"on_timeout": "pause", "auto_resume": False},
+ {"enabled": False},
+ id="explicit-false",
+ ),
+ pytest.param(
+ {"on_timeout": "pause", "auto_resume": True},
+ {"enabled": True},
+ id="explicit-true",
+ ),
+ pytest.param(
+ cast(Any, {"on_timeout": "pause", "auto_resume": None}),
+ None,
+ id="explicit-none",
+ ),
+]
+
+
[email protected]("lifecycle, auto_resume", AUTO_RESUME_CASES)
+def test_create_sends_auto_resume_only_when_configured(
+ monkeypatch, test_api_key, lifecycle, auto_resume
+):
+ body = _sync_request_body(monkeypatch, test_api_key, lifecycle)
+
+ if auto_resume is None:
+ assert "autoResume" not in body
+ else:
+ assert body["autoResume"] == auto_resume
+
+
[email protected]("lifecycle, auto_resume", AUTO_RESUME_CASES)
+async def test_async_create_sends_auto_resume_only_when_configured(
+ monkeypatch, test_api_key, lifecycle, auto_resume
+):
+ body = await _async_request_body(monkeypatch, test_api_key, lifecycle)
+
+ if auto_resume is None:
+ assert "autoResume" not in body
+ else:
+ assert body["autoResume"] == auto_resume