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

​
Pause a machine

from nullspace import Machine

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

​
Resume paused state

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

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

​
Reusable snapshots

snapshot = machine.create_snapshot()

child_a = Machine.create(snapshot_id=snapshot.id)
child_b = Machine.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 Machine.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.
  • Machine.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 machine before the request is forwarded. When the wake cannot complete in time, callers get 503 Service Unavailable with Retry-After: 5.