Sandbox state transitions
Understanding how sandboxes transition between different states is crucial for managing their lifecycle effectively. Here’s a diagram showing the possible state transitions:State descriptions
- Running: The sandbox is actively running and can execute code. This is the initial state after creation.
- Paused: The sandbox execution is suspended but its state is preserved.
- Snapshotting: The sandbox is briefly paused while a persistent snapshot is being created. It automatically returns to Running. See Snapshots.
- Killed: The sandbox is terminated and all resources are released. This is a terminal state.
Changing sandbox’s state
Pausing sandbox
When you pause a sandbox, both the sandbox’s filesystem and memory state will be saved. This includes all the files in the sandbox’s filesystem and all the running processes, loaded variables, data, etc.mode: 'filesystem' (JavaScript) / mode="filesystem" (Python). The older keepMemory: false / keep_memory=False form is deprecated but still works. See Filesystem-only snapshots.
When a pause is refused
Rolling out. The refusal behavior below is being enabled region by region. Until it reaches your region, a pause in this situation fails with a
500 error instead. ServiceBusyError and ServiceBusyException are available in the JavaScript and Python SDKs (the e2b package) starting with version 2.48.0.503 and the sandbox keeps running with its state intact. Nothing was paused and nothing was lost. The SDKs surface this as ServiceBusyError (JavaScript) / ServiceBusyException (Python), the same error every other 503 from the API raises, for example when there is no capacity to place a new sandbox.
The right reaction is to retry the pause after a short wait, or simply to keep using the sandbox and pause it later:
ServiceBusyError / ServiceBusyException is not a SandboxError / SandboxException, so catch it explicitly.
When the sandbox is not responding
Before taking a snapshot, E2B checks thatenvd, the E2B daemon inside the sandbox, answers a health check. A sandbox whose envd does not answer is usually hung. What the pause does next depends on what you ask for:
Forks and snapshots are refused the same way as a filesystem-only pause.
The default keeps the pause from failing: you get a paused sandbox with its disk and memory saved, but you won’t be able to resume it with its memory. Pass
strict: true (JavaScript) / strict=True (Python) when you would rather keep the memory and retry the pause later than end up with a sandbox that can only reboot. Like a busy node, the refusal surfaces as ServiceBusyError (JavaScript) / ServiceBusyException (Python).
strict needs SDK 2.63.0 or later.
A sandbox paused while it was not responding shows envdUnresponsiveAtPause: true in GET /sandboxes/{sandboxID} and in the list of paused sandboxes. In the SDK (2.63.0 or later), getInfo() returns it as envdUnresponsiveAtPause (JavaScript) and get_info() as envd_unresponsive_at_pause (Python). The field is omitted for a running sandbox and for a snapshot taken while envd answered.
Resuming sandbox
When you resume a sandbox, it will be in the same state it was in when you paused it. This means that all the files in the sandbox’s filesystem will be restored and all the running processes, loaded variables, data, etc. will be restored.When a resume is refused
A sandbox that was paused while it was not responding cannot be resumed with its memory: restoring that memory would bring the hung sandbox back. A plainconnect() is refused with HTTP 409, error code sandbox_snapshot_guest_agent_unresponsive, and this message:
GuestUnresponsiveError in JavaScript and GuestUnresponsiveException in Python, both exported from e2b. Other 409 answers, such as a sandbox that is still being paused, do not raise it. In older SDKs the same refusal is a generic SandboxError (JavaScript) / SandboxException (Python) carrying the message above. The same refusal answers the resume endpoint and auto-resume on traffic. Nothing is consumed: the sandbox stays paused with its snapshot intact.
To get the sandbox back, reboot it: catch the error and connect again with onResume: 'reboot' (JavaScript) / on_resume="reboot" (Python). It boots from its disk, so files written and flushed before the pause are there, while running processes and in-memory state are gone, and writes not flushed before the pause may be lost. This works for every team, with no enablement needed for such a sandbox.
On an SDK between 2.48.0 and 2.62.x you can still reboot the sandbox, but you have to recognize the refusal by its message. Upgrade to 2.63.0 or later to catch it by type.
Once the rebooted sandbox is running, pause it again to record a new, healthy snapshot. If it reaches its timeout without being paused, it reverts to the snapshot you resumed from, and the next plain
connect() is refused again (see Keep a snapshot afterwards).
Listing paused sandboxes
You can list all paused sandboxes by calling theSandbox.list method and supplying the state query parameter.
More information about using the method can be found in List Sandboxes.
Removing paused sandboxes
You can remove paused sandboxes by calling thekill method on the Sandbox instance.
Sandbox’s timeout
When connecting to a sandbox, the timeout is not reset.Sandbox.connect() only ever extends the sandbox’s lifetime - the new expiry is the later of the current expiry and now plus the timeout you pass (default 5 minutes). So a sandbox with 20 minutes left stays at 20 minutes even if you connect with the default timeout, while a sandbox with only 1 minute left is bumped up to 5. To set an exact timeout that can also shorten the remaining lifetime, use setTimeout() / set_timeout() instead.
Auto-pause
Auto-pause is configured in the sandbox lifecycle on create.onTimeout/on_timeout defaults to "kill", meaning the sandbox is terminated when its timeout expires. Set it to "pause" to auto-pause on timeout instead.
sandbox.lifecycle.paused event: pause_mode is filesystem (see lifecycle events).
If the sandbox is not responding when its timeout expires, E2B keeps it running and retries the auto-pause for about two minutes, in case it recovers. If it is still not responding after that, it is paused with its memory anyway and marked, so the next resume has to reboot it.
To make the auto-pause filesystem-only — dropping memory so resume reboots the sandbox — use the object form onTimeout: { action: 'pause', mode: 'filesystem' } (JavaScript) / "on_timeout": {"action": "pause", "mode": "filesystem"} (Python). See Filesystem-only snapshots.
If you call .kill(), the sandbox is permanently deleted and cannot be resumed.
For auto-resume behavior, see AutoResume.
Network
If you have a service (for example a server) running inside your sandbox and you pause the sandbox, the service won’t be accessible from the outside and all the clients will be disconnected. If you resume the sandbox, the service will be accessible again but you need to connect clients again.Limitations
Pause and resume performance
- Pausing a sandbox takes approximately 4 seconds per 1 GiB of RAM
- Resuming a sandbox takes approximately 1 second
Paused sandbox retention
- Paused sandboxes are kept indefinitely; there is no automatic deletion or time-to-live limit
- There is currently no configurable “auto-kill after N days” option; a paused sandbox will not expire on its own
- You can resume a paused sandbox at any time
- To remove a paused sandbox, you must kill it explicitly with an API call (
sandbox.kill()/Sandbox.kill(sandboxId)), as shown in Removing paused sandboxes
Continuous runtime limits
- A sandbox can remain running (without being paused) for:
- 24 hours on the Pro tier
- 1 hour on the Hobby tier
- After a sandbox is paused and resumed, the continuous runtime limit is reset