Skip to main content
A file system mount exposes Git-backed content as an ordinary directory. The mount mode controls whether the directory is writable and whether it follows future branch updates. Start with a private writable workspace unless snapshots should publish immediately or the mount should be read-only.
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 <repo>[:<ref-or-commit>] <path>
ModeCommandUse it for
Private writable workspacetl fs mount agent-outputs:main /workOne agent working privately before promotion
Shared read-write workspacetl fs mount agent-outputs:main /work --shared-rwMultiple agents whose snapshots publish to the branch
Pinned read-only mounttl fs mount agent-outputs:<commit> /release --mode roReproducible builds, evals, and fixed releases
Following read-only mounttl fs mount agent-outputs:main /skills --mode roShared skills, prompts, docs, configs, and assets

​
Writable Workspaces

Writable workspaces are for agent sessions that create or modify files. The agent writes in the mount, snapshots progress, and promotes finished work to a branch. 
tl fs mount agent-outputs:main /work
See Writable Workspaces.

​
Read-only Mounts

Read-only mounts are for inputs and shared assets. Pin to a commit for reproducibility, or follow a branch to roll out updates to many sandboxes. 
tl fs mount agent-outputs:main /skills --mode ro
See Read-only Mounts.

​
Workspace Operations

Use workspace operations to inspect dirty files, reattach after a sandbox restart, clean up old workspaces, diff snapshots, and restore an earlier state. 
tl fs status /work
tl fs ls
tl fs restore /work <snapshot>
See Manage Workspaces.

​
Plain Git Boundary

tl fs manages workspaces. Plain branches, pull-style collaboration, and CI are ordinary Git workflows. See Git Repositories. Workspace refs such as refs/workspaces/... are reserved on the server and cannot be updated with direct git push.

Writable Workspaces

Mount, snapshot, and promote agent work.

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.

Generated Code

Store generated apps, docs, and assets with snapshots and activity history.

Manage Workspaces

Inspect, reattach, clean up, diff, and restore workspaces.

Core Concepts

Repositories, workspaces, mounts, snapshots, and promotion.