Skip to main content
Use a writable workspace when an agent needs to create or edit files. The default mode is private: writes stay isolated until you promote them.

​
Mount a Private Workspace

$ tl fs mount agent-outputs:main /work
Mounted agent-outputs:main at /work (workspace 3f9a2b7e1c4d)
/work is now an ordinary writable directory. The workspace starts from main, but changes do not affect main yet.

​
Snapshot Changes

$ tl fs snapshot /work -m "implemented parser and tests"
Snapshot 8b21f6a9c3d5e7f1a2b4c6d8e0f3a5b7c9d1e3f5 (14 file(s), 14 of 14 chunks uploaded)
A snapshot is a commit on the workspace. Snapshotting with no changes is a no-op: 
$ tl fs snapshot /work
Nothing to snapshot: workspace is clean.

​
Promote to a Branch

$ tl fs promote /work main -m "parser and tests"
Promoted workspace 3f9a2b7e1c4d -> main at 1c4d9a2f7e5b3d8c6a4f2e0d9b7c5a3f1e8d6b4c (squashed)
By default, promotion publishes one clean commit to the target branch. Future agents that mount that branch, and Git users who clone or fetch it, get that version. Following read-only mounts pick up the update automatically. Activity history shows who published the promotion and which workspace it came from. Use --full-history when you want every workspace snapshot to land as its own commit: 
$ tl fs promote /work main --full-history
Promoted workspace 3f9a2b7e1c4d -> main at 1c4d9a2f7e5b3d8c6a4f2e0d9b7c5a3f1e8d6b4c (full history)

​
Shared Read-write Workspaces

Use --shared-rw when every snapshot should publish to the target branch automatically. 
$ tl fs mount agent-outputs:main /work --shared-rw
Mounted agent-outputs:main at /work (workspace 3f9a2b7e1c4d, snapshots auto-publish to the branch)
This mode is for fleets that cannot wait for a manual promotion step. It requires a branch target and is incompatible with --mode ro.

​
Next Steps

Manage Workspaces

Inspect dirty files, reattach, clean up, diff, and restore.

Architecture

Learn how promotion and merge conflict handling work internally.