Tensorlake Documentation

A file system mount exposes a versioned file system as an ordinary directory 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.

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

tl fs setup --check
tl fs setup

Choose a Mode

Every mode uses the same command shape:

tl fs mount <filesystem>[:<snapshot-or-autosave-id>] <path>

Mode	Command	Use it for
Writable mount	`tl fs mount agent-scratch /work`	Agents creating or modifying files; autosaves become durable automatically
Read-only, following	`tl fs mount agent-scratch /skills --ro`	Shared skills, prompts, docs, configs, and assets
Read-only, pinned	`tl fs mount agent-scratch:<snapshot-id> /release --ro`	Reproducible builds, evals, and fixed releases

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. Mount the filesystem:

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";

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

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. A session already mounted elsewhere mounts read-only.

Read-only Mounts

Read-only mounts are for inputs and shared assets. Follow the file system’s current state to roll out updates to many sandboxes, or pin a permanent snapshot for reproducibility.

CLI
Python
TypeScript

tl fs mount agent-scratch /skills --ro

mount = client.mount("agent-scratch", "/skills", readonly=True)

const mount = await client.mount("agent-scratch", "/skills", true);

See Read-only Mounts.

Session Operations

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

tl fs status /work                       # unsaved changes, retained + ignored counts
tl fs snapshot /work -m "milestone"      # permanent snapshot (--clear also trims its retained byte cache)
tl fs history agent-scratch              # browse the timeline
tl fs delete-snapshot agent-scratch <id>  # remove a permanent snapshot
tl fs restore /work <id>                 # restore a snapshot or retained autosave
tl fs doctor /work                       # inspect / repair local session state

See Manage Sessions.

Mounting in Sandboxes

A sandbox 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. Inside the sandbox, the same tl fs mount commands work unchanged.

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 a Mode

Writable Mounts

Read-only Mounts

Session Operations

Mounting in Sandboxes

Read-only Mounts

Distribute Files

Manage Sessions

Core Concepts

​Choose a Mode

​Writable Mounts

​Read-only Mounts

​Session Operations

​Mounting in Sandboxes

Read-only Mounts

Distribute Files

Manage Sessions

Core Concepts

Choose a Mode

Writable Mounts

Read-only Mounts

Session Operations

Mounting in Sandboxes