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

# Manage Sessions

> Inspect, resume, recover, and clean up versioned file system sessions.

A mount path is ephemeral. Server autosaves and permanent snapshots are the durable state behind it. A writable session also owns a local crash-safe journal, so the same machine can recover changes that had not reached the server when the mount stopped.

Use these commands, or their SDK equivalents, to inspect a session, resume it, browse its history, get back to an earlier snapshot's contents, or delete a file system.

## Check Status

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    $ tl fs status /work
    filesystem: agent-scratch
    session: 54398548341c (created 12m ago)
    mode: writable — every save becomes the filesystem's current state
    autosave: settled changes replicate in about 1s (5s max while continuously writing)
    last autosave: 2m ago
    permanent snapshots: 1
    daemon: serving save 8b21f6a9
    log: ~/.local/share/tensorlake/mounts/54398548341c.../daemon.log
    local: clean
    ```
  </Tab>

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

    client = FilesystemClient()

    status = client.mount_status("/work")
    print(status.filesystem, status.mounted)
    ```
  </Tab>

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

    const client = new FilesystemClient();

    const status = await client.mountStatus("/work");
    console.log(status.filesystem, status.mounted);
    ```
  </Tab>
</Tabs>

With unsaved changes, status lists dirty paths:

```bash theme={null}
local: 2 change(s):
  M src/parser.py
  D src/old_parser.py
```

Two more lines appear as a session ages:

* `retained:` counts files already published and kept locally as the byte cache. They are durable; the local copies only make reads and future autosaves fast.
* `ignored:` counts local-only files that never enter an autosave or snapshot (build output and the like, per the file system's ignore rules).

Add `--json` for machine-readable output; the SDK's `MountStatus.raw` carries the same structured payload.

## Browse History

```bash theme={null}
$ tl fs history agent-scratch
Autosave WAL (fixed native_fs_v1): each checkpoint is synchronously replicated to the shared drive; keep the newest 256 generations and all generations from the last 24h. Snapshots are permanent until you delete them.

Snapshots (permanent — kept until deleted)
4d9a2f7e  baseline benchmarks  1h ago

Recent autosave WAL (ephemeral — truncated automatically)
8b21f6a9  2m ago
e3f421a7  3h ago
```

Autosaves provide a recent recovery window. Create a permanent, billed snapshot as part of the changed generation you need to keep:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    $ tl fs snapshot /work -m "baseline benchmarks"
    Snapshot 4d9a2f7e "baseline benchmarks" — kept until deleted.
    ```
  </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>

Permanent snapshots are exempt from automatic retention. Snapshotting a clean mount promotes its
current automatic save to permanent retention in place, without uploading file bytes or creating a
duplicate content version. It is a quiet no-op only when the current save is already permanent.
Drop a permanent snapshot you no longer need with `tl fs delete-snapshot agent-scratch <snapshot-id>`.

## List Sessions

```bash theme={null}
$ tl fs ls agent-scratch
Session        Filesystem      Base       Saves   Mode         Mounted   Age
54398548341c   agent-scratch   e3f421a7   yes     publishing   /work     12m
```

`tl fs ls` with no argument lists your file systems.

## Resume a Session

Unmounting keeps the session by default:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    $ tl fs unmount /work
    Unmounted /work. Session 54398548341c kept — `tl fs mount agent-scratch <path>` resumes it.
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    mount.unmount()
    # or, without a Mount object: client.unmount("/work")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await mount.unmount();
    // or, without a mount object: await client.unmount("/work");
    ```
  </Tab>
</Tabs>

Remounting the file system on a machine that has a detached session resumes that session, unsaved local changes included. The new mount path can be different:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    $ tl fs mount agent-scratch /work2
    Resumed session 54398548341c at its last durable checkpoint.
    ```
  </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>

## Discard Local Changes

Throw away unsaved changes (and ignored files under the mount) with the mount:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    $ tl fs unmount /work --discard
    Unmounted /work (unsaved local changes discarded).
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    mount.unmount(discard=True)
    ```
  </Tab>

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

Everything already published is untouched: autosave checkpoints and snapshots are immutable.

## Access Historical State

Autosave checkpoints and permanent snapshots are immutable, and the shared timeline only moves forward — there is no in-place restore. To get back to an earlier state, fork the file system at that snapshot. A fork is metadata-only: the server shares the immutable content and publishes only metadata, so no file bytes are copied.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    fork = client.fork(
        "agent-scratch-baseline",
        "agent-scratch",
        "4d9a2f7e5b3d8c6a4f2e0d9b7c5a3f1e8d6b4c2a1029384756abcdef01234567",
    )
    ```
  </Tab>

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

Mount the fork (or mount it `read_only` into sandboxes) to work from the historical state. You can fork at the live head or at any retained point — a permanent snapshot, or an autosave still inside the retention window.

To read individual files at a historical point without mounting anything, pass the snapshot to the SDK's read APIs:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    fs = client.get("agent-scratch")
    data = fs.read_file("results/bench.json", version="4d9a2f7e5b3d...")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const fs = await client.get("agent-scratch");
    const data = await fs.readFile("results/bench.json", "4d9a2f7e5b3d...");
    ```
  </Tab>
</Tabs>

## Inspect a Session

If a session's local state is ever inconsistent (a hard sandbox kill mid-write, an interrupted resume), `tl fs doctor` inspects the crash-safe local session state and reports problems:

```bash theme={null}
$ tl fs doctor /work --json
```

Doctor only reads local session state; durable history is never touched.

## Delete a File System

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    $ tl fs rm agent-scratch
    Delete filesystem agent-scratch and all of its history? This cannot be undone. [y/N]
    ```
  </Tab>

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

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

Pass `-f` to skip the confirmation; the SDK clients delete without prompting. Deletion removes the file system, its history, and its sessions.