> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Images, checkpoints, and branches

> Save filesystem state deliberately and start independent work from immutable images.

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](/sandboxes/start/python-quickstart), with its authenticated `client`. Use an image tag available in your project. The [complete recipe](/sandboxes/cookbook/prepare-once-reuse-safely) also shows how to run the two readers concurrently.

```python theme={null}
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:

```text theme={null}
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.

```mermaid theme={null}
flowchart TB
  A[Base image] --> B[Prepare and save]
  B --> C[Checkpoint]
  C --> D[Run A]
  C --> E[Run B]
  D --> F[Output A]
  E --> G[Output B]
```

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](/sandboxes/guides/configure-networking-and-secrets) for the supported controls.

## Continue

* [Branch, compare, and recover](/sandboxes/guides/branch-compare-and-recover)
* [Prepare and reuse environments](/sandboxes/guides/prepare-and-reuse-environments)
* [Python image reference](/sandboxes/sdk/python_sdk/reference/image)
* [REST image and inspection reference](/sandboxes/reference/index#images-and-files)