> ## 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 and watch parent and child diverge.

Fork clones a *running* machine — memory, processes, and filesystem — into an
independent child. This example writes shared state, forks, then changes each
side to show they no longer affect each other.

## Setup

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
uv pip install "nullspace-sdk==1.0.0"
export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain
```

## Python

```python fork_example.py theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
from nullspace import Machine

with Machine.create(template="base", timeout=120) as parent:
    parent.files.write("/workspace/state.txt", "common\n")

    child = parent.fork()
    try:
        parent.files.write("/workspace/state.txt", "common\nparent\n")
        child.files.write("/workspace/state.txt", "common\nchild\n")

        print("parent:", parent.files.read("/workspace/state.txt").split())
        print("child: ", child.files.read("/workspace/state.txt").split())
    finally:
        child.kill()
```

## Expected output

```text theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
parent: ['common', 'parent']
child:  ['common', 'child']
```

The child starts as an exact copy (it sees `common`), then each side's write
lands only in its own filesystem. Fork children are full machines: fork them
again, hibernate them, or expose ports — anything a created machine can do.

## Where this is useful

* **Parallel exploration** — set up a repo or environment once, fork per
  hypothesis, keep the winner.
* **Cheap retries** — fork before a risky step; on failure, kill the child and
  fork again instead of rebuilding state.
* **Evaluation** — run N candidate patches against identical warm state.

Related: [Fork concept](../concepts/fork) ·
[Machine fork guide](../machines/fork)