Machine Lifecycle

Nullspace machines 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 operation	Memory	Mutable rootfs and files	Processes	Volumes	Runtime resources
Creating	Booting 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.
Running	Live guest memory.	File changes are immediately visible inside the machine.	Commands, services, PTY, desktop, and agents can run.	Mounted volumes are live external storage.	CPU, memory, disk, and routing resources are allocated.
Exec	Same live memory as the running machine.	Command side effects persist in the running machine.	Foreground commands return output; background commands keep a PID.	Commands can read/write mounted volumes.	Uses the running machine resources.
Hibernate / pause	Captured into a pause/resume snapshot.	Mutable rootfs state is captured with the paused machine 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.
Paused	Stored in snapshot artifacts.	Stored with the paused machine metadata and artifacts.	Not running while paused.	External volume data remains in the volume backend.	No running VM; storage artifacts remain.
Resume	Restored lazily from paused memory state.	Restored with the paused machine.	Processes continue from captured VM state when the restore is compatible.	Volumes remount with fresh internal leases before ready.	Allocates a new running machine execution.
Reusable snapshot	Captures 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.
Fork	Branches a running machine 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 machine.
Destroy	Memory is discarded.	Machine-local mutable state is discarded.	Processes stop.	External volumes are not deleted.	Runtime resources are released.
Error	State depends on the failing transition.	Inspect lifecycle events and error envelope.	May be unavailable.	Existing external volume data is not deleted by a machine 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 machine. The default timeout action is destroy. Use on_timeout="pause" or lifecycle.on_timeout: "pause" when the machine should hibernate instead. auto_resume=True lets SDK calls, command/file/PTY/desktop routes, or public traffic targeting the original machine ID wake a hibernated machine. Preview URL traffic waits for resume and then forwards the original request when the runtime is ready.

Create And Exec

from nullspace import Machine

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

import { Machine } from "nullspace";

await using machine = await Machine.create({ template: "base" });
const result = await machine.commands.run("uname -a", { shell: true });
console.log(result.stdout);

nullspace machine create --template base
nullspace machine exec mch_123 --shell "uname -a"

curl -X POST "${NULLSPACE_API_URL}/v1/machines" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"template": "base"}'

curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/exec" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"command": "uname -a", "shell": true}'

Hibernate And Resume

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

resumed = Machine.resume(snapshot.id)
print(resumed.files.read("/workspace/state.txt"))
resumed.kill()

import { NullspaceClient } from "nullspace";

const client = new NullspaceClient();
const machine = await client.machines.create({ template: "base" });
await machine.files.write("/workspace/state.txt", "kept across pause\n");
const snapshot = await machine.hibernate();

const resumed = await client.snapshots.resume(snapshot.id);
console.log(await resumed.files.read("/workspace/state.txt"));
await resumed.destroy();

nullspace machine hibernate mch_123   # returns the pause snapshot id
nullspace machine resume snap_123

curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/hibernate" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

curl -X POST "${NULLSPACE_API_URL}/v1/machines/snap_123/resume" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

pause() is an alias for hibernate().

Reusable Snapshots

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

child = Machine.create(snapshot_id=snapshot.id)
child.kill()
source.kill()

const source = await Machine.create({ template: "base" });
await source.files.write("/workspace/state.txt", "baseline\n");
const snapshot = await source.createSnapshot();

const child = await Machine.create({ snapshotId: snapshot.id });
await child.destroy();
await source.destroy();

nullspace snapshot create mch_123   # returns a reusable snapshot id
nullspace machine create --snapshot-id snap_123

curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/snapshots" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

curl -X POST "${NULLSPACE_API_URL}/v1/machines" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"snapshot_id": "snap_123"}'

Reusable snapshots keep the source machine running and can start many independent children with Machine.create(snapshot_id=...).

Fork

parent = Machine.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()

const parent = await Machine.create({ template: "base" });
await parent.files.write("/workspace/state.txt", "common\n");

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

await parent.destroy();
await child.destroy();

nullspace machine fork mch_123

curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/fork" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

Destroy

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

machine.kill()

await machine.destroy();

nullspace machine kill mch_123

curl -X DELETE "${NULLSPACE_API_URL}/v1/machines/mch_123" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

Get started

Machines

Commands

Filesystem

Code Interpreter

Desktop

Templates

Volumes

Networking

Interactive access

Observability

State Semantics

Timeout And Auto-Resume

Create And Exec

Hibernate And Resume

Reusable Snapshots

Fork

Destroy

​State Semantics

​Timeout And Auto-Resume

​Create And Exec

​Hibernate And Resume

​Reusable Snapshots

​Fork

​Destroy

​Related

State Semantics

Timeout And Auto-Resume

Create And Exec

Hibernate And Resume

Reusable Snapshots

Fork

Destroy

Related