Appearance

turbo fork ​

The fork command creates a copy of an existing container.

Usage ​

text
Usage: turbo fork  <existing container> [<new container name>]

Options ​

  • --format=VALUE — Use the specified format for output. Supported values: json
  • --images=VALUE — Use specified images for new container
  • --wait-after-error — Leave process open after error
  • --wait-after-exit — Leave process open after it exits

The --images flag replaces all images in the new container with the ones that are specified. Any images from the original container that are required in the new container would need to be specified again.

Description ​

  • Forking records a fork point: a snapshot of the parent's state at the moment of the fork, written onto both the parent and the child. That snapshot is the base turbo merge works over when the branches rejoin, so a container forked without one can only be merged with an explicit --base.
  • The fork point is content-addressed, so forking an unchanged, idle container a second time reuses the snapshot the first fork recorded. Branching one prepared container twice costs one snapshot, not two.
  • A snapshot is named by what it holds: snp- followed by the whole content address, sixty-four hexadecimal digits. Printed output abbreviates it to the first twelve; --format=json carries all of it. Wherever a snapshot id is an argument, any leading part of one is accepted as long as it is at least eight digits and names exactly one stored snapshot.
  • The new container's name must be one no other container has, and it is checked before anything is frozen. Forking a named container without giving the copy a name of its own is refused for the same reason: the copy would carry its parent's name.
  • The new container is populated from the fork point rather than copied from the parent, so what the child holds is exactly what the base says it holds.
  • The fork point also records what turbo state made of the parent's state at that moment: the application state units present, how each is classified, and the structural signature of each. That is what lets a later merge tell a unit somebody edited from one an application migrated. It is a reading of the snapshot rather than part of its identity, so a fork point stays reusable when the state subsystem learns a new application.
  • Forking with --images gives the child a different image set from its fork point. The two overlays can no longer be compared path for path, so merge refuses such a container.
  • Hardened containers created with --sandbox cannot be forked: their state lives in service-owned storage the client cannot copy, so fork refuses them rather than producing an empty copy.
  • Under the default write-copy isolation, writes to host paths go to the host rather than into the container, so two forks editing a host-mounted workspace overwrite each other and leave nothing to merge. fork warns when the container uses that isolation; run it with merge or full isolation for the workspace if you intend to merge the branches later.

Snapshots are reference-counted from container records, and turbo gc removes the ones no container names any more.

On macOS ​

The verb and its options are the same on macOS. What differs is who owns the storage underneath it.

  • The container must be stopped. The Turbo sandbox service owns container storage on macOS and cannot pause a running container while its overlay is read, so fork refuses a running one by name and tells you to stop it. On Windows a running container is suspended for the moment it takes to record the fork point and resumed afterwards.
  • The sandbox service assigns the copy's container id from the parent and the new name, which is the other reason a name another container already has is refused before anything is frozen.
  • The sandbox service records the fork point and creates the child, and it writes the fork onto both records in the same operation. A service that does not provide the container snapshot operations refuses the fork and names what is missing; see turbo merge for the message and the remedy.
  • A fork point has the same identity on both platforms. The same overlay frozen on Windows and on macOS is the same snapshot with the same snp- id.

Examples ​

# Create a copy of an unnamed container
> turbo fork 28c

# Create a named copy of a container
> turbo fork test-container copy-of-test-container

# Create a copy with Java & Firefox as new main images
> turbo fork chrome-container --images=oracle/jre,mozilla/firefox

JSON output ​

When --format=json option was passed this command will provide output in JSON format. It will contain either an container object with information about cloned container or an error object if command failed. The container object carries a forkPoint field naming the snapshot the fork was taken from.

Turbo.net © 2025