Tensorlake Documentation

A mount path is ephemeral. Server autosaves and permanent snapshots are the durable state behind it. A writable session also owns a local crash-safe journal, so the same machine can recover changes that had not reached the server when the mount stopped. Use these commands, or their SDK equivalents, to inspect a session, resume it, browse its history, get back to an earlier snapshot’s contents, or delete a file system.

Check Status

CLI
Python
TypeScript

$ tl fs status /work
filesystem: agent-scratch
session: 54398548341c (created 12m ago)
mode: writable — every save becomes the filesystem's current state
autosave: settled changes replicate in about 1s (5s max while continuously writing)
last autosave: 2m ago
permanent snapshots: 1
daemon: serving save 8b21f6a9
log: ~/.local/share/tensorlake/mounts/54398548341c.../daemon.log
local: clean

from tensorlake.filesystem import FilesystemClient

client = FilesystemClient()

status = client.mount_status("/work")
print(status.filesystem, status.mounted)

import { FilesystemClient } from "tensorlake";

const client = new FilesystemClient();

const status = await client.mountStatus("/work");
console.log(status.filesystem, status.mounted);

With unsaved changes, status lists dirty paths:

local: 2 change(s):
  M src/parser.py
  D src/old_parser.py

Two more lines appear as a session ages:

retained: counts files already published and kept locally as the byte cache. They are durable; the local copies only make reads and future autosaves fast.
ignored: counts local-only files that never enter an autosave or snapshot (build output and the like, per the file system’s ignore rules).

Add --json for machine-readable output; the SDK’s MountStatus.raw carries the same structured payload.

Browse History

$ tl fs history agent-scratch
Autosave WAL (fixed native_fs_v1): each checkpoint is synchronously replicated to the shared drive; keep the newest 256 generations and all generations from the last 24h. Snapshots are permanent until you delete them.

Snapshots (permanent — kept until deleted)
4d9a2f7e  baseline benchmarks  1h ago

Recent autosave WAL (ephemeral — truncated automatically)
8b21f6a9  2m ago
e3f421a7  3h ago

Autosaves provide a recent recovery window. Create a permanent, billed snapshot as part of the changed generation you need to keep:

CLI
Python
TypeScript

$ tl fs snapshot /work -m "baseline benchmarks"
Snapshot 4d9a2f7e "baseline benchmarks" — kept until deleted.

mount.snapshot("baseline benchmarks")

await mount.snapshot("baseline benchmarks");

Permanent snapshots are exempt from automatic retention. Snapshotting a clean mount promotes its current automatic save to permanent retention in place, without uploading file bytes or creating a duplicate content version. It is a quiet no-op only when the current save is already permanent. Drop a permanent snapshot you no longer need with tl fs delete-snapshot agent-scratch <snapshot-id>.

List Sessions

$ tl fs ls agent-scratch
Session        Filesystem      Base       Saves   Mode         Mounted   Age
54398548341c   agent-scratch   e3f421a7   yes     publishing   /work     12m

tl fs ls with no argument lists your file systems.

Resume a Session

Unmounting keeps the session by default:

CLI
Python
TypeScript

$ tl fs unmount /work
Unmounted /work. Session 54398548341c kept — `tl fs mount agent-scratch <path>` resumes it.

mount.unmount()
# or, without a Mount object: client.unmount("/work")

await mount.unmount();
// or, without a mount object: await client.unmount("/work");

Remounting the file system on a machine that has a detached session resumes that session, unsaved local changes included. The new mount path can be different:

CLI
Python
TypeScript

$ tl fs mount agent-scratch /work2
Resumed session 54398548341c at its last durable checkpoint.

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

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

Discard Local Changes

Throw away unsaved changes (and ignored files under the mount) with the mount:

CLI
Python
TypeScript

$ tl fs unmount /work --discard
Unmounted /work (unsaved local changes discarded).

mount.unmount(discard=True)

await mount.unmount(true);

Everything already published is untouched: autosave checkpoints and snapshots are immutable.

Access Historical State

Autosave checkpoints and permanent snapshots are immutable, and the shared timeline only moves forward — there is no in-place restore. To get back to an earlier state, fork the file system at that snapshot. A fork is metadata-only: the server shares the immutable content and publishes only metadata, so no file bytes are copied.

Python
TypeScript

fork = client.fork(
    "agent-scratch-baseline",
    "agent-scratch",
    "4d9a2f7e5b3d8c6a4f2e0d9b7c5a3f1e8d6b4c2a1029384756abcdef01234567",
)

const fork = await client.fork(
  "agent-scratch-baseline",
  "agent-scratch",
  "4d9a2f7e5b3d8c6a4f2e0d9b7c5a3f1e8d6b4c2a1029384756abcdef01234567",
);

Mount the fork (or mount it read_only into sandboxes) to work from the historical state. You can fork at the live head or at any retained point — a permanent snapshot, or an autosave still inside the retention window. To read individual files at a historical point without mounting anything, pass the snapshot to the SDK’s read APIs:

Python
TypeScript

fs = client.get("agent-scratch")
data = fs.read_file("results/bench.json", version="4d9a2f7e5b3d...")

const fs = await client.get("agent-scratch");
const data = await fs.readFile("results/bench.json", "4d9a2f7e5b3d...");

Inspect a Session

If a session’s local state is ever inconsistent (a hard sandbox kill mid-write, an interrupted resume), tl fs doctor inspects the crash-safe local session state and reports problems:

$ tl fs doctor /work --json

Doctor only reads local session state; durable history is never touched.

Delete a File System

CLI
Python
TypeScript

$ tl fs rm agent-scratch
Delete filesystem agent-scratch and all of its history? This cannot be undone. [y/N]

client.delete("agent-scratch")

await client.delete("agent-scratch");

Pass -f to skip the confirmation; the SDK clients delete without prompting. Deletion removes the file system, its history, and its sessions.

Overview

Guides

Reference

Use Cases

Manage Sessions

Check Status

Browse History

List Sessions

Resume a Session

Discard Local Changes

Access Historical State

Inspect a Session

Delete a File System

​Check Status

​Browse History

​List Sessions

​Resume a Session

​Discard Local Changes

​Access Historical State

​Inspect a Session

​Delete a File System

Check Status

Browse History

List Sessions

Resume a Session

Discard Local Changes

Access Historical State

Inspect a Session

Delete a File System