Branching Workflows

One of ConTree’s most powerful features is the ability to branch execution flows from a single base filesystem state (a snapshot of all files and directories in a container at a specific point in time). This is similar to Git branches, but for container execution states.

Why Branching Matters

Without ConTree, running the same operations twice (like installing packages, creating files, or compiling code) requires rebuilding the entire filesystem state from scratch each time. ConTree captures the exact filesystem state after each command, making it reproducible and allowing you to branch from that exact state.

Simple Branching Example

This example demonstrates creating a parent state with a random value, then branching into multiple child states from that fixed parent:

Async
Sync

base = await client.images.use("alpine:latest")

child = await base.run(shell='echo "$RANDOM" > /tmp/random.txt', disposable=False)
print(f"Child created from base, UUID: {child.uuid}\n")

for i, letter in enumerate(["A", "B", "C"], 1):
    gc = await child.run(
        shell=f"echo '{letter}' >> /tmp/random.txt && cat /tmp/random.txt",
        disposable=False,
    )
    print(f"Grandchild {i}: {gc.stdout.strip()}")

See run() for full API reference.

base = client.images.use("alpine:latest")

child = base.run(shell='echo "$RANDOM" > /tmp/random.txt', disposable=False).wait()
print(f"Child created from base, UUID: {child.uuid}\n")

for i, letter in enumerate(["A", "B", "C"], 1):
    gc = child.run(
        shell=f"echo '{letter}' >> /tmp/random.txt && cat /tmp/random.txt",
        disposable=False,
    ).wait()
    print(f"Grandchild {i}: {gc.stdout.strip()}")

See run() for full API reference.

Key Points:

The child state contains a random value that would be different on each execution without ConTree
All three grandchildren start from the exact same child state (same random value)
Each grandchild branches independently, creating different execution paths

Advanced Branching Patterns

For more complex scenarios with multiple branching strategies:

Async
Sync

image = await client.images.use("alpine:latest")
print(f"Using {image=}")

print("\nExample 1: Different commands from same image")
result1 = await image.run(shell="echo 'First branch'", disposable=False)
result2 = await image.run(shell="echo 'Second branch'", disposable=False)
result3 = await image.run(shell="ls /bin | head -3", disposable=False)

print(f"Branch 1: {result1.stdout=}, {result1.uuid=}")
print(f"Branch 2: {result2.stdout=}, {result2.uuid=}")
print(f"Branch 3: {result3.stdout=}, {result3.uuid=}")

print("\nExample 2: Random output command (different each time)")
random1 = await image.run(shell="od -An -N2 -tu2 /dev/urandom", disposable=False)
random2 = await image.run(shell="od -An -N2 -tu2 /dev/urandom", disposable=False)

print(f"Random 1: {random1.stdout=}, {random1.uuid=}")
print(f"Random 2: {random2.stdout=}, {random2.uuid=}")

print("\nExample 3: Chain of operations from different branches")
base_result = await image.run(shell="echo 'apple\nbanana\ncherry' > /tmp/fruits.txt", disposable=False)

sort_result = await base_result.run(shell="sort /tmp/fruits.txt", disposable=False)
reverse_result = await base_result.run(shell="sort -r /tmp/fruits.txt", disposable=False)

print(f"Base: {base_result.uuid=}")
print(f"Sorted: {sort_result.stdout=}, {sort_result.uuid=}")
print(f"Reverse sorted: {reverse_result.stdout=}, {reverse_result.uuid=}")

print("\nExample 4: Same command twice - same UUID")
same1 = await image.run(shell="echo 'Same command'", disposable=False)
same2 = await image.run(shell="echo 'Same command'", disposable=False)

print(f"Same 1: {same1.stdout=}, {same1.uuid=}")
print(f"Same 2: {same2.stdout=}, {same2.uuid=}")
print(f"UUIDs equal: {same1.uuid == same2.uuid}")

See ContreeImage for full API reference.

image = client.images.use("alpine:latest")
print(f"Using {image=}")

print("\nExample 1: Different commands from same image")
result1 = image.run(shell="echo 'First branch'", disposable=False).wait()
result2 = image.run(shell="echo 'Second branch'", disposable=False).wait()
result3 = image.run(shell="ls /bin | head -3", disposable=False).wait()

print(f"Branch 1: {result1.stdout=}, {result1.uuid=}")
print(f"Branch 2: {result2.stdout=}, {result2.uuid=}")
print(f"Branch 3: {result3.stdout=}, {result3.uuid=}")

print("\nExample 2: Random output command (different each time)")
random1 = image.run(shell="od -An -N2 -tu2 /dev/urandom", disposable=False).wait()
random2 = image.run(shell="od -An -N2 -tu2 /dev/urandom", disposable=False).wait()

print(f"Random 1: {random1.stdout=}, {random1.uuid=}")
print(f"Random 2: {random2.stdout=}, {random2.uuid=}")

print("\nExample 3: Chain of operations from different branches")
base_result = image.run(shell="echo 'apple\nbanana\ncherry' > /tmp/fruits.txt", disposable=False).wait()

sort_result = base_result.run(shell="sort /tmp/fruits.txt", disposable=False).wait()
reverse_result = base_result.run(shell="sort -r /tmp/fruits.txt", disposable=False).wait()

print(f"Base: {base_result.uuid=}")
print(f"Sorted: {sort_result.stdout=}, {sort_result.uuid=}")
print(f"Reverse sorted: {reverse_result.stdout=}, {reverse_result.uuid=}")

print("\nExample 4: Same command twice - same UUID")
same1 = image.run(shell="echo 'Same command'", disposable=False).wait()
same2 = image.run(shell="echo 'Same command'", disposable=False).wait()

print(f"Same 1: {same1.stdout=}, {same1.uuid=}")
print(f"Same 2: {same2.stdout=}, {same2.uuid=}")
print(f"UUIDs equal: {same1.uuid == same2.uuid}")

See ContreeImageSync for full API reference.

Use Cases

Branching is particularly useful for:

Testing multiple scenarios: Run different operations from the same starting state
Reproducible randomness: Capture random/non-deterministic operations and branch from them
Parallel execution paths: Execute different workflows from a common checkpoint
Version control for execution: Create branches like Git for different execution flows

Get Started

Inference

Observability

Post-training

Data Lab

Sandboxes

Teams & Access Management

Other Capabilities

Integrations

Why Branching Matters

Simple Branching Example

Advanced Branching Patterns

Use Cases

​Why Branching Matters

​Simple Branching Example

​Advanced Branching Patterns

​Use Cases

Why Branching Matters

Simple Branching Example

Advanced Branching Patterns

Use Cases