Architecture

This page is a deep dive. You do not need it for day-to-day use. Start with Git-backed File Systems, Core Concepts, or File System Mounts first.

​

Overview

Tensorlake separates repository metadata from file content.

• The control plane stores commits, refs, branches, workspaces, merge state, and operation history.
• The data plane stores file content in blob storage.
• Mounts resolve metadata through the control plane and fetch file content lazily from the data plane.

This split keeps workspace creation, branch resolution, and snapshot listing fast even when repositories are large.

​

Metadata and Storage

A workspace is metadata, not a full repository copy. It records:

• The repository it belongs to.
• The branch or commit it forked from.
• The workspace snapshot chain.

Creating a workspace writes a small metadata record. Snapshotting appends a commit to that workspace chain and uploads only changed content. Repository optimization, deduplication, and garbage collection run in the background so agents do not wait on storage maintenance.

​

Content Delivery

Mounting a repository does not copy the repository into the sandbox. The mount resolves the tree, then fetches file content lazily as processes read paths. That means:

• Large repositories can mount quickly.
• A sandbox only downloads paths it actually reads.
• Many sandboxes can mount the same repository without a single shared serving path becoming the bottleneck.

Following read-only mounts add branch tracking. When the followed branch moves, Tensorlake compares the old and new commits and invalidates only changed paths. Unchanged files keep their warm page cache.

​

Merge Engine

Every divergent-history operation uses the same server-side merge engine:

• Promoting a workspace to a branch.
• Merging one branch into another.
• Auto-publishing snapshots from a shared read-write workspace.

The merge engine uses standard three-way merge semantics and is verified against Git’s merge behavior. It compares the common ancestor, the target branch, and the workspace or source branch. Cost is proportional to changed paths, not total repository size:

• If only one side changed a path, that change wins.
• If both sides made the same change, the path resolves automatically.
• If both sides edited different regions of a text file, the text merge resolves automatically.
• If both sides conflict, the result depends on conflict policy.

​

Conflict Policies

Tensorlake uses two main conflict behaviors. Fail is the default for manual promotion. Nothing lands on the target branch. The operation returns a structured conflict report. The agent resolves the conflict in the workspace, snapshots again, and promotes again. Materialize is the default for shared read-write branches. The merge lands with standard Git conflict markers in conflicted files. The commit also carries a structured conflict record so tooling can query conflicts without parsing file contents. Both policies preserve the losing content in Git history.

​

Promotion

Promotion is the user-facing path through the merge engine. A workspace can land as one squashed commit or preserve each workspace snapshot as branch history. See Writable Workspaces for the workflow.

​

Observability

Every mounted file system and workspace is queryable through the API and visible in the dashboard:

• Which workspaces are live.
• Which are detached and resumable.
• Which snapshots exist.
• Which principal created each snapshot.
• Which paths changed.

Branch activity is also recorded: pushes, promotions, shared read-write reconciliations, merges, and materialized conflict records. This gives automation enough state to manage sandbox fleets based on file-system activity.