Tensorlake Documentation

Agents produce state and artifacts worth keeping: code, documents, artifacts, working notes. Volumes can be mounted as a directory on the file system into a sandbox, all writes are automatically saved in durable storage asynchronously. They offer SSD grade write performance, and reads are cached and can be fetched either lazily or pre-fetched from remote storage. These directories can be snapshotted to create point-in-time checkpoints and can be time travelled to restore state at a given time. Volumes can be used on any sandbox provider or AWS/GCP/Azure or even Kubernetes containers. They are portable directories that can be mounted on any Linux or OSX machines. These are some use cases for versioned file systems:

Version an agent’s working state without teaching it version control
Persist a long-running session so a crashed sandbox loses nothing
Share one file system across several coding agents at once. Disjoint work merges automatically
Distribute documents, skills, and tools to fleets of agents with read-only mounts

Quickstart

Install the Tensorlake CLI and sign in:

curl -fsSL https://tensorlake.ai/install | sh
tl login

Then create a file system, mount it, and watch changes save themselves.

Create a file system

CLI
Python
TypeScript

$ tl fs create agent-scratch
Created filesystem agent-scratch (empty).
  mount it: tl fs mount agent-scratch <path>
  or push a folder: tl fs push <dir> agent-scratch

from tensorlake.filesystem import FilesystemClient

client = FilesystemClient()
fs = client.create("agent-scratch")

import { FilesystemClient } from "tensorlake";

const client = new FilesystemClient();
const fs = await client.create("agent-scratch");

A new empty file system is created on our servers. It’s ready to be mounted immediately on a sandbox or machine.

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 pathlib import Path

# Tilde paths are not expanded by the SDK; pass a resolved path.
mount = fs.mount(str(Path.home() / "work"))

import { homedir } from "node:os";
import { join } from "node:path";

// Tilde paths are not expanded by the SDK; pass a resolved path.
const mount = await fs.mount(join(homedir(), "work"));

The file system is mounted at ~/work on the local machine. It’s a normal POSIX compliant directory. You can write to the file system through the Python or TypeScript SDKs without mounting them. The SDKs use the HTTP API of the remote file system directly.

Work in it

Write into the mounted directory with POSIX read/write APIs. if you use the Python/TypeScript SDKs, writes go straight to the file system without a mount.

CLI
Python
TypeScript

$ echo "hypothesis: the parser is quadratic" > /work/notes.md
$ mkdir /work/results && cp bench.json /work/results/

fs.write_file("notes.md", "hypothesis: the parser is quadratic\n")

import { readFile } from "node:fs/promises";

await fs.writeFile("notes.md", "hypothesis: the parser is quadratic\n");
await fs.writeFile("results/bench.json", await readFile("bench.json"));

The writes are asynchronously replicated to Tensorlake’s remote file system. The server dvances the file-system timeline.The file systems can be mounted on multiple machines at once. The other mounts will see the changes within seconds.You can create create a permanent snapshot to create a point in time checkpoint of the file system. You can time travel across the snapshots, restore a specific checkpoint or fork the file system from that point.

CLI
Python
TypeScript

$ tl fs snapshot /work -m "baseline benchmarks"

mount.snapshot("baseline benchmarks")

await mount.snapshot("baseline benchmarks");

Check status and history

CLI
Python
TypeScript

$ tl fs status /work
filesystem: agent-scratch
session: 54398548341c (created 5m 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
local: clean

status = mount.status()
print(status.filesystem, status.mounted)

const status = await mount.status();
console.log(status.filesystem, status.mounted);

History is browsed with the CLI:

$ 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  4m ago

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

local: clean means the local journal has no changes waiting for autosave. History separates permanent snapshots from recent autosave recovery points.

Resume on another machine

The mount path is disposable; the session behind it is durable. If the sandbox crashes or you unmount and walk away, remount the file system and pick up from its last durable state:

CLI
Python
TypeScript

$ tl fs mount agent-scratch /work2
Resumed session 54398548341c

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

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

From another machine you recover everything through the last autosave checkpoint, and because autosave is frequent, that is typically seconds of work at most; anything written since the last checkpoint stays on the machine that wrote it. Remounting on the same machine can additionally recover a detached session’s unsaved local changes from its overlay.

Push a Folder Without Mounting

When you just want a directory’s contents in a file system, you can push the directory into the file system:

$ tl fs push ./results agent-scratch -m "run 42 results"
Pushed ./results to agent-scratch (14 file(s)).

Pushing the same directory again uploads only what changed. Passing -m creates a permanent snapshot.

Mental Model

A file system is the durable, versioned store.
A mount gives a sandbox an ordinary directory backed by it.
A session is the state behind one mount — resumable after crashes and unmounts.
An autosave checkpoint replicates settled work through a session WAL and advances the shared timeline before it is acknowledged.
A snapshot with new changes keeps that generation as a permanent, billed retention point until you delete it. A clean snapshot is a quiet no-op.
Other mounts converge as acknowledged autosaves or permanent snapshots advance the shared timeline.

See Core Concepts for short definitions of each term.

Summary of Features

Autosave: settled changes replicate through durable server WAL and into the shared timeline automatically; a continuously-writing agent still checkpoints at a bounded interval.
Permanent snapshots and history: browse both kinds of history with tl fs history; create a permanent, billed point with tl fs snapshot and remove it with tl fs delete-snapshot.
Time travel: restore the mount to any retained autosave or permanent snapshot with tl fs restore.
Durable sessions: crash a sandbox and remount elsewhere to recover through the last server autosave. On the same machine, the local journal can also recover changes that had not reached the server yet.
Shared file systems: many writers on one file system; server-ordered disjoint changes merge automatically, same-path writes are last-writer-wins.
Read-only mounts: serve a fixed snapshot or follow the file system’s current state across many running sandboxes.

Use Cases

Distribute Files to Agents

Roll out manuals, skills, configs, and tools to many agents with versioned read-only mounts.

Store Agent-Generated Code

Prefer a Git repository when generated projects need branches and explicit publication.

Where To Go Next

Core Concepts

Learn the vocabulary: file systems, mounts, sessions, autosave checkpoints, snapshots, and publishing.

File System Mounts

Choose between writable and read-only mounts.

Manage Sessions

Inspect status, resume, restore an earlier checkpoint or snapshot, and clean up.

Concurrent Writes

How several mounts writing at once reconcile — disjoint paths merge, same-path is last-writer-wins.

Overview

Guides

Reference

Use Cases

Cloud Volumes

Quickstart

Push a Folder Without Mounting

Mental Model

Summary of Features

Use Cases

Distribute Files to Agents

Store Agent-Generated Code

Where To Go Next

Core Concepts

File System Mounts

Manage Sessions

Concurrent Writes

​Quickstart

​Push a Folder Without Mounting

​Mental Model

​Summary of Features

​Use Cases

Distribute Files to Agents

Store Agent-Generated Code

​Where To Go Next

Core Concepts

File System Mounts

Manage Sessions

Concurrent Writes

Quickstart

Push a Folder Without Mounting

Mental Model

Summary of Features

Use Cases

Where To Go Next