> ## 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.

# Fork

> Branch a running machine into an independent child.

Fork is Nullspace's main differentiator for agent and evaluator workflows. Do
expensive setup once, fork the machine, then let each branch mutate files,
processes, and services independently.

## Branch warm state

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

  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")

  print(parent.files.read("/workspace/state.txt").strip())
  print(child.files.read("/workspace/state.txt").strip())

  child.kill()
  parent.kill()
  ```

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

  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");

  console.log((await parent.files.read("/workspace/state.txt")).trim());
  console.log((await child.files.read("/workspace/state.txt")).trim());

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

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # Fork a running machine into an independent child.
  nullspace machine fork mch_123
  ```

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

## Use cases

* Fan out prompt, patch, or evaluator variants from one prepared repo.
* Test destructive changes in a child without touching the parent.
* Keep a warm parent while retrying independent plans in children.

## Behavior

Parent and child each receive their own machine ID and routing credentials.
Shared volumes are remounted in the child; the external volume data is shared
according to volume mount permissions.

## Related

* [Fork example](../examples/fork)
* [Lifecycle events](../observability/lifecycle-events)