Skip to content

armgit / E2B

Public Imported from GitHub
0

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

feat(sdk): filesystem-only snapshots (pause memory:false) (#1465)

Babis Chalioscb5a3870b6a3
diff --git a/.changeset/filesystem-only-pause.md b/.changeset/filesystem-only-pause.md
new file mode 100644
index 000000000..a530c7daa
--- /dev/null
+++ b/.changeset/filesystem-only-pause.md
@@ -0,0 +1,22 @@
+---
+"e2b": minor
+"@e2b/python-sdk": minor
+---
+
+Add a `keepMemory` (`keep_memory` in Python) option to `pause` for
+filesystem-only snapshots.
+
+When `keepMemory` is `false`, pausing drops the in-memory state and captures
+only the filesystem (no memory snapshot); resuming such a snapshot cold-boots
+(reboots) the sandbox from disk, losing running processes and open connections.
+Defaults to `true` (full memory snapshot), so existing callers are unaffected.
+
+```python
+# Python
+sbx.pause(keep_memory=False) # filesystem-only snapshot
+```
+
+```ts
+// JS/TS
+await sandbox.pause({ keepMemory: false }) // filesystem-only snapshot
+```
diff --git a/packages/js-sdk/src/api/schema.gen.ts b/packages/js-sdk/src/api/schema.gen.ts
index cf9751a40..060944176 100644
--- a/packages/js-sdk/src/api/schema.gen.ts
+++ b/packages/js-sdk/src/api/schema.gen.ts
@@ -350,7 +350,11 @@ export interface paths {
};
cookie?: never;
};
- requestBody?: never;
+ requestBody?: {
+ content: {
+ "application/json": components["schemas"]["SandboxPauseRequest"];
+ };
+ };
responses: {
/** @description The sandbox was paused successfully and can be resumed */
204: {
@@ -2379,6 +2383,13 @@ export interface components {
* @enum {string}
*/
SandboxOnTimeout: "kill" | "pause";
+ SandboxPauseRequest: {
+ /**
+ * @description Whether to capture a full memory snapshot. When false, only the filesystem is persisted and resuming the sandbox cold-boots (reboots) it from disk, losing in-memory state, running processes, and open connections. Resume it with an explicit request (connect or resume); auto-resume, which can be triggered by arbitrary traffic, refuses such a sandbox. Defaults to true.
+ * @default true
+ */
+ memory?: boolean;
+ };
/**
* @description State of the sandbox
* @enum {string}
diff --git a/packages/js-sdk/src/index.ts b/packages/js-sdk/src/index.ts
index c7a80f8fc..21ad4589d 100644
--- a/packages/js-sdk/src/index.ts
+++ b/packages/js-sdk/src/index.ts
@@ -53,6 +53,7 @@ export type {
SandboxApiOpts,
SandboxConnectOpts,
SandboxMetricsOpts,
+ SandboxPauseOpts,
SandboxState,
SandboxListOpts,
SandboxPaginator,
diff --git a/packages/js-sdk/src/sandbox/index.ts b/packages/js-sdk/src/sandbox/index.ts
index e330ccaac..49415cb2c 100644
--- a/packages/js-sdk/src/sandbox/index.ts
+++ b/packages/js-sdk/src/sandbox/index.ts
@@ -25,6 +25,7 @@ import {
SnapshotInfo,
SnapshotPaginator,
CreateSnapshotOpts,
+ SandboxPauseOpts,
} from './sandboxApi'
import { getSignature } from './signature'
import { compareVersions } from 'compare-versions'
@@ -534,24 +535,31 @@ export class Sandbox extends SandboxApi {
/**
* Pause a sandbox by its ID.
*
- * @param opts connection options.
+ * @param opts connection options, plus `keepMemory` to control the snapshot
+ * kind. When `opts.keepMemory` is `false`, the in-memory state is dropped and
+ * only the filesystem is persisted (a filesystem-only snapshot); resuming such
+ * a sandbox cold-boots (reboots) it from disk, losing running processes and
+ * open connections. Defaults to `true` (full memory snapshot).
*
- * @returns sandbox ID that can be used to resume the sandbox.
+ * @returns `true` if the sandbox got paused, `false` if the sandbox was already paused.
*
* @example
* ```ts
* const sandbox = await Sandbox.create()
* await sandbox.pause()
+ *
+ * // filesystem-only snapshot (resume reboots the sandbox)
+ * await sandbox.pause({ keepMemory: false })
* ```
*/
- async pause(opts?: ConnectionOpts): Promise<boolean> {
+ async pause(opts?: SandboxPauseOpts): Promise<boolean> {
return await SandboxApi.pause(this.sandboxId, this.resolveApiOpts(opts))
}
/**
* @deprecated Use {@link Sandbox.pause} instead.
*/
- async betaPause(opts?: ConnectionOpts): Promise<boolean> {
+ async betaPause(opts?: SandboxPauseOpts): Promise<boolean> {
return await SandboxApi.betaPause(this.sandboxId, this.resolveApiOpts(opts))
}
diff --git a/packages/js-sdk/src/sandbox/sandboxApi.ts b/packages/js-sdk/src/sandbox/sandboxApi.ts
index d4e1fc763..4fba4bdc0 100644
--- a/packages/js-sdk/src/sandbox/sandboxApi.ts
+++ b/packages/js-sdk/src/sandbox/sandboxApi.ts
@@ -242,6 +242,22 @@ export interface SandboxApiOpts
>
> {}
+/**
+ * Options for pausing a sandbox.
+ */
+export interface SandboxPauseOpts extends SandboxApiOpts {
+ /**
+ * Whether to keep a full memory snapshot.
+ *
+ * When `false`, the in-memory state is dropped and only the filesystem is
+ * persisted (a filesystem-only snapshot); resuming such a sandbox cold-boots
+ * (reboots) it from disk, losing running processes and open connections.
+ *
+ * @default true
+ */
+ keepMemory?: boolean
+}
+
/**
* Options for creating a new Sandbox.
*/
@@ -915,13 +931,13 @@ export class SandboxApi {
* Pause the sandbox specified by sandbox ID.
*
* @param sandboxId sandbox ID.
- * @param opts connection options.
+ * @param opts pause options, including `keepMemory` and connection options.
*
* @returns `true` if the sandbox got paused, `false` if the sandbox was already paused.
*/
static async pause(
sandboxId: string,
- opts?: SandboxApiOpts
+ opts?: SandboxPauseOpts
): Promise<boolean> {
const config = new ConnectionConfig(opts)
const client = new ApiClient(config)
@@ -932,6 +948,9 @@ export class SandboxApi {
sandboxID: sandboxId,
},
},
+ body: {
+ memory: opts?.keepMemory ?? true,
+ },
signal: config.getSignal(opts?.requestTimeoutMs, opts?.signal),
})
@@ -957,7 +976,7 @@ export class SandboxApi {
*/
static async betaPause(
sandboxId: string,
- opts?: SandboxApiOpts
+ opts?: SandboxPauseOpts
): Promise<boolean> {
return this.pause(sandboxId, opts)
}
diff --git a/packages/js-sdk/tests/sandbox/snapshot.test.ts b/packages/js-sdk/tests/sandbox/snapshot.test.ts
index 28d2cfc58..af88640ef 100644
--- a/packages/js-sdk/tests/sandbox/snapshot.test.ts
+++ b/packages/js-sdk/tests/sandbox/snapshot.test.ts
@@ -162,3 +162,42 @@ sandboxTest.skipIf(isDebug)(
assert.equal(response2.status, 200)
}
)
+
+sandboxTest.skipIf(isDebug)(
+ 'filesystem-only pause reboots on resume but keeps the filesystem',
+ async ({ sandbox }) => {
+ // Absolute path: a cold boot may not restore the template's default
+ // user/cwd, so a relative path could resolve differently after resume.
+ const filename = '/home/user/fs_only_snapshot.txt'
+ const content = 'This is a filesystem-only snapshot test file.'
+
+ await sandbox.files.write(filename, content)
+
+ // Kernel boot id before the pause; it changes only across a real (cold) boot.
+ const bootBefore = (
+ await sandbox.files.read('/proc/sys/kernel/random/boot_id')
+ ).trim()
+
+ // Filesystem-only snapshot: no memory is captured, so resuming cold-boots.
+ await sandbox.pause({ keepMemory: false })
+ assert.isFalse(await sandbox.isRunning())
+
+ // Resume the paused sandbox; a filesystem-only pause keeps no memory, so
+ // connect() cold-boots (reboots) it. connect() returns the same handle, and
+ // its credentials stay valid across the resume (the backend re-binds the
+ // same envd access token on the cold boot).
+ const resumedSandbox = await sandbox.connect()
+ assert.equal(resumedSandbox.sandboxId, sandbox.sandboxId)
+ assert.isTrue(await resumedSandbox.isRunning())
+
+ // The filesystem survives the cold boot.
+ assert.isTrue(await resumedSandbox.files.exists(filename))
+ assert.equal(await resumedSandbox.files.read(filename), content)
+
+ // A fresh boot id proves the guest rebooted rather than restoring memory.
+ const bootAfter = (
+ await resumedSandbox.files.read('/proc/sys/kernel/random/boot_id')
+ ).trim()
+ assert.notEqual(bootAfter, bootBefore)
+ }
+)
diff --git a/packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes_sandbox_id_pause.py b/packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes_sandbox_id_pause.py
index f1c55c62f..f2931d26c 100644
--- a/packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes_sandbox_id_pause.py
+++ b/packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes_sandbox_id_pause.py
@@ -6,17 +6,27 @@ import httpx
from ... import errors
from ...client import AuthenticatedClient, Client
from ...models.error import Error
+from ...models.sandbox_pause_request import SandboxPauseRequest
from ...types import Response
def _get_kwargs(
sandbox_id: str,
+ *,
+ body: SandboxPauseRequest,
) -> dict[str, Any]:
+ headers: dict[str, Any] = {}
+
_kwargs: dict[str, Any] = {
"method": "post",
"url": f"/sandboxes/{sandbox_id}/pause",
}
+ _kwargs["json"] = body.to_dict()
+
+ headers["Content-Type"] = "application/json"
+
+ _kwargs["headers"] = headers
return _kwargs
@@ -63,11 +73,13 @@ def sync_detailed(
sandbox_id: str,
*,
client: AuthenticatedClient,
+ body: SandboxPauseRequest,
) -> Response[Union[Any, Error]]:
"""Pause the sandbox
Args:
sandbox_id (str):
+ body (SandboxPauseRequest):
Raises:
errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -79,6 +91,7 @@ def sync_detailed(
kwargs = _get_kwargs(
sandbox_id=sandbox_id,
+ body=body,
)
response = client.get_httpx_client().request(
@@ -92,11 +105,13 @@ def sync(
sandbox_id: str,
*,
client: AuthenticatedClient,
+ body: SandboxPauseRequest,
) -> Optional[Union[Any, Error]]:
"""Pause the sandbox
Args:
sandbox_id (str):
+ body (SandboxPauseRequest):
Raises:
errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -109,6 +124,7 @@ def sync(
return sync_detailed(
sandbox_id=sandbox_id,
client=client,
+ body=body,
).parsed
@@ -116,11 +132,13 @@ async def asyncio_detailed(
sandbox_id: str,
*,
client: AuthenticatedClient,
+ body: SandboxPauseRequest,
) -> Response[Union[Any, Error]]:
"""Pause the sandbox
Args:
sandbox_id (str):
+ body (SandboxPauseRequest):
Raises:
errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -132,6 +150,7 @@ async def asyncio_detailed(
kwargs = _get_kwargs(
sandbox_id=sandbox_id,
+ body=body,
)
response = await client.get_async_httpx_client().request(**kwargs)
@@ -143,11 +162,13 @@ async def asyncio(
sandbox_id: str,
*,
client: AuthenticatedClient,
+ body: SandboxPauseRequest,
) -> Optional[Union[Any, Error]]:
"""Pause the sandbox
Args:
sandbox_id (str):
+ body (SandboxPauseRequest):
Raises:
errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -161,5 +182,6 @@ async def asyncio(
await asyncio_detailed(
sandbox_id=sandbox_id,
client=client,
+ body=body,
)
).parsed
diff --git a/packages/python-sdk/e2b/api/client/models/__init__.py b/packages/python-sdk/e2b/api/client/models/__init__.py
index aa5d633ff..1f18254d1 100644
--- a/packages/python-sdk/e2b/api/client/models/__init__.py
+++ b/packages/python-sdk/e2b/api/client/models/__init__.py
@@ -61,6 +61,7 @@ from .sandbox_network_transform_headers import SandboxNetworkTransformHeaders
from .sandbox_network_update_config import SandboxNetworkUpdateConfig
from .sandbox_network_update_config_rules import SandboxNetworkUpdateConfigRules
from .sandbox_on_timeout import SandboxOnTimeout
+from .sandbox_pause_request import SandboxPauseRequest
from .sandbox_state import SandboxState
from .sandbox_volume_mount import SandboxVolumeMount
from .sandboxes_with_metrics import SandboxesWithMetrics
@@ -151,6 +152,7 @@ __all__ = (
"SandboxNetworkUpdateConfig",
"SandboxNetworkUpdateConfigRules",
"SandboxOnTimeout",
+ "SandboxPauseRequest",
"SandboxState",
"SandboxVolumeMount",
"SnapshotInfo",
diff --git a/packages/python-sdk/e2b/api/client/models/sandbox_pause_request.py b/packages/python-sdk/e2b/api/client/models/sandbox_pause_request.py
new file mode 100644
index 000000000..0f36b2eb8
--- /dev/null
+++ b/packages/python-sdk/e2b/api/client/models/sandbox_pause_request.py
@@ -0,0 +1,62 @@
+from collections.abc import Mapping
+from typing import Any, TypeVar, Union
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+
+from ..types import UNSET, Unset
+
+T = TypeVar("T", bound="SandboxPauseRequest")
+
+
+@_attrs_define
+class SandboxPauseRequest:
+ """
+ Attributes:
+ memory (Union[Unset, bool]): Whether to capture a full memory snapshot. When false, only the filesystem is
+ persisted and resuming the sandbox cold-boots (reboots) it from disk, losing in-memory state, running processes,
+ and open connections. Resume it with an explicit request (connect or resume); auto-resume, which can be
+ triggered by arbitrary traffic, refuses such a sandbox. Defaults to true. Default: True.
+ """
+
+ memory: Union[Unset, bool] = True
+ additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+ def to_dict(self) -> dict[str, Any]:
+ memory = self.memory
+
+ field_dict: dict[str, Any] = {}
+ field_dict.update(self.additional_properties)
+ field_dict.update({})
+ if memory is not UNSET:
+ field_dict["memory"] = memory
+
+ return field_dict
+
+ @classmethod
+ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
+ d = dict(src_dict)
+ memory = d.pop("memory", UNSET)
+
+ sandbox_pause_request = cls(
+ memory=memory,
+ )
+
+ sandbox_pause_request.additional_properties = d
+ return sandbox_pause_request
+
+ @property
+ def additional_keys(self) -> list[str]:
+ return list(self.additional_properties.keys())
+
+ def __getitem__(self, key: str) -> Any:
+ return self.additional_properties[key]
+
+ def __setitem__(self, key: str, value: Any) -> None:
+ self.additional_properties[key] = value
+
+ def __delitem__(self, key: str) -> None:
+ del self.additional_properties[key]
+
+ def __contains__(self, key: str) -> bool:
+ return key in self.additional_properties
diff --git a/packages/python-sdk/e2b/sandbox_async/main.py b/packages/python-sdk/e2b/sandbox_async/main.py
index 6f9f8973e..4b688ab2f 100644
--- a/packages/python-sdk/e2b/sandbox_async/main.py
+++ b/packages/python-sdk/e2b/sandbox_async/main.py
@@ -616,11 +616,14 @@ class AsyncSandbox(SandboxApi):
@overload
async def pause(
self,
+ keep_memory: bool = True,
**opts: Unpack[ApiParams],
) -> bool:
"""
Pause the sandbox.
+ :param keep_memory: When `False`, the in-memory state is dropped and only the filesystem is persisted (no memory snapshot); resuming such a sandbox cold-boots (reboots) it from disk. Defaults to `True`.
+
:return: `True` if the sandbox got paused, `False` if the sandbox was already paused
"""
...
@@ -629,12 +632,14 @@ class AsyncSandbox(SandboxApi):
@staticmethod
async def pause(
sandbox_id: str,
+ keep_memory: bool = True,
**opts: Unpack[ApiParams],
) -> bool:
"""
Pause the sandbox specified by sandbox ID.
:param sandbox_id: Sandbox ID
+ :param keep_memory: When `False`, the in-memory state is dropped and only the filesystem is persisted (no memory snapshot); resuming such a sandbox cold-boots (reboots) it from disk. Defaults to `True`.
:return: `True` if the sandbox got paused, `False` if the sandbox was already paused
"""
@@ -643,22 +648,27 @@ class AsyncSandbox(SandboxApi):
@class_method_variant("_cls_pause")
async def pause(
self,
+ keep_memory: bool = True,
**opts: Unpack[ApiParams],
) -> bool:
"""
Pause the sandbox.
+ :param keep_memory: When `False`, the in-memory state is dropped and only the filesystem is persisted (no memory snapshot); resuming such a sandbox cold-boots (reboots) it from disk, losing running processes and open connections. Defaults to `True` (full memory snapshot).
+
:return: `True` if the sandbox got paused, `False` if the sandbox was already paused
"""
return await SandboxApi._cls_pause(
sandbox_id=self.sandbox_id,
+ keep_memory=keep_memory,
**self.connection_config.get_api_params(**opts),
)
@overload
async def beta_pause(
self,
+ keep_memory: bool = True,
**opts: Unpack[ApiParams],
) -> bool: ...
@@ -666,12 +676,14 @@ class AsyncSandbox(SandboxApi):
@staticmethod
async def beta_pause(
sandbox_id: str,
+ keep_memory: bool = True,
**opts: Unpack[ApiParams],
) -> bool: ...
@class_method_variant("_cls_pause")
async def beta_pause(
self,
+ keep_memory: bool = True,
**opts: Unpack[ApiParams],
) -> bool:
"""
@@ -679,7 +691,7 @@ class AsyncSandbox(SandboxApi):
:return: `True` if the sandbox got paused, `False` if the sandbox was already paused
"""
- return await self.pause(**opts)
+ return await self.pause(keep_memory=keep_memory, **opts)
@overload
async def create_snapshot(
diff --git a/packages/python-sdk/e2b/sandbox_async/sandbox_api.py b/packages/python-sdk/e2b/sandbox_async/sandbox_api.py
index 40611e784..66758ba95 100644
--- a/packages/python-sdk/e2b/sandbox_async/sandbox_api.py
+++ b/packages/python-sdk/e2b/sandbox_async/sandbox_api.py
@@ -25,6 +25,7 @@ from e2b.api.client.models import (
PostSandboxesSandboxIDTimeoutBody,
SandboxAutoResumeConfig,
SandboxNetworkConfig,
+ SandboxPauseRequest,
SandboxVolumeMount as SandboxVolumeMountAPI,
)
from e2b.api.client.types import UNSET
@@ -383,6 +384,7 @@ class SandboxApi(SandboxBase):
async def _cls_pause(
cls,
sandbox_id: str,
+ keep_memory: bool = True,
**opts: Unpack[ApiParams],
) -> bool:
config = ConnectionConfig(**opts)
@@ -391,6 +393,7 @@ class SandboxApi(SandboxBase):
res = await post_sandboxes_sandbox_id_pause.asyncio_detailed(
sandbox_id,
client=api_client,
+ body=SandboxPauseRequest(memory=keep_memory),
)
if res.status_code == 404:
diff --git a/packages/python-sdk/e2b/sandbox_sync/main.py b/packages/python-sdk/e2b/sandbox_sync/main.py
index 97485b694..12c2c5415 100644
--- a/packages/python-sdk/e2b/sandbox_sync/main.py
+++ b/packages/python-sdk/e2b/sandbox_sync/main.py
@@ -608,11 +608,14 @@ class Sandbox(SandboxApi):
@overload
def pause(
self,
+ keep_memory: bool = True,
**opts: Unpack[ApiParams],
) -> bool:
"""
Pause the sandbox.
+ :param keep_memory: When `False`, the in-memory state is dropped and only the filesystem is persisted (no memory snapshot); resuming such a sandbox cold-boots (reboots) it from disk. Defaults to `True`.
+
:return: `True` if the sandbox got paused, `False` if the sandbox was already paused
"""
...
@@ -621,12 +624,14 @@ class Sandbox(SandboxApi):
@staticmethod
def pause(
sandbox_id: str,
+ keep_memory: bool = True,
**opts: Unpack[ApiParams],
) -> bool:
"""
Pause the sandbox specified by sandbox ID.
:param sandbox_id: Sandbox ID
+ :param keep_memory: When `False`, the in-memory state is dropped and only the filesystem is persisted (no memory snapshot); resuming such a sandbox cold-boots (reboots) it from disk. Defaults to `True`.
:return: `True` if the sandbox got paused, `False` if the sandbox was already paused
"""
@@ -635,22 +640,27 @@ class Sandbox(SandboxApi):
@class_method_variant("_cls_pause")
def pause(
self,
+ keep_memory: bool = True,
**opts: Unpack[ApiParams],
) -> bool:
"""
Pause the sandbox.
+ :param keep_memory: When `False`, the in-memory state is dropped and only the filesystem is persisted (no memory snapshot); resuming such a sandbox cold-boots (reboots) it from disk, losing running processes and open connections. Defaults to `True` (full memory snapshot).
+
:return: `True` if the sandbox got paused, `False` if the sandbox was already paused
"""
return SandboxApi._cls_pause(
sandbox_id=self.sandbox_id,
+ keep_memory=keep_memory,
**self.connection_config.get_api_params(**opts),
)
@overload
def beta_pause(
self,
+ keep_memory: bool = True,
**opts: Unpack[ApiParams],
) -> bool: ...
@@ -658,12 +668,14 @@ class Sandbox(SandboxApi):
@staticmethod
def beta_pause(
sandbox_id: str,
+ keep_memory: bool = True,
**opts: Unpack[ApiParams],
) -> bool: ...
@class_method_variant("_cls_pause")
def beta_pause(
self,
+ keep_memory: bool = True,
**opts: Unpack[ApiParams],
) -> bool:
"""
@@ -671,7 +683,7 @@ class Sandbox(SandboxApi):
:return: `True` if the sandbox got paused, `False` if the sandbox was already paused
"""
- return self.pause(**opts)
+ return self.pause(keep_memory=keep_memory, **opts)
@overload
def create_snapshot(
diff --git a/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py b/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py
index cff712e89..435f593d4 100644
--- a/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py
+++ b/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py
@@ -25,6 +25,7 @@ from e2b.api.client.models import (
PostSandboxesSandboxIDTimeoutBody,
SandboxAutoResumeConfig,
SandboxNetworkConfig,
+ SandboxPauseRequest,
SandboxVolumeMount as SandboxVolumeMountAPI,
)
from e2b.api.client.types import UNSET
@@ -422,6 +423,7 @@ class SandboxApi(SandboxBase):
def _cls_pause(
cls,
sandbox_id: str,
+ keep_memory: bool = True,
**opts: Unpack[ApiParams],
) -> bool:
config = ConnectionConfig(**opts)
@@ -430,6 +432,7 @@ class SandboxApi(SandboxBase):
res = post_sandboxes_sandbox_id_pause.sync_detailed(
sandbox_id,
client=api_client,
+ body=SandboxPauseRequest(memory=keep_memory),
)
if res.status_code == 404:
diff --git a/packages/python-sdk/tests/async/sandbox_async/test_snapshot_filesystem_only.py b/packages/python-sdk/tests/async/sandbox_async/test_snapshot_filesystem_only.py
new file mode 100644
index 000000000..cdfa597d4
--- /dev/null
+++ b/packages/python-sdk/tests/async/sandbox_async/test_snapshot_filesystem_only.py
@@ -0,0 +1,31 @@
+import pytest
+from e2b import AsyncSandbox
+
+
+async def test_pause_filesystem_only(async_sandbox: AsyncSandbox):
+ # A marker on the persisted rootfs and the kernel boot id before pausing.
+ await async_sandbox.files.write("/home/user/fs-only-marker.txt", "persisted")
+ boot_before = (
+ await async_sandbox.files.read("/proc/sys/kernel/random/boot_id")
+ ).strip()
+
+ # Filesystem-only pause: only the rootfs is persisted, no memory snapshot.
+ assert await async_sandbox.pause(keep_memory=False)
+ assert not await async_sandbox.is_running()
+
+ # Resuming a filesystem-only snapshot cold-boots (reboots) from the rootfs.
+ resumed = await async_sandbox.connect()
+ assert await resumed.is_running()
+ assert resumed.sandbox_id == async_sandbox.sandbox_id
+
+ # connect() returns the same handle, and its credentials stay valid across
+ # the resume (the backend re-binds the same envd access token on the cold
+ # boot). The rootfs survives the reboot...
+ marker = (await resumed.files.read("/home/user/fs-only-marker.txt")).strip()
+ assert marker == "persisted"
+
+ # ...while a fresh kernel boot id proves the guest cold-booted rather than
+ # being restored from a memory snapshot.
+ boot_after = (await resumed.files.read("/proc/sys/kernel/random/boot_id")).strip()
+ assert boot_after != boot_before
diff --git a/packages/python-sdk/tests/sync/sandbox_sync/test_snapshot_filesystem_only.py b/packages/python-sdk/tests/sync/sandbox_sync/test_snapshot_filesystem_only.py
new file mode 100644
index 000000000..0493b9714
--- /dev/null
+++ b/packages/python-sdk/tests/sync/sandbox_sync/test_snapshot_filesystem_only.py
@@ -0,0 +1,29 @@
+import pytest
+from e2b import Sandbox
+
+
+def test_pause_filesystem_only(sandbox: Sandbox):
+ # A marker on the persisted rootfs and the kernel boot id before pausing.
+ sandbox.files.write("/home/user/fs-only-marker.txt", "persisted")
+ boot_before = sandbox.files.read("/proc/sys/kernel/random/boot_id").strip()
+
+ # Filesystem-only pause: only the rootfs is persisted, no memory snapshot.
+ assert sandbox.pause(keep_memory=False)
+ assert not sandbox.is_running()
+
+ # Resuming a filesystem-only snapshot cold-boots (reboots) from the rootfs.
+ resumed = sandbox.connect()
+ assert resumed.is_running()
+ assert resumed.sandbox_id == sandbox.sandbox_id
+
+ # connect() returns the same handle, and its credentials stay valid across
+ # the resume (the backend re-binds the same envd access token on the cold
+ # boot). The rootfs survives the reboot...
+ marker = resumed.files.read("/home/user/fs-only-marker.txt").strip()
+ assert marker == "persisted"
+
+ # ...while a fresh kernel boot id proves the guest cold-booted rather than
+ # being restored from a memory snapshot.
+ boot_after = resumed.files.read("/proc/sys/kernel/random/boot_id").strip()
+ assert boot_after != boot_before
diff --git a/spec/openapi.yml b/spec/openapi.yml
index 5d3a54235..b8c1bb063 100644
--- a/spec/openapi.yml
+++ b/spec/openapi.yml
@@ -725,6 +725,20 @@ components:
deprecated: true
description: Automatically pauses the sandbox after the timeout
+ SandboxPauseRequest:
+ type: object
+ properties:
+ memory:
+ type: boolean
+ default: true
+ description: >-
+ Whether to capture a full memory snapshot. When false, only the
+ filesystem is persisted and resuming the sandbox cold-boots
+ (reboots) it from disk, losing in-memory state, running processes,
+ and open connections. Resume it with an explicit request (connect or
+ resume); auto-resume, which can be triggered by arbitrary traffic,
+ refuses such a sandbox. Defaults to true.
+
ConnectSandbox:
type: object
required:
@@ -2349,6 +2363,12 @@ paths:
AuthProviderTeamAuth: []
parameters:
- $ref: '#/components/parameters/sandboxID'
+ requestBody:
+ required: false
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SandboxPauseRequest'
responses:
'204':
description: The sandbox was paused successfully and can be resumed