Tensorlake Documentation

A mount exposes a repository as a live directory on your machine or inside a sandbox, 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. Read-only views create no private workspace. 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. Directory mounts also automatically save your work and if your sandbox crashes, you can resume from the last auto-saved checkpoint.

Prerequisites

Install the Tensorlake CLI and choose an existing repository with a branch, tag, or full commit to mount. The destination directory must be empty; the CLI creates it if needed. For the SDK examples, use Node.js 22 or later, install the tensorlake npm package, and set TENSORLAKE_API_KEY. See Install and Configure. SDK mounts also require the separately installed CLI and appear on the machine running Node.js.

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

tl fs setup --check
tl fs setup

Choose a Mount

CLI
TypeScript

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 <full-workspace-id>`	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

Call repos.mount(target, path, options). The target accepts repo[:ref-or-full-commit][//subtree].

Options	Use it for
Omitted	Writable private workspace; autosaves keep changes durable without updating a branch
`{ readOnly: true }`	Read-only view of a branch, tag, full commit, or subtree
`{ workspace: "WORKSPACE_ID" }`	Resume an existing private workspace and its autosaved changes
`{ publish: true }`	Publish each explicit snapshot onto the mounted branch; requires a branch target

readOnly, workspace, and publish are mutually exclusive.

Writable Mounts (the Default)

CLI
TypeScript

$ tl git mount agent-outputs /work
Mounted repository agent-outputs at /work (workspace 3f9a2b7e1c4d).

import { RepositoryClient } from "tensorlake";

const repos = await RepositoryClient.fromEnv();
const mount = await repos.mount("agent-outputs:main", "./work");

The SDK examples below reuse repos and mount. mount.path is the absolute local path. Call mount.unmount() when you finish; repos.close() does not detach mounts.

/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. Create a snapshot when the current state should become an attributable workspace commit.

Read-Only Mounts

Use a read-only view to read repository content without creating a private workspace:

CLI
TypeScript

$ tl git mount agent-outputs /code --ro
Mounted repository agent-outputs read-only at /code (refs/heads/main at 9f2a1c8e4d6b; no workspace).

const view = await repos.mount("agent-outputs", "./code", {
  readOnly: true,
});

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):

CLI
TypeScript

$ tl git mount agent-outputs:9f2a1c8e4d6b1a0f3c7e9d2b8a4f6c1e0d3b7a99 /release --ro
Mounted repository agent-outputs read-only at /release (9f2a1c8e4d6b1a0f3c7e9d2b8a4f6c1e0d3b7a99 at 9f2a1c8e4d6b; no workspace).

const view = await repos.mount(
  "agent-outputs:9f2a1c8e4d6b1a0f3c7e9d2b8a4f6c1e0d3b7a99",
  "./release",
  { readOnly: true },
);

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:

CLI
TypeScript

$ 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).

const view = await repos.mount("agent-outputs:main//services/auth", "./code", {
  readOnly: true,
});

The subtree must exist. Detach a read-only SDK view with await view.unmount() when you finish. Subtree and commit forms combine: agent-outputs:9f2a1c8e4d6b1a0f3c7e9d2b8a4f6c1e0d3b7a99//services/auth.

Snapshot Changes

CLI
TypeScript

$ tl git snapshot /work -m "implemented parser and tests"
Snapshot 8b21f6a9c3d5 retained permanently.

await mount.snapshot("implemented parser and tests");

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:

CLI
TypeScript

$ tl git snapshot /work
Snapshot 8b21f6a9c3d5 retained permanently.

await mount.snapshot();

A clean snapshot mints no new commit; it reports the snapshot already at the workspace tip.

Promote to a Branch

CLI
TypeScript

$ tl git promote /work main
Snapshot 8b21f6a9c3d5 retained permanently.
Promoted workspace 3f9a2b7e1c4d -> refs/heads/main at 1c4d9a2f7e5b.

await mount.promote("main");

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, or pass { merge: true } to mount.promote(), 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:

CLI
TypeScript

$ tl git rebase /work main
Rebased workspace onto main (3 path(s) changed).

await mount.rebase("main");

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, or pass { failOnConflict: true } to mount.rebase(), to report conflicts without materializing markers into the workspace.

Refresh a Mount

Refresh the current source, or switch a workspace without snapshots to another branch, tag, or full commit:

CLI
TypeScript

tl git sync /work
# To switch the base:
tl git sync /work feature

await mount.sync();
// To switch the base:
await mount.sync("feature");

Changing a snapshotted workspace’s base requires a rebase. Publish mounts cannot be retargeted or rebased.

Prefetch Files

Download and verify the mounted working set so subsequent reads do not need to fetch file content. Make sure the machine has enough local disk for that content.

CLI
TypeScript

tl git prefetch /work

await mount.prefetch();

Check Status

CLI
TypeScript

$ 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 <BRANCH>
next: tl git rebase <REF-OR-COMMIT>

const status = await mount.status();
console.log(status.workspaceId, status.state, status.localChanges);

// Without a mount handle:
console.log(await repos.mountStatus("./work"));

status() also returns path, repository, and reference, with the complete CLI JSON in raw. repos.mountStatus() defaults to the mount containing the current directory. 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:

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:

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
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:

CLI
TypeScript

$ tl git unmount /work
Unmounted /work.

await mount.unmount();
// Without a mount handle, use repos.unmount("./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 <repo> lists them; mount and status print an abbreviation):

CLI
TypeScript

$ tl git mount agent-outputs /work2 --workspace 3f9a2b7e1c4d5e7f1a2b4c6d8e0f3a5b7c9d1e3f
Mounted repository agent-outputs at /work2 (workspace 3f9a2b7e1c4d).

const resumed = await repos.mount("agent-outputs", "./work-resumed", {
  workspace: "YOUR_SAVED_WORKSPACE_ID",
});

try {
  console.log(await resumed.status());
} finally {
  await resumed.unmount();
}

Save status.workspaceId after the first autosaved write or snapshot to resume later. It is null before a private workspace exists, and stays null for read-only views.

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:

CLI
TypeScript

$ tl git unmount /work --delete
Unmounted /work.

await mount.unmount({ deleteWorkspace: true });

The workspace WAL and unpublished snapshots become unreachable. Promote first if the work should survive as branch history. Use tl git unmount /work --discard, or mount.unmount({ discard: true }), to drop unpublished local state. 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.

Errors

SDK CLI discovery failures raise CliNotFoundError. Failed CLI operations and malformed status JSON raise MountError. Both errors are exported from tensorlake. The SDK passes its selected API key and API URL to the CLI and looks for TENSORLAKE_CLI, tl on PATH, then ~/.tensorlake/bin/tl. SDK mounts require an API key even if you previously authenticated the CLI with a personal access token.

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

Prerequisites

Choose a Mount

Writable Mounts (the Default)

Autosave WAL

Read-Only Mounts

Snapshot Changes

Promote to a Branch

Rebase a Workspace

Refresh a Mount

Prefetch Files

Check Status

Observe Workspaces

Reattach a Workspace

Delete a Workspace

What a Mount Is Not

Errors

Next Steps

Merging Changes

Architecture

​Prerequisites

​Choose a Mount

​Writable Mounts (the Default)

​Autosave WAL

​Read-Only Mounts

​Snapshot Changes

​Promote to a Branch

​Rebase a Workspace

​Refresh a Mount

​Prefetch Files

​Check Status

​Observe Workspaces

​Reattach a Workspace

​Delete a Workspace

​What a Mount Is Not

​Errors

​Next Steps

Merging Changes

Architecture

Prerequisites

Choose a Mount

Writable Mounts (the Default)

Autosave WAL

Read-Only Mounts

Snapshot Changes

Promote to a Branch

Rebase a Workspace

Refresh a Mount

Prefetch Files

Check Status

Observe Workspaces

Reattach a Workspace

Delete a Workspace

What a Mount Is Not

Errors

Next Steps