Skip to main content
Nullspace sandboxes move through explicit states instead of hiding lifecycle behind sessions. Use the state table when deciding whether to destroy, hibernate, resume, snapshot, or fork.

​
State Semantics

State or operationMemoryMutable rootfs and filesProcessesVolumesRuntime resources
CreatingBooting from template or snapshot.Materializing template/rootfs state.Start commands may run before ready.Mount intents are resolved before ready.Counts against create capacity while placement is in progress.
RunningLive guest memory.File changes are immediately visible inside the sandbox.Commands, services, PTY, desktop, and agents can run.Mounted volumes are live external storage.CPU, memory, disk, and routing resources are allocated.
ExecSame live memory as the running sandbox.Command side effects persist in the running sandbox.Foreground commands return output; background commands keep a PID.Commands can read/write mounted volumes.Uses the running sandbox resources.
Hibernate / pauseCaptured into a pause/resume snapshot.Mutable rootfs state is captured with the paused sandbox state.Live processes stop with the VM and resume with memory state when compatible.Mount leases are released; attachment intent remains durable and remounts on resume.Running VM resources are released after hibernate succeeds.
PausedStored in snapshot artifacts.Stored with the paused sandbox metadata and artifacts.Not running while paused.External volume data remains in the volume backend.No running VM; storage artifacts remain.
ResumeRestored lazily from paused memory state.Restored with the paused sandbox.Processes continue from captured VM state when the restore is compatible.Volumes remount with fresh internal leases before ready.Allocates a new running sandbox execution.
Reusable snapshotCaptures a baseline while the source keeps running.Captured as a reusable 1-to-many baseline.Snapshot children start from captured state; source keeps running.Volume data remains external; snapshot stores attachment intent, not volume contents.Snapshot artifacts are stored for future creates.
ForkBranches a running sandbox into a child.Parent and child start from the same warm state, then diverge.Parent and child continue independently.Shared external volumes remain shared unless mounted read-only or separated by path.Allocates a second running sandbox.
DestroyMemory is discarded.Sandbox-local mutable state is discarded.Processes stop.External volumes are not deleted.Runtime resources are released.
ErrorState depends on the failing transition.Inspect lifecycle events and error envelope.May be unavailable.Existing external volume data is not deleted by a sandbox error.Cleanup or recovery depends on error type.

​
Timeout And Auto-Resume

timeout_ms controls when the reaper acts on an idle or long-running sandbox. The default timeout action is destroy. Use on_timeout="pause" or lifecycle.on_timeout: "pause" when the sandbox should hibernate instead. auto_resume=True lets SDK calls, command/file/PTY/desktop routes, or public traffic targeting the original sandbox ID wake a hibernated sandbox. Preview URL traffic waits for resume and then forwards the original request when the runtime is ready.

​
Create And Exec

from nullspace import Sandbox

with Sandbox.create(template="base") as sandbox:
    result = sandbox.commands.run("uname -a", shell=True)
    print(result.stdout)

​
Hibernate And Resume

sandbox = Sandbox.create(template="base")
sandbox.files.write("/workspace/state.txt", "kept across pause\n")
snapshot = sandbox.hibernate()

resumed = Sandbox.resume(snapshot.id)
print(resumed.files.read("/workspace/state.txt"))
resumed.kill()
pause() is an alias for hibernate().

​
Reusable Snapshots

source = Sandbox.create(template="base")
source.files.write("/workspace/state.txt", "baseline\n")
snapshot = source.create_snapshot()

child = Sandbox.create(snapshot_id=snapshot.id)
child.kill()
source.kill()
Reusable snapshots keep the source sandbox running and can start many independent children with Sandbox.create(snapshot_id=...).

​
Fork

parent = Sandbox.create(template="base")
parent.files.write("/workspace/state.txt", "common\n")

child = parent.fork()
parent.files.write("/workspace/state.txt", "parent\n")
child.files.write("/workspace/state.txt", "child\n")

parent.kill()
child.kill()

​
Destroy

Destroy releases runtime resources. It does not delete external durable data, such as shared volume contents. 
sandbox.kill()