Tensorlake Documentation

A file system mount exposes a versioned file system as an ordinary directory on your machine or in a sandbox. The mount path is ephemeral. For writable mounts, Tensorlake replicates settled changes through a durable server WAL into the shared file system. Start with a writable mount unless the sandbox should not write.

Choose Where to Mount

Choose the API based on what you want to mount and where you want the directory to appear:

Mount	TypeScript API	Where it appears	Local CLI required?
Tensorlake filesystem in a sandbox	`Sandbox.create({ fileSystems: [...] })` or `sandbox.attachFileSystem()`	Inside the Tensorlake sandbox	No
Tensorlake filesystem on the current machine	`FilesystemClient.mount(name, path)`	On the machine running Node.js	Yes
Git repository on the current machine	`RepositoryClient.mount(target, path, options)`	On the machine running Node.js	Yes

Local filesystem mounts are writable. Passing true as the third argument to FilesystemClient.mount() raises ReadOnlyMountNotSupportedError. Use a read-only sandbox filesystem mount for shared filesystem inputs, or a read-only Git mount for repository content. Sandbox filesystem mounts also support snapshot pins.

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

tl fs setup --check
tl fs setup

Choose a Mode

Mode	Command	Use it for
Writable mount	`tl fs mount agent-scratch /work`	Agents creating or modifying files; autosaves become durable automatically
Read-only sandbox mount	`tl sbx create -f agent-scratch:/skills:ro`	Shared skills, prompts, docs, configs, and assets
Read-only repository view	`tl git mount agent-outputs:<full-commit> /release --ro`	Reproducible builds, evals, and fixed releases from a Git repository

tl fs mount itself is always writable: a file system is the shared writable surface, so read-only is expressed where the consumer attaches — as a read_only sandbox mount — while --ro lives on tl git mount, where read-only views are a repository concept.

Writable Mounts

Writable mounts are for agent sessions that create or modify files. The agent writes files in the mount; writes enter a crash-safe local journal and settled changes replicate as durable server WAL checkpoints. The server applies each acknowledged checkpoint to the shared timeline. Create the filesystem first and install and authenticate the CLI or SDK. Local SDK mounts also require the separately installed tl CLI with filesystem mount support. Then mount it:

CLI
Python
TypeScript

$ tl fs mount agent-scratch /work
Mounted filesystem agent-scratch at /work (session 54398548341c, saves publish automatically)
At save e3f421a78c8cbba09c79294131835fe0da8b4433a1b2c3d4e5f60718293a4b5c. Changes save automatically; tl fs snapshot /work makes a permanent snapshot.
Autosave: settled changes replicate in about 1s (5s max while continuously writing).

from tensorlake.filesystem import FilesystemClient

client = FilesystemClient()
mount = client.mount("agent-scratch", "/work")

import { FilesystemClient } from "tensorlake";
import { writeFile } from "node:fs/promises";
import { join, resolve } from "node:path";

const client = new FilesystemClient();
const mount = await client.mount("agent-scratch", resolve("./work"));

try {
  await writeFile(join(mount.path, "notes.txt"), "Agent working notes\n");
  await mount.snapshot("Save working notes");
  console.log(await mount.status());
} finally {
  await mount.unmount();
}

The TypeScript handle exposes snapshot(message?), status(), and unmount(discard?). unmount() keeps recoverable session state; pass true only to discard changes not yet uploaded. See Manage Sessions for mounting again and inspecting existing mounts. Autosave is always on for writable mounts. Changes normally reach the shared timeline about 750ms after they settle plus upload/server time; a continuously-writing agent checkpoints at least every 5 seconds. The server does not acknowledge the checkpoint until verification and shared-head publication complete. tl fs snapshot /work -m "..." keeps the command’s exact state permanently and returns only after the durable snapshot receipt exists. If autosave already published that state, the server promotes the existing automatic save in place—no file bytes are uploaded and no duplicate content version is created. You can safely unmount as soon as the command succeeds. It is a quiet no-op only when the current save is already permanent. Remounting a file system this machine has a detached session for resumes that session, unsaved local changes included.

Read-only Mounts

Read-only mounts are for inputs and shared assets: follow the current state to roll out updates to many consumers, or pin a fixed version for reproducibility. Read-only is expressed on the consumer, not on tl fs mount:

Sandboxes: pass read_only on the mount when creating the sandbox (or attaching to a running one). The guest directory follows the file system’s current state and refuses writes with EROFS, enforced down to the storage credential.
tl sbx create -f agent-scratch:/skills:ro
See Mount Filesystems for the Python, TypeScript, and HTTP equivalents.
Git repositories: tl git mount --ro gives a stateless read-only view of a branch, a pinned commit, or a subtree:
tl git mount agent-outputs /code --ro

For pinning a file system to an exact release, fork it at a permanent snapshot and mount the fork read-only. See Read-only Mounts.

Session Operations

Use session operations to inspect local changes, resume after a sandbox restart, browse history, create permanent snapshots, inspect a session, and clean up.

tl fs status /work                       # unsaved changes, retained + ignored counts
tl fs snapshot /work -m "milestone"      # permanent snapshot
tl fs history agent-scratch              # browse the timeline
tl fs delete-snapshot agent-scratch <id>  # remove a permanent snapshot
tl fs doctor /work                       # inspect local session state

To get back to an earlier snapshot’s contents, fork the file system at that snapshot with the SDK’s fork, or read individual files at a snapshot with read_file(path, version=...). See Manage Sessions. See Manage Sessions.

Mounting in Sandboxes

The simplest way to mount a file system into a Tensorlake sandbox is through the sandbox API: pass the file system’s name and a mount path when creating the sandbox (or attach it to a running one), and the mount appears as an ordinary directory with no credentials to manage:

tl sbx create -f agent-scratch:/work

Per-mount read_only and prefetch options are available. See Mount Filesystems for the full guide, including warm-pool claims and runtime attach/detach. Alternatively, mount from inside the guest with the same tl fs mount commands. The guest needs one scoped credential to attach a file system:

$ tl fs token agent-scratch

The command prints the credential and the environment recipe for the guest.

Read-only Mounts

Use pinned and following mounts for fixed inputs and shared assets.

Distribute Files

Roll out manuals, skills, configs, and tools to agent fleets.

Manage Sessions

Inspect status, resume, restore, and clean up.

Core Concepts

File systems, mounts, sessions, autosave checkpoints, snapshots, and publishing.

Overview

Guides

Reference

Use Cases

File System Mounts

Choose Where to Mount

Choose a Mode

Writable Mounts

Read-only Mounts

Session Operations

Mounting in Sandboxes

Read-only Mounts

Distribute Files

Manage Sessions

Core Concepts

​Choose Where to Mount

​Choose a Mode

​Writable Mounts

​Read-only Mounts

​Session Operations

​Mounting in Sandboxes

Read-only Mounts

Distribute Files

Manage Sessions

Core Concepts

Choose Where to Mount

Choose a Mode

Writable Mounts

Read-only Mounts

Session Operations

Mounting in Sandboxes