> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensorlake.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Writable Workspaces

> Mount a private or shared writable workspace, snapshot agent changes, and promote finished work to a branch.

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

```bash theme={null}
$ 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

```bash theme={null}
$ 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:

```bash theme={null}
$ tl fs snapshot /work
Nothing to snapshot: workspace is clean.
```

## Promote to a Branch

```bash theme={null}
$ 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:

```bash theme={null}
$ 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.

```bash theme={null}
$ 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

<CardGroup cols={2}>
  <Card title="Manage Workspaces" icon="arrows-rotate" href="/filesystems/manage-workspaces">
    Inspect dirty files, reattach, clean up, diff, and restore.
  </Card>

  <Card title="Architecture" icon="cubes" href="/filesystems/architecture">
    Learn how promotion and merge conflict handling work internally.
  </Card>
</CardGroup>