Images, checkpoints, and branches

An image is an immutable stored filesystem state. A checkpoint is an image chosen as a continuation point. A branch is an independent operation started from a selected image. Images preserve saved files and installed dependencies. They do not preserve running processes, memory, open file handles, connections, or live services.

Choose persistence before submission

Set persistence explicitly when later work needs the changed files. The Python SDK discards changes by default; the CLI saves them. A session does not override those defaults.

Interface	Default in this interface	Explicit choice	Session effect
Python SDK 0.3.6 `image.run()`	`disposable=True`	`disposable=False` saves; `True` discards	The returned object exposes the process result and, when saved, an image you can reuse through its UUID or `.run()`.
Python SDK 0.3.6 `image.session().run()`	`disposable=True`	Set `disposable=False` for a step the session must reuse	The session object updates its image reference when the retained result supplies one. It does not preserve compute.
REST API	`disposable: false` in the public request schema	Always send `disposable: false` or `disposable: true`	REST has no client session unless the application implements one.
CLI 0.9.4 `contree run`	Retains changes unless `-D` or `--disposable` is set	Omit `-D` to retain; add `-D` to discard	A retained run advances the local session image; a disposable run leaves it on the prior image.
MCP `run` tool	`disposable=true`	Set `disposable=false` to request a saved result	The result includes `result_image` and `filesystem_changed`. Check the connected server’s tool list before relying on this behavior.

Interpret the result image

Reuse a saved result only when the operation returns an image UUID and you can read the files you need from it. This also applies after a command failure, timeout, or cancellation. If no usable image is returned, restart from your last known-good image.

Run outcome	Result-image interpretation
Save requested and filesystem changed	Use the returned image UUID only after confirming that it is present and inspectable.
Save requested and filesystem did not change	An interface may return the input image UUID or report no new image. Use the returned UUID when available; otherwise keep the input image as your starting point.
Disposable run	Filesystem changes are discarded. The operation may have output, while its result-image field can be absent. A client session can continue to reference the unchanged input image.
Nonzero exit, timeout, cancellation, or platform failure	Check that the result includes an image UUID and that its files can be read before using it.

An absent result image means there is no new continuation point from that operation. An unchanged image ID means the existing immutable source remains the continuation point.

Use UUIDs for repeatable work

A tag is a mutable name. Assigning an existing tag to another image moves the tag.

Workflow	Reference to record
Reproducible evaluation or production run	Resolved input image UUID and returned result image UUID, when present
Maintained base updated over time	Tag for discovery plus the resolved UUID used by each run
Branch point	Immutable image UUID

Prepare once, branch twice

Save a shared input file once, then read it in two independent operations. The fragment belongs inside the async main() from the Python quickstart, with its authenticated client. Use an image tag available in your project. The complete recipe also shows how to run the two readers concurrently.

base = await client.images.use("alpine:3.19", strict=True)

preparation = base.run(
    shell="printf 'shared input\\n' > /tmp/input.txt",
    disposable=False,
)
checkpoint = await preparation
if checkpoint.exit_code != 0 or checkpoint.uuid is None:
    raise RuntimeError("Preparation did not produce a usable checkpoint")

first = await checkpoint.run(
    shell="printf 'first: '; cat /tmp/input.txt",
    disposable=True,
)
second = await checkpoint.run(
    shell="printf 'second: '; cat /tmp/input.txt",
    disposable=True,
)
if first.exit_code != 0 or second.exit_code != 0:
    raise RuntimeError("A checkpoint reader failed")

print(first.stdout, end="")
print(second.stdout, end="")

Expected output:

first: shared input
second: shared input

Each child starts from the same immutable checkpoint. A disposable child cannot change the checkpoint or the other child. Both runs read the checkpoint file and discard their own changes. The arrows show which image each operation starts from. The branches share a starting image, not a running process or a writable filesystem. To continue from a branch, that branch must save its own result and return an inspectable image UUID. To return to the checkpoint, start another operation from the checkpoint UUID.

Environment values

Values passed through env are available to the guest process and are represented in operation input metadata. SDK 0.3.6 exposes preserve_env=True for saving supported environment metadata together with disposable=False. Files attached to a run are also visible inside the guest. Do not put credentials in preserved environment metadata, uploaded files, or commands executed as untrusted code. Follow Configure networking and secrets for the supported controls.

Get Started

Inference

Observability

Post-training

Data Lab

Sandboxes

Teams & Access Management

Other Capabilities

Integrations

Platform Notices

Choose persistence before submission

Interpret the result image

Use UUIDs for repeatable work

Prepare once, branch twice

Environment values

Continue

​Choose persistence before submission

​Interpret the result image

​Use UUIDs for repeatable work

​Prepare once, branch twice

​Environment values

​Continue

Choose persistence before submission

Interpret the result image

Use UUIDs for repeatable work

Prepare once, branch twice

Environment values

Continue