Tensorlake Documentation

A mount gives a sandbox a live directory backed by a repository, without cloning it. Attach takes about a second regardless of repository size; file content streams in as processes read it, and unopened content never transfers. By default a mount is writable. The agent edits /work like any directory, and changes autosave to a durable private workspace WAL. The server workspace is created lazily on the first WAL checkpoint. Autosave never creates a Git commit or updates a branch; snapshots and promotion remain deliberate. Add --ro for a read-only view that creates no workspace and needs no cleanup. Because durable WAL checkpoints, snapshots, operations, and mount heartbeats live on the server, your control plane can track workspace state across a fleet of sandboxes — see Observe Workspaces.

Install the file-system extension once on macOS. Linux needs no setup.

tl git setup --check
tl git setup

Choose a Mount

The command shape:

tl git mount <repo>[:<ref-or-full-commit>][//<subpath>] <path> [--ro] [--workspace <id>] [--publish]

Mount	Command	Use it for
Writable mount (default)	`tl git mount agent-outputs /work`	An agent editing privately before promotion; workspace activates on first autosave
Read-only branch view	`tl git mount agent-outputs /code --ro`	Read a repository at the moving branch tip
Read-only pinned commit	`tl git mount agent-outputs:<full-commit> /release --ro`	Fixed inputs, reproducible builds, agent context
Read-only subtree	`tl git mount agent-outputs:main//services/auth /code --ro`	One directory of a monorepo
Resume a workspace	`tl git mount agent-outputs /work --workspace 3f9a2b7e1c4d`	Reattach an existing workspace on another machine
Publish on snapshot	`tl git mount agent-outputs:main /work --publish`	Every explicit snapshot also promotes to the branch; autosaves stay private

Writable Mounts (the Default)

$ tl git mount agent-outputs /work
Mounted writable agent-outputs at /work (workspace 3f9a2b7e1c4d activates on the first WAL checkpoint)

/work is an ordinary writable directory based on the branch tip — name a different base with agent-outputs:<ref-or-full-commit>. Writes enter a crash-safe local journal and autosave to private server WAL; the branch does not change while the agent works. Workspace mounts can take a subtree too; snapshots record paths relative to the repository root.

Autosave WAL

Writable mounts autosave every 30 seconds. Each autosave uploads changed content and advances the workspace’s durable WAL checkpoint, but creates no Git commit and moves no branch. This is the recovery layer for an agent run: another machine can resume through the latest server checkpoint, while the same machine can additionally recover a newer unsealed tail from its local journal. Autosave is intentionally separate from Git history. Use tl git snapshot when the current state should become an attributable workspace commit.

Read-Only Mounts

Add --ro for a view that creates no workspace and needs no cleanup:

$ tl git mount agent-outputs /code --ro
Mounted agent-outputs at /code (read-only, follows main)

A read-only branch mount follows the branch: when it moves, Tensorlake refreshes only the paths that changed. Reads are always consistent — a file open when the branch moves keeps serving the version it was opened against. Pin a commit when the input must never change (pinning takes a full commit id, not an abbreviation):

$ tl git mount agent-outputs:9f2a1c8e4d6b1a0f3c7e9d2b8a4f6c1e0d3b7a99 /release --ro
Mounted agent-outputs at /release (read-only, pinned)

Mount a subtree when the task only needs part of a large repository. The mount root becomes that directory, and nothing outside it is fetched:

$ tl git mount agent-outputs:main//services/auth /code --ro
Mounted agent-outputs//services/auth at /code (read-only, follows main)

Subtree and commit forms combine: agent-outputs:9f2a1c8e4d6b1a0f3c7e9d2b8a4f6c1e0d3b7a99//services/auth.

Snapshot Changes

$ tl git snapshot /work -m "implemented parser and tests"
Snapshot 8b21f6a9c3d5e7f1a2b4c6d8e0f3a5b7c9d1e3f5 (14 file(s), 14 of 14 chunks uploaded)

Snapshotting first seals any pending local changes, then materializes the resulting WAL state as one commit on the workspace. It is a deliberate history boundary, not the first point of durability. Snapshotting with no changes is a no-op:

$ tl git snapshot /work
Nothing to snapshot: workspace is clean.

Promote to a Branch

$ tl git promote /work main
Promoted workspace 3f9a2b7e1c4d -> main at 1c4d9a2f7e5b3d8c6a4f2e0d9b7c5a3f1e8d6b4c (squashed)

Promotion is the deliberate path to a branch. Before landing, it autosaves and materializes any dirty WAL, then lands the workspace as a squashed commit. Compare-and-swap safety prevents a plain promotion from overwriting a branch that moved. Add --merge to land a two-parent merge instead. See Merging Changes for conflict reports and the resolve loop. Activity history shows who published the promotion and which workspace it came from.

Rebase a Workspace

When the branch has moved and you want the workspace replayed on top of it — a linear history instead of a merge — rebase it onto a target ref or commit:

$ tl git rebase /work main
Rebased workspace 3f9a2b7e1c4d onto main at 9c4e2a7b1f3d (3 snapshot(s) replayed).

The target is required — rebase onto any branch, tag, or full commit. The daemon first seals pending local WAL, then the replay runs server-side and the mounted directory updates in place. If both sides changed the same content, the conflicting files carry standard diff3 markers — resolve, snapshot, and promote. After a clean rebase, promotion fast-forwards. Add --fail-on-conflict to report conflicts without materializing markers into the workspace.

Check Status

$ tl git status /work
repository: agent-outputs
state: workspace_snapshotted_unpromoted
source: refs/heads/main
commit: 8b21f6a9c3d5
workspace: 3f9a2b7e1c4d
base: 9c4e2a7b1f3d
snapshot: 8b21f6a9c3d5
target: main
relationship: ahead
local changes: 0 path(s)
next: tl git promote <BRANCH>
next: tl git rebase <REF-OR-COMMIT>

With unsealed changes, status reports how many paths are dirty and makes snapshotting the next valid transition:

state: workspace_locally_dirty
local changes: 2 path(s)
next: tl git snapshot

Status also names every in-between state a workspace can reach — behind its branch, mid-rebase with unresolved markers, attached elsewhere — together with the command that exits it. Add --json for machine-readable output.

Observe Workspaces

Durable workspace state is server-side, so you can inspect a fleet without touching its sandboxes. List workspace WAL, snapshot, and attachment state first:

tl git workspaces agent-outputs

tl git smartlog shows every branch, tag, workspace, and snapshot chain and how they sit relative to each other:

$ tl git smartlog agent-outputs
main            1c4d9a2f  parser and tests               2m ago
├─ 3f9a2b7e1c4d  8b21f6a9  implemented parser and tests   ahead 1
├─ 7d4c1e9b2a6f  5e3a7c1d  refactor config loader         ahead 2
└─ b2e8f4a6c0d1  (no snapshots)                           at base

tl git log shows one mount’s own workspace snapshot chain; tl git smartlog --project widens the view to the whole project. The same graph is in the dashboard’s repository page, with each workspace’s snapshot chain and actor attribution. Every snapshot, promote, rebase, and merge is also a durable entry in the repository’s activity history — the audit trail of what your agents did, queryable long after the sandboxes are gone. Live mounts also report a liveness heartbeat — that a mount exists, where it’s mounted, and that it’s still alive — so the control plane can tell which sessions are active. Fine-grained edits remain local until autosave; durable WAL checkpoints report progress without exposing every in-progress edit.

Reattach a Workspace

The mount path is disposable. The workspace is the resumable state behind it. Unmounting keeps the workspace by default:

$ tl git unmount /work
Unmounted /work. Workspace 3f9a2b7e1c4d kept.

Reattach it later from the same sandbox, another sandbox, or another machine. The new mount path can be different:

$ tl git mount agent-outputs /work2 --workspace 3f9a2b7e1c4d
Mounted workspace 3f9a2b7e1c4d (agent-outputs) at /work2, resumed at its last durable checkpoint

A workspace already mounted elsewhere mounts read-only if you mount it again. Unmount it there first to take writes.

Delete a Workspace

Delete the workspace while unmounting when its history is no longer needed:

$ tl git unmount /work --delete
Unmounted /work (workspace 3f9a2b7e1c4d deleted).

The workspace WAL and unpublished snapshots become unreachable. Promote first if the work should survive as branch history. Detached workspaces are also collected automatically. By default, a WAL-only workspace is retained for 48 hours and a workspace with snapshots for 14 days. An actively mounted workspace is retained. These periods are deployment configuration, so use explicit deletion when your application requires deterministic cleanup.

What a Mount Is Not

Not a Git checkout. There is no .git directory inside a mount, and git commands do not run there. The verbs on this page are the interface — see Git or the tl CLI? for how they map onto Git habits. tl git clone exists when you need a real clone.
Not auto-publishing. A repository mount autosaves to private workspace WAL, but autosave never creates a commit or changes a branch. For a shared directory whose autosave windows periodically advance the common state, use a file system.
Not fully offline. Cached content and the crash-safe local journal can remain usable during a disconnection. Fetching uncached content and making work remotely durable require reconnection.

Next Steps

Merging Changes

Land workspaces on moved branches, resolve conflicts, and merge branches directly.

Architecture

Learn how promotion and merge conflict handling work internally.

Overview

Guides

Reference

Use Cases

Repository Mounts

Choose a Mount

Writable Mounts (the Default)

Autosave WAL

Read-Only Mounts

Snapshot Changes

Promote to a Branch

Rebase a Workspace

Check Status

Observe Workspaces

Reattach a Workspace

Delete a Workspace

What a Mount Is Not

Next Steps

Merging Changes

Architecture

​Choose a Mount

​Writable Mounts (the Default)

​Autosave WAL

​Read-Only Mounts

​Snapshot Changes

​Promote to a Branch

​Rebase a Workspace

​Check Status

​Observe Workspaces

​Reattach a Workspace

​Delete a Workspace

​What a Mount Is Not

​Next Steps

Merging Changes

Architecture

Choose a Mount

Writable Mounts (the Default)

Autosave WAL

Read-Only Mounts

Snapshot Changes

Promote to a Branch

Rebase a Workspace

Check Status

Observe Workspaces

Reattach a Workspace

Delete a Workspace

What a Mount Is Not

Next Steps