Skip to main content
Nullspace persistence is built around hibernate and resume. Hibernate stops the active VM and records a paused-sandbox snapshot; resume restores that state into a runnable sandbox. This is separate from reusable snapshots, which keep the source sandbox running and can be used as a 1-to-many starting point.

​
Pause a sandbox

from nullspace import Sandbox

sandbox = Sandbox.create(template="base")
sandbox.files.write("/workspace/report.txt", "draft\n")
snapshot = sandbox.pause()
print(snapshot.id)

​
Resume paused state

resumed = Sandbox.resume(snapshot.id)
print(resumed.files.read("/workspace/report.txt"))
resumed.kill()
Resume creates a new running sandbox ID. If the original sandbox paused because of timeout behavior, the original ID can remain as a paused alias so Sandbox.connect(original_id) and public auto-resume traffic can find the latest running execution. 
original_id = sandbox.id
snapshot = sandbox.pause()

resumed = Sandbox.connect(original_id)
print(original_id, resumed.id)

​
Reusable snapshots

snapshot = sandbox.create_snapshot()

child_a = Sandbox.create(snapshot_id=snapshot.id)
child_b = Sandbox.create(snapshot_id=snapshot.id)

child_a.kill()
child_b.kill()
create_snapshot() briefly pauses the source, captures memory and mutable rootfs state, resumes the source, and returns a reusable snapshot ID. Use Sandbox.create(snapshot_id=...) to spawn independent children from it.

​
Behavior

  • VM memory and mutable rootfs state come from hibernate or reusable snapshots.
  • Shared volumes are remounted as external storage during resume and fork.
  • Snapshot compatibility depends on runtime host and kernel compatibility; incompatible restores fail explicitly instead of silently starting from scratch.
  • Sandbox.get_info_by_id(id) is read-only and does not wake a paused alias.
  • Deleting a paused original ID removes the paused alias and its lifecycle routing target.
  • Use lifecycle events to observe transition state and recovery failures.

​
Auto-resume

Create with on_timeout="pause", auto_resume=True when a public HTTP or WebSocket request should wake a paused sandbox before the request is forwarded. When the wake cannot complete in time, callers get 503 Service Unavailable with Retry-After: 5.