Lineages

A lineage is a sandbox together with everything that descends from it: its forks, the forks of those forks, and the sandboxes restored from its snapshots. It lets you find every sandbox that shares a common starting point.

How lineages are formed

A sandbox created from a base or a template, with zbox new or POST /api/rest/sandbox, starts a new lineage and has no parent. Two sandboxes from the same template belong to two different lineages.

A fork child and a restored sandbox join the lineage of the sandbox they came from, and record that sandbox as their parent.

An imported sandbox has no parent and starts a lineage of its own. The exception is an archive uploaded from a file: the upload gets a lineage, and every import of that upload joins it.

Each sandbox carries both:

Field	Meaning
lineageId	The lineage the sandbox belongs to. Set at create and never changes.
parentId	The sandbox it was forked or restored from. Empty for a sandbox created from a base or a template, and for an imported one.

zbox get shows them as Lineage and Parent.

A lineage has no name and no status of its own, only an ID and the time it was created. It stays in the workspace while the workspace keeps the record of any of its sandboxes, or an export file of it. After that, retention deletes the lineage with its export records. Objects in a bucket stay.

List and inspect lineages

# all lineages in the workspace, newest first
zbox lineage list
# a page of 50, then the next one
zbox lineage list --limit 50
zbox lineage list --limit 50 --before <last-lineage-id>
# one lineage by its ID
zbox lineage get <lineage-id>

GET /api/rest/lineage-list pages with limit (at most 1000) and beforeId like the sandbox list, and answers every lineage when you pass no limit.

To see the sandboxes of a lineage, filter the sandbox list. Like any zbox list, it shows only live sandboxes unless you ask for other statuses:

# sandboxes of one lineage
zbox list --lineage <lineage-id>
# only the removed ones, until retention deletes them
zbox list --lineage <lineage-id> --status terminated,archived
# direct children of one sandbox (forks and restores), by ID or name
zbox list --parent app

--parent lists only direct children. To find everything descended from a sandbox, list its lineage.

Export and import

To move a sandbox out of the workspace or into another one, see export and import.