> ## 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.

# File System Mounts

> Choose the right Git-backed file system mount for agent workspaces, shared branches, fixed inputs, and branch-following assets.

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.

<Note>
  Install the file-system extension once on macOS. Linux needs no setup.

  ```bash theme={null}
  tl fs setup --check
  tl fs setup
  ```
</Note>

## Choose a Mode

Every mode uses the same command shape:

```bash theme={null}
tl fs mount <repo>[:<ref-or-commit>] <path>
```

| Mode                        | Command                                                 | Use it for                                            |
| --------------------------- | ------------------------------------------------------- | ----------------------------------------------------- |
| Private writable workspace  | `tl fs mount agent-outputs:main /work`                  | One agent working privately before promotion          |
| Shared read-write workspace | `tl fs mount agent-outputs:main /work --shared-rw`      | Multiple agents whose snapshots publish to the branch |
| Pinned read-only mount      | `tl fs mount agent-outputs:<commit> /release --mode ro` | Reproducible builds, evals, and fixed releases        |
| Following read-only mount   | `tl fs mount agent-outputs:main /skills --mode ro`      | Shared 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.

```bash theme={null}
tl fs mount agent-outputs:main /work
```

See [Writable Workspaces](/filesystems/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.

```bash theme={null}
tl fs mount agent-outputs:main /skills --mode ro
```

See [Read-only Mounts](/filesystems/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.

```bash theme={null}
tl fs status /work
tl fs ls
tl fs restore /work <snapshot>
```

See [Manage Workspaces](/filesystems/manage-workspaces).

## Plain Git Boundary

`tl fs` manages workspaces. Plain branches, pull-style collaboration, and CI are ordinary Git workflows. See [Git Repositories](/filesystems/git-repositories).

Workspace refs such as `refs/workspaces/...` are reserved on the server and cannot be updated with direct `git push`.

<CardGroup cols={2}>
  <Card title="Writable Workspaces" icon="pen-line" href="/filesystems/writable-workspaces">
    Mount, snapshot, and promote agent work.
  </Card>

  <Card title="Read-only Mounts" icon="lock" href="/filesystems/read-only-mounts">
    Use pinned and following mounts for fixed inputs and shared assets.
  </Card>

  <Card title="Distribute Files" icon="package-open" href="/filesystems/distribute-files">
    Roll out manuals, skills, configs, and tools to agent fleets.
  </Card>

  <Card title="Generated Code" icon="code-branch" href="/filesystems/store-generated-code">
    Store generated apps, docs, and assets with snapshots and activity history.
  </Card>

  <Card title="Manage Workspaces" icon="arrows-rotate" href="/filesystems/manage-workspaces">
    Inspect, reattach, clean up, diff, and restore workspaces.
  </Card>

  <Card title="Core Concepts" icon="book-open" href="/filesystems/core-concepts">
    Repositories, workspaces, mounts, snapshots, and promotion.
  </Card>
</CardGroup>