> ## 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, fixed inputs, and shared assets.

A file system mount exposes a versioned file system as an ordinary directory in a sandbox. The mount path is ephemeral. For writable mounts, Tensorlake replicates settled changes through a durable server WAL into the shared file system.

Start with a writable mount unless the sandbox should not write.

<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

| Mode                      | Command                                                  | Use it for                                                                                    |
| ------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Writable mount            | `tl fs mount agent-scratch /work`                        | Agents creating or modifying files; autosaves become durable automatically                    |
| Read-only sandbox mount   | `tl sbx create -f agent-scratch:/skills:ro`              | Shared skills, prompts, docs, configs, and assets                                             |
| Read-only repository view | `tl git mount agent-outputs:<full-commit> /release --ro` | Reproducible builds, evals, and fixed releases from a [Git repository](/git/workspace-mounts) |

`tl fs mount` itself is always writable: a file system is the shared writable surface, so read-only is expressed where the consumer attaches — as a `read_only` [sandbox mount](/sandboxes/mount-filesystems#read-only) — while `--ro` lives on `tl git mount`, where read-only views are a repository concept.

## Writable Mounts

Writable mounts are for agent sessions that create or modify files. The agent writes files in the mount; writes enter a crash-safe local journal and settled changes replicate as durable server WAL checkpoints. The server applies each acknowledged checkpoint to the shared timeline.

Mount the filesystem:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    $ tl fs mount agent-scratch /work
    Mounted filesystem agent-scratch at /work (session 54398548341c, saves publish automatically)
    At save e3f421a78c8cbba09c79294131835fe0da8b4433a1b2c3d4e5f60718293a4b5c. Changes save automatically; tl fs snapshot /work makes a permanent snapshot.
    Autosave: settled changes replicate in about 1s (5s max while continuously writing).
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from tensorlake.filesystem import FilesystemClient

    client = FilesystemClient()
    mount = client.mount("agent-scratch", "/work")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { FilesystemClient } from "tensorlake";

    const client = new FilesystemClient();
    const mount = await client.mount("agent-scratch", "/work");
    ```
  </Tab>
</Tabs>

Autosave is always on for writable mounts. Changes normally reach the shared timeline about 750ms after they settle plus upload/server time; a continuously-writing agent checkpoints at least every 5 seconds. The server does not acknowledge the checkpoint until verification and shared-head publication complete. `tl fs snapshot /work -m "..."` keeps the command's exact state permanently and returns only after the durable snapshot receipt exists. If autosave already published that state, the server promotes the existing automatic save in place—no file bytes are uploaded and no duplicate content version is created. You can safely unmount as soon as the command succeeds. It is a quiet no-op only when the current save is already permanent.

Remounting a file system this machine has a detached session for resumes that session, unsaved local changes included.

## Read-only Mounts

Read-only mounts are for inputs and shared assets: follow the current state to roll out updates to many consumers, or pin a fixed version for reproducibility. Read-only is expressed on the consumer, not on `tl fs mount`:

* **Sandboxes**: pass `read_only` on the mount when creating the sandbox (or attaching to a running one). The guest directory follows the file system's current state and refuses writes with `EROFS`, enforced down to the storage credential.

  ```bash theme={null}
  tl sbx create -f agent-scratch:/skills:ro
  ```

  See [Mount Filesystems](/sandboxes/mount-filesystems#read-only) for the Python, TypeScript, and HTTP equivalents.

* **Git repositories**: `tl git mount --ro` gives a stateless read-only view of a branch, a pinned commit, or a subtree:

  ```bash theme={null}
  tl git mount agent-outputs /code --ro
  ```

For pinning a file system to an exact release, fork it at a permanent snapshot and mount the fork read-only. See [Read-only Mounts](/filesystems/read-only-mounts).

## Session Operations

Use session operations to inspect local changes, resume after a sandbox restart, browse history, create permanent snapshots, inspect a session, and clean up.

```bash theme={null}
tl fs status /work                       # unsaved changes, retained + ignored counts
tl fs snapshot /work -m "milestone"      # permanent snapshot
tl fs history agent-scratch              # browse the timeline
tl fs delete-snapshot agent-scratch <id>  # remove a permanent snapshot
tl fs doctor /work                       # inspect local session state
```

To get back to an earlier snapshot's contents, fork the file system at that snapshot with the SDK's `fork`, or read individual files at a snapshot with `read_file(path, version=...)`. See [Manage Sessions](/filesystems/manage-sessions#access-historical-state).

See [Manage Sessions](/filesystems/manage-sessions).

## Mounting in Sandboxes

The simplest way to mount a file system into a Tensorlake sandbox is through the sandbox API: pass the file system's name and a mount path when creating the sandbox (or attach it to a running one), and the mount appears as an ordinary directory with no credentials to manage:

```bash theme={null}
tl sbx create -f agent-scratch:/work
```

Per-mount `read_only` and `prefetch` options are available. See [Mount Filesystems](/sandboxes/mount-filesystems) for the full guide, including warm-pool claims and runtime attach/detach.

Alternatively, mount from inside the guest with the same `tl fs mount` commands. The guest needs one scoped credential to attach a file system:

```bash theme={null}
$ tl fs token agent-scratch
```

The command prints the credential and the environment recipe for the guest.

<CardGroup cols={2}>
  <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="Manage Sessions" icon="arrows-rotate" href="/filesystems/manage-sessions">
    Inspect status, resume, restore, and clean up.
  </Card>

  <Card title="Core Concepts" icon="book-open" href="/filesystems/core-concepts">
    File systems, mounts, sessions, autosave checkpoints, snapshots, and publishing.
  </Card>
</CardGroup>