> ## 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). Directory mounts also automatically save your work and if your sandbox crashes, you can resume from the last auto-saved checkpoint. Install the file-system extension once on macOS. Linux needs no setup. ```bash theme={null} tl fs setup --check tl fs 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 ` | 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 repository agent-outputs at /work (workspace 3f9a2b7e1c4d). ``` `/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 repository agent-outputs read-only at /code (refs/heads/main at 9f2a1c8e4d6b; no workspace). ``` 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 repository agent-outputs read-only at /release (9f2a1c8e4d6b1a0f3c7e9d2b8a4f6c1e0d3b7a99 at 9f2a1c8e4d6b; no workspace). ``` 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 repository agent-outputs read-only at /code (refs/heads/main at 9f2a1c8e4d6b; no workspace). ``` 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 8b21f6a9c3d5 retained permanently. ``` 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 Snapshot 8b21f6a9c3d5 retained permanently. ``` A clean snapshot mints no new commit; it reports the snapshot already at the workspace tip. ## Promote to a Branch ```bash theme={null} $ tl git promote /work main Snapshot 8b21f6a9c3d5 retained permanently. Promoted workspace 3f9a2b7e1c4d -> refs/heads/main at 1c4d9a2f7e5b. ``` 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 onto main (3 path(s) changed). ``` 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 reference: refs/heads/main state: workspace_snapshotted_unpromoted workspace: 3f9a2b7e1c4d base: 9c4e2a7b1f3d snapshot: 8b21f6a9c3d5 target: 9c4e2a7b1f3d relationship: ahead local changes: 0 path(s) next: tl git promote next: tl git rebase ``` Daemon and credential diagnostics follow those lines; they are for support, not for the workflow. 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 names the state a workspace is in together with the commands that leave it, and never recommends a transition the state does not permit — a dirty overlay is told to snapshot, because rebase and sync reject one. Besides the two above, the states are `workspace_clean`, `workspace_target_advanced` (the branch moved past your base), `read_only_following`, `read_only_pinned`, `source_ref_deleted`, and `server_unreachable_stale_view` for a mount that cannot currently reach the server. 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 repository project_9f3c2a1b/agent-outputs main 1c4d9a2f7e5b ├─ 3f9a2b7e1c4d 8b21f6a9c3d5 implemented parser and tests ahead 1 ├─ 7d4c1e9b2a6f 5e3a7c1d9b2f 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. ``` Reattach it later from the same sandbox, another sandbox, or another machine. The new mount path can be different. `--workspace` takes the **full** workspace id (`tl git workspaces ` lists them; mount and status print an abbreviation): ```bash theme={null} $ tl git mount agent-outputs /work2 --workspace 3f9a2b7e1c4d5e7f1a2b4c6d8e0f3a5b7c9d1e3f Mounted repository agent-outputs at /work2 (workspace 3f9a2b7e1c4d). ``` A workspace that already has a live writable mount refuses a second mount. 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. ``` 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.