> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshots

> Create reusable machine snapshots and spawn independent machines from them.

Use snapshots when expensive setup should become a durable starting point for
many later machines. Each `Machine.create(snapshot_id=...)` call starts a fresh
independent machine from the same snapshot, and the snapshot remains available
until deleted.

## Create a reusable snapshot

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  from nullspace import Machine

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

  snapshot = machine.create_snapshot()
  print(snapshot.id)
  print(machine.files.read("/workspace/state.txt"))
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  import { Machine } from "nullspace";

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

  const snapshot = await machine.createSnapshot();
  console.log(snapshot.id);
  console.log(await machine.files.read("/workspace/state.txt"));
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace snapshot create mch_123   # returns a reusable snapshot id
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/snapshots" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

## Spawn from the snapshot

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  from nullspace import Machine

  first = Machine.create(snapshot_id=snapshot.id)
  second = Machine.create(snapshot_id=snapshot.id)

  try:
      first.files.write("/workspace/state.txt", "first child\n")
      second.files.write("/workspace/state.txt", "second child\n")

      print(first.files.read("/workspace/state.txt"))
      print(second.files.read("/workspace/state.txt"))
  finally:
      first.kill()
      second.kill()
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  import { Machine } from "nullspace";

  const first = await Machine.create({ snapshotId: snapshot.id });
  const second = await Machine.create({ snapshotId: snapshot.id });

  try {
    await first.files.write("/workspace/state.txt", "first child\n");
    await second.files.write("/workspace/state.txt", "second child\n");

    console.log(await first.files.read("/workspace/state.txt"));
    console.log(await second.files.read("/workspace/state.txt"));
  } finally {
    await first.destroy();
    await second.destroy();
  }
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine create --snapshot-id snap_123
  nullspace machine create --snapshot-id snap_123
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "${NULLSPACE_API_URL}/v1/machines" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"snapshot_id": "snap_123"}'
  ```
</CodeGroup>

## Manage reusable snapshots

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  from nullspace import Snapshot

  snapshot = Snapshot.get("snap_...")
  print(snapshot.id, snapshot.machine_id, snapshot.created_at)

  for item in Snapshot.list(machine_id=snapshot.machine_id):
      print(item.id, item.metadata)

  Snapshot.delete(snapshot.id)
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  import { NullspaceClient } from "nullspace";

  const client = new NullspaceClient();

  const snapshot = await client.snapshots.get("snap_123");
  console.log(snapshot.id, snapshot.machineId, snapshot.createdAt);

  for (const item of await client.snapshots.list({ machineId: snapshot.machineId })) {
    console.log(item.id, item.metadata);
  }

  await client.snapshots.delete(snapshot.id);
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace snapshot get snap_123
  nullspace snapshot list --machine-id mch_123
  nullspace snapshot delete snap_123
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl "${NULLSPACE_API_URL}/v1/snapshots/snap_123" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

  curl "${NULLSPACE_API_URL}/v1/snapshots?machine_id=mch_123" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

  curl -X DELETE "${NULLSPACE_API_URL}/v1/snapshots/snap_123" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

## Pause, snapshot, or fork

| Primitive         | Source machine                            | Reuse model                | Restore call                                                    |
| ----------------- | ----------------------------------------- | -------------------------- | --------------------------------------------------------------- |
| Hibernate / pause | Stops the source VM                       | 1-to-1 persistence         | `Machine.resume(snapshot_id)` or `Machine.connect(original_id)` |
| Reusable snapshot | Briefly pauses, then keeps source running | 1-to-many durable template | `Machine.create(snapshot_id=snapshot_id)`                       |
| Fork              | Keeps source running                      | 1 live child per request   | `machine.fork()`                                                |

## Behavior

* Snapshots include VM memory and mutable rootfs state.
* Shared volumes remain external durable storage and are remounted on compatible
  restore; they are not copied into the snapshot.
* Restore requires compatible runtime hosts, kernels, and snapshot artifacts. A
  paused machine alias can resume only from its own latest snapshot lineage;
  reusable snapshots are restored with `Machine.create(snapshot_id=...)` and do
  not mutate the source machine.
* Delete removes reusable snapshot metadata and makes its artifact eligible for
  cleanup when no active reusable snapshot references it.

## Related

* [Persistence](./persistence)
* [Fork](./fork)
* [Templates](../templates/overview)
* [WebSocket protocol](../reference/websocket-protocol)