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

# Core Concepts

> Short definitions for the versioned file system model: mounts, local journals, autosave checkpoints, permanent snapshots, retention, and publishing.

These are the terms used across the versioned file system docs.

## File System

A **file system** is the durable, versioned store: one shared timeline. Autosave checkpoints are kept as a recent recovery window; permanent snapshots are kept until you delete them (see [Retention](#retention)).

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl fs create agent-scratch
    ```
  </Tab>

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

    client = FilesystemClient()
    fs = client.create("agent-scratch")
    ```
  </Tab>

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

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

A new file system starts empty and is ready to mount immediately.

## Mount

A **mount** gives a sandbox a directory backed by a file system.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl fs mount agent-scratch /work
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    mount = client.mount("agent-scratch", "/work")
    # or, from a filesystem object: mount = fs.mount("/work")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const mount = await client.mount("agent-scratch", "/work");
    // or, from a filesystem object: const mount = await fs.mount("/work");
    ```
  </Tab>
</Tabs>

The mount path is ephemeral. Processes read and write `/work` like any other directory while the sandbox is running. Reads stream in lazily, so mounting is fast regardless of how much the file system holds.

## Session

A **session** is the state behind one writable mount. It records which checkpoint the mount started from and owns a crash-safe local journal for changes that have not reached the server yet.

Sessions survive unmounts and sandbox crashes. Remounting a file system this machine has a detached session for resumes that session:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl fs mount agent-scratch /work2
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    mount = client.mount("agent-scratch", "/work2")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const mount = await client.mount("agent-scratch", "/work2");
    ```
  </Tab>
</Tabs>

`tl fs ls agent-scratch` lists a file system's sessions.

## Autosave Checkpoint

An **autosave checkpoint** is a durable, shared recovery point for the mounted file state. Writable mounts replicate settled changes through a per-session server WAL automatically, including at a bounded interval when an agent writes continuously.

The server verifies and applies each acknowledged checkpoint to the shared file-system timeline before returning success. Following mounts can observe it on their next head poll, typically within seconds of the original writes settling. Automatic points appear under `Recent autosave WAL` in `tl fs history`. They are ephemeral: Tensorlake retains the newest 256 and all points from at least the most recent 24 hours, then truncates older entries automatically.

## Permanent Snapshot

A **snapshot** keeps the invocation's exact state as a permanent, billed retention point:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl fs snapshot /work -m "baseline benchmarks"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    mount.snapshot("baseline benchmarks")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await mount.snapshot("baseline benchmarks");
    ```
  </Tab>
</Tabs>

If autosave already published that state, the command promotes the current automatic save to
permanent retention in place. It uploads no file bytes and creates no duplicate content version.
If the current save is already permanent, the command is a quiet no-op. Permanent snapshots appear
separately in `tl fs history`, can be forked into a new file system or read at with the SDK, and
remain until you run `tl fs delete-snapshot`.

## Retention

Autosave checkpoints are retained as a bounded recent window so long-running mounts do not accumulate history without limit. Permanent snapshots are billed storage, structurally exempt from automatic expiry, and remain until you delete them.

## Publishing

Writable mounts **publish**: every acknowledged autosave checkpoint advances the file system's shared timeline, and other mounts converge to it automatically. The server WAL is the crash-safe commit path, not a private 15-minute staging window.

`tl fs status` shows the mode:

```bash theme={null}
mode: writable — shared current state
```

There is no separate promote step on the file system surface. If you want private work that publishes only when you say so, use a [Git repository workspace](/git/workspace-mounts) instead.

## Concurrent Writes

Several mounts can write to one file system at once. Crystallized updates that touch different paths merge automatically. Two mounts publishing the *same* file in overlapping windows are last-writer-wins: the later ordered update's version sticks, silently. A file system is a shared drive, not a set of branches, so there are no conflict markers.

See [Concurrent Writes](/filesystems/concurrent-writes).

## Retained Files

After a checkpoint publishes, the mount keeps local copies of its files as a byte cache: reads stay local and future autosaves stay incremental. `tl fs status` counts them under `retained:`. They are already durable; the cache only costs local disk.

## Credentials

`tl login` stores a Tensorlake CLI credential. `tl fs` commands mint and refresh the short-lived credentials they need automatically, including inside sandboxes, where `tl fs token <filesystem>` mints the scoped credential a guest needs to attach one file system.

You only handle credentials yourself on the Git surface. See [Authentication](/git/authentication).