Skip to main content
After forking a sandbox and running different plans in the children, call merge_into to commit the winner’s state back into the parent. The parent’s sandbox id remains valid and now points to the winner’s VM — so any callers holding a reference to the parent id continue working without interruption. The winner’s id is retired after the merge.

​
Request

POST /v1/sandboxes/:id/merge_into/:winner
​
id
string
required
The parent sandbox id — the one you originally forked from.
​
winner
string
required
The child sandbox id whose state should replace the parent’s. This is typically one of the ids returned by a previous fork call on this parent.

​
Response

Returns 204 No Content on success. There is no response body.

​
Examples

curl -X POST https://api.podflare.dev/v1/sandboxes/$PARENT/merge_into/$WINNER \
  -H "Authorization: Bearer $PODFLARE_API_KEY"
Response 
204 No Content

​
What happens during merge

The merge is atomic from the perspective of the in-memory VM registry:
  1. Both the parent and winner entries are removed from the sandbox registry simultaneously.
  2. The parent’s Firecracker process is sent SIGKILL and its working directory is deleted.
  3. The winner’s VM handle is re-inserted under the parent’s id.
After merge_into returns:
  • parent.id is a valid sandbox id pointing to the winner’s underlying VM.
  • winner.id is no longer a live sandbox. The SDKs mark the winner object as defunct so close() on it becomes a no-op and does not attempt a double-destroy.
  • Sibling children are not touched. If you forked n=5 and one child is the winner, the other 4 are still live — destroy them explicitly.

​
Typical pattern

children = parent.fork(n=5)
try:
    results = [c.run_code(plan) for c, plan in zip(children, plans)]
    winner = children[pick_best_index(results)]
    parent.merge_into(winner)
finally:
    for c in children:
        if c is not winner:
            c.close()

​
Idempotency and edge cases

Merging the same winner a second time returns 404 — the winner id no longer exists after the first merge. Merging a sandbox into itself returns 400.

​
Error responses

StatusBodyCause
400{"error": "..."}Parent and winner are the same id
401{"error": "invalid api key"}Missing or invalid bearer token
404{"error": "sandbox not found"}Parent or winner id does not exist
500{"error": "..."}Internal error during VM swap