File System Mounts

Choose the right versioned file system mount for agent work, fixed inputs, and shared assets.

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

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.

Mount the filesystem:

CLI

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

Python

from tensorlake.filesystem import FilesystemClient

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

TypeScript

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.

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.