> ## 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 versioned file system mount for agent work, shared branches, fixed inputs, and branch-following assets.

A file system mount exposes repository content as an ordinary directory in a sandbox. The mount path is ephemeral. For writable mounts, Tensorlake creates a workspace behind the path and snapshots persist file state into that workspace.

Start with a private writable mount 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 mount    | `tl fs mount agent-outputs:main /work`                  | One agent working privately before promotion          |
| Shared read-write mount   | `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 Mounts

Writable mounts are for agent sessions that create or modify files. The agent writes files in the mount, snapshots persist progress to the workspace, and promotion publishes finished work to a branch.

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

See [Writable Mounts](/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 the persisted workspace 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 Mounts" 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>