BRANCH a running sandbox to fork mid-thought agents

# Full BRANCH (default)
forkd snapshot --from-sandbox <sandbox-id> --tag checkpoint-1

# Diff BRANCH (~200 ms pause)
forkd snapshot --from-sandbox <sandbox-id> --tag checkpoint-1 --diff

# Live BRANCH (sub-50 ms pause; source must have been spawned with --live-fork)
forkd snapshot --from-sandbox <sandbox-id> --tag checkpoint-1 --live

# Live + fire-and-forget: returns ~10 ms after source resumes
forkd snapshot --from-sandbox <sandbox-id> --tag checkpoint-1 --live --no-wait

forkd fork --tag checkpoint-1 -n 5 --per-child-netns

from forkd import Controller

c = Controller()  # reads FORKD_URL and FORKD_TOKEN from env

# Spawn a source sandbox. live_fork=True is required upfront for mode="live" later.
parent = c.spawn_sandboxes("pyagent", n=1, live_fork=True)[0]

# ... drive the parent via in-guest Sandbox, then BRANCH before a risky step ...

# Diff BRANCH — ~200 ms pause, synchronous
branch = c.branch_sandbox(parent["id"], tag="checkpoint-diff", mode="diff")
grandchildren = c.spawn_sandboxes(branch["tag"], n=5)

# Live BRANCH — sub-50 ms pause, fire-and-forget
branch = c.branch_sandbox(parent["id"], mode="live", wait=False)
# Returns after ~10 ms with status="writing"
# Poll until the background copy finishes:
import time
while True:
    snaps = c.list_snapshots()
    snap = next((s for s in snaps if s["tag"] == branch["tag"]), None)
    if snap and snap.get("status") == "ready":
        break
    time.sleep(0.5)

grandchildren = c.spawn_sandboxes(branch["tag"], n=5)

import { Controller } from '@deeplethe/forkd';

const ctrl = new Controller();  // reads FORKD_URL, FORKD_TOKEN from env

const [parent] = await ctrl.spawnSandboxes({
  snapshotTag: 'pyagent',
  n: 1,
  perChildNetns: true,
  liveFork: true,   // required upfront for mode: 'live' later
});

// ... drive parent ...

// Live BRANCH + fire-and-forget
const branch = await ctrl.branchSandbox(parent.id, { mode: 'live', wait: false });
// branch.status === "writing" at this point

// Poll for ready
let snap;
while (true) {
  const snaps = await ctrl.listSnapshots();
  snap = snaps.find(s => s.tag === branch.tag);
  if (snap?.status === 'ready') break;
  await new Promise(r => setTimeout(r, 500));
}

const kids = await ctrl.spawnSandboxes({ snapshotTag: branch.tag, n: 5 });

TOKEN=$(cat /etc/forkd/token)
while true; do
  STATUS=$(curl -s -H "Authorization: Bearer $TOKEN" \
    http://127.0.0.1:8889/v1/snapshots | \
    jq -r '.[] | select(.tag=="checkpoint-1") | .status')
  echo "status: $STATUS"
  [ "$STATUS" = "ready" ] && break
  sleep 0.5
done

TOKEN=$(cat /etc/forkd/token)

curl -s -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     -X POST http://127.0.0.1:8889/v1/sandboxes/sb-67a1b3-0000/branch \
     -d '{"tag":"checkpoint-1","mode":"live","wait":false}'

{
  "tag": "checkpoint-1",
  "dir": "/home/user/.local/share/forkd/snapshots/checkpoint-1",
  "created_at_unix": 1717000456,
  "branched_from": "sb-67a1b3-0000",
  "pause_ms": 48,
  "status": "writing"
}

from forkd import Controller, Sandbox

c = Controller()

# Boot the source agent with live_fork=True
parent = c.spawn_sandboxes("langgraph-react", n=1, live_fork=True)[0]
sb = Sandbox(sandbox_id=parent["id"])

# Run the agent for several turns (it builds up reasoning state)
sb.eval("agent.run('Plan a 3-day trip to Kyoto')")

# BRANCH mid-thought (sub-50 ms source pause)
branch = c.branch_sandbox(parent["id"], mode="live", wait=False)

# Wait for branch to be ready, then fan out with 3 different hints
hints = ["Focus on budget options", "Include nature experiences", "Prioritize cultural sites"]
grandchildren = c.spawn_sandboxes(branch["tag"], n=3)
for child, hint in zip(grandchildren, hints):
    Sandbox(sandbox_id=child["id"]).eval(f"inject_hint('{hint}')")