Skip to Content
Podyard

FORK

Branch a running pod or a snapshot into one or more new pods.

FORK

Forking creates new pods from the state of an existing pod or snapshot. It's the primitive behind agent branching, A/B runs, and fleet fan-out.

Base: https://api.podyard.dev/v1


POST /v1/pods/{id}/fork — Fork a running pod

Branches the live state of a running pod into a new pod. The original pod is unaffected.

Body (optional):

{ "name": "branch-a" }

Response 201:

{
  "id": "pod_01J...new",
  "name": "branch-a",
  "sourcePodId": "pod_01J...orig",
  "status": "running",
  "createdAt": "2026-01-15T10:30:00Z"
}

Errors: 429 quota_exceeded (concurrent pod limit), 422 invalid_request (source pod not running).


POST /v1/snapshots/{id}/fork — Fork a snapshot

Creates 1 to 64 new pods from a snapshot in a single call. Ideal for fleet fan-out.

Body (optional):

{ "count": 8 }
FieldTypeDefaultMaxDescription
countint164Number of pods to create

Response 201:

{
  "items": [
    { "id": "pod_...", "status": "running", "sourceSnapshotId": "snap_..." },
    { "id": "pod_...", "status": "running", "sourceSnapshotId": "snap_..." }
  ]
}

Errors: 429 quota_exceeded (if count would exceed maxConcurrentPods), 422 invalid_request (count > 64 or source snapshot not found).


FORK_SEMANTICS

  • Forked pods are independent — destroying the source does not affect them.
  • Forked pods count against maxConcurrentPods and maxLifetimeHours like any pod.
  • Fork is available on all plans (Free, Hobby, Pro, Team).

WHERE_TO_GO_NEXT

  • Snapshots — creating fork points.
  • Pods — pod lifecycle.
  • Errors — full error code reference.