Filesystem-only snapshots

When you pause a sandbox, E2B saves a snapshot you can resume later. By default that snapshot includes both the filesystem and the memory, so resuming restores the sandbox exactly as it was — running processes and in-memory state included. A filesystem-only snapshot persists only the filesystem. There is no memory snapshot, so resuming reboots the sandbox from its disk: the files on disk survive, but RAM and running processes do not.

Full vs. filesystem-only

	Full snapshot (default)	Filesystem-only snapshot
Filesystem (disk)	Preserved	Preserved
Memory (RAM)	Preserved	Disposed
Running processes	Restored	Terminated (reboot)
In-memory state (variables, caches)	Restored	Discarded (reboot)
Resume behavior	Restored in place	Reboot from disk
Speed	Baseline	Faster

Network connections to clients outside the sandbox drop when it pauses — in both cases — and must be re-established on resume (see Persistence). The in-sandbox difference: a full snapshot keeps the process running so it can serve again immediately, while a filesystem-only snapshot reboots, so the service must be restarted first.

Use a filesystem-only snapshot when you only care about the data on disk and don’t need running processes restored — for example, persisting a workspace’s files between sessions, or checkpointing build/scratch state. The snapshot is lighter to store because there’s no memory image, at the cost of a reboot on resume.

Pause filesystem-only

Pass keepMemory: false (JavaScript) / keep_memory=False (Python) to pause(). The filesystem is saved; memory is dropped.

import { Sandbox } from 'e2b'

const sbx = await Sandbox.create()

// Save only the filesystem — resuming will reboot the sandbox
await sbx.pause({ keepMemory: false })

// Resume: the sandbox reboots from disk (files survive, processes do not)
const sameSbx = await sbx.connect()

from e2b import Sandbox

sbx = Sandbox.create()

# Save only the filesystem — resuming will reboot the sandbox
sbx.pause(keep_memory=False)

# Resume: the sandbox reboots from disk (files survive, processes do not)
same_sbx = sbx.connect()

keepMemory / keep_memory defaults to true, so omitting it (or calling pause()) takes a full memory snapshot — see Persistence. keepMemory is a per-pause choice, not a sandbox-wide mode. Pausing once with keepMemory: false / keep_memory=False does not lock the sandbox into filesystem-only: after you resume, the next pause() takes a full memory snapshot again unless you pass keepMemory: false / keep_memory=False once more.

Auto-pause filesystem-only

You can also make the timeout-driven auto-pause filesystem-only. Set onTimeout / on_timeout to the object form and include keepMemory / keep_memory:

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create({
  lifecycle: {
    onTimeout: { action: 'pause', keepMemory: false },
  },
})

from e2b import Sandbox

sandbox = Sandbox.create(
    lifecycle={
        "on_timeout": {"action": "pause", "keep_memory": False},
    },
)

When this sandbox times out, it auto-pauses filesystem-only; the next explicit resume reboots it. See Auto-resume on request for the full lifecycle reference.

Type safety and validation

keepMemory / keep_memory only governs a pause action, so the SDK rejects nonsensical combinations:

It cannot be set when the action is kill. In TypeScript this is a compile-time type error (the onTimeout object is a discriminated union on action); in Python it raises InvalidArgumentException.
It cannot be combined with auto-resume. A filesystem-only snapshot can’t be woken by inbound traffic (auto-resume restores the running process from memory, which a filesystem-only snapshot doesn’t have), so it must be resumed explicitly with connect(). Setting keepMemory: false / keep_memory=False together with autoResume: true / auto_resume=True is rejected client-side.

A filesystem-only snapshot is not compatible with auto-resume. Resume it explicitly via connect() — it will not wake on traffic.

What changes on resume

Resuming a filesystem-only snapshot is a reboot, so it takes roughly a fresh boot rather than the near-instant in-place memory restore. Any service running inside the sandbox must be restarted after resume, and clients must reconnect. Because resume is a reboot, anything that lived only in memory is gone, while everything written to disk persists. The example below writes a file and starts a background process, pauses filesystem-only, then resumes: the file is still there, but the process is not.

import { Sandbox } from 'e2b'

const sbx = await Sandbox.create()

await sbx.files.write('/home/user/data.txt', 'survives the reboot')
const cmd = await sbx.commands.run('sleep 600', { background: true })

await sbx.pause({ keepMemory: false })
const resumed = await sbx.connect()

// File on disk survives the reboot
const content = await resumed.files.read('/home/user/data.txt')
console.log(content) // "survives the reboot"

// The background process is gone — the sandbox rebooted
const check = await resumed.commands.run(`kill -0 ${cmd.pid}`, { background: false })
console.log(check.exitCode !== 0) // true — process no longer running

from e2b import Sandbox

sbx = Sandbox.create()

sbx.files.write("/home/user/data.txt", "survives the reboot")
cmd = sbx.commands.run("sleep 600", background=True)

sbx.pause(keep_memory=False)
resumed = sbx.connect()

# File on disk survives the reboot
content = resumed.files.read("/home/user/data.txt")
print(content)  # "survives the reboot"

# The background process is gone — the sandbox rebooted
check = resumed.commands.run(f"kill -0 {cmd.pid}", background=False)
print(check.exit_code != 0)  # True — process no longer running

Picking up envd updates

envd is E2B’s in-sandbox daemon. The envd version a sandbox runs is pinned by its template, so by default a long-lived paused sandbox stays on that version for its whole lifetime and does not pick up later envd fixes and improvements. A filesystem-only resume cold-boots the sandbox from disk, and that reboot can bring the sandbox up on a newer envd than its template shipped. The filesystem is untouched. This is how a long-lived sandbox can adopt envd improvements - for example around memory management, stability, and speed - without losing the data on disk. To move an existing sandbox onto a newer envd:

Resume the sandbox.
Pause it filesystem-only with keepMemory: false (JavaScript) / keep_memory=False (Python).
Resume it again. This cold boot can bring it up on a newer envd.

A sandbox has to be resumable to use this flow. A sandbox whose snapshot already fails to resume cannot be paused filesystem-only in the first place, so it cannot be upgraded this way.

Sandbox persistence — full (memory + filesystem) pause and resume.
Auto-resume on request — the full lifecycle configuration reference.
Connect to a sandbox — resume a paused sandbox explicitly.

​Full vs. filesystem-only

​Pause filesystem-only

​Auto-pause filesystem-only

​Type safety and validation

​What changes on resume

​Picking up envd updates

​Related

Full vs. filesystem-only

Pause filesystem-only

Auto-pause filesystem-only

Type safety and validation

What changes on resume

Picking up envd updates

Related