> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensorlake.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Repository Mounts
> Mount a repository lazily, autosave into private workspace WAL, materialize deliberate commits, and land changes with server-side promote and rebase.
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](#observe-workspaces).
Install the file-system extension once on macOS. Linux needs no setup.
```bash theme={null}
tl git setup --check
tl git setup
```
## Choose a Mount
The command shape:
```bash theme={null}
tl git mount [:][//] [--ro] [--workspace ] [--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: /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)
```bash theme={null}
$ 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:`. 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:
```bash theme={null}
$ 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):
```bash theme={null}
$ 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:
```bash theme={null}
$ 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
```bash theme={null}
$ 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:
```bash theme={null}
$ tl git snapshot /work
Nothing to snapshot: workspace is clean.
```
## Promote to a Branch
```bash theme={null}
$ 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](/git/merging) 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:
```bash theme={null}
$ 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
```bash theme={null}
$ 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
next: tl git rebase
```
With unsealed changes, status reports how many paths are dirty and makes snapshotting the next valid transition:
```bash theme={null}
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:
```bash theme={null}
tl git workspaces agent-outputs
```
`tl git smartlog` shows every branch, tag, workspace, and snapshot chain and how they sit relative to each other:
```bash theme={null}
$ 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:
```bash theme={null}
$ 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:
```bash theme={null}
$ 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:
```bash theme={null}
$ 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?](/git/introduction#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](/filesystems/introduction).
* **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
Land workspaces on moved branches, resolve conflicts, and merge branches directly.
Learn how promotion and merge conflict handling work internally.