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

# Cloud Volumes

> Cloud Volumes are directories that can be mounted on one or more sandboxes. Volumes can be versioned and can be time-travelled.

Agents produce state and artifacts worth keeping: code, documents, artifacts, working notes.
Volumes can be mounted as a directory on the file system into a sandbox, all writes are automatically saved in durable storage asynchronously. They offer
SSD grade write performance, and reads are cached and can be fetched either lazily or pre-fetched from remote storage.

These directories can be snapshotted to create point-in-time checkpoints and can be time travelled to restore state at a given time.

Volumes can be used on any sandbox provider or AWS/GCP/Azure or even Kubernetes containers. They are portable directories that can be mounted
on any Linux or OSX machines.

These are some use cases for versioned file systems:

* Version an agent's working state without teaching it version control
* Persist a long-running session so a crashed sandbox loses nothing
* Share one file system across several coding agents at once. Disjoint work merges automatically
* Distribute documents, skills, and tools to fleets of agents with read-only mounts

## Quickstart

Install and authenticate the interface you plan to use:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    curl -fsSL https://tensorlake.ai/install | sh
    tl login
    # Or export TENSORLAKE_API_KEY=tl_apiKey_...
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install tensorlake
    export TENSORLAKE_API_KEY=tl_apiKey_...
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install tensorlake
    export TENSORLAKE_API_KEY=tl_apiKey_...
    ```
  </Tab>
</Tabs>

The SDKs require an API key and derive the project from that key. They do not
use the Personal Access Token stored by `tl login`, and they do not require
separate organization or project IDs. Local SDK mounts also require the `tl`
binary on `PATH`.

Then create a file system, mount it, and watch changes save themselves.

<Steps>
  <Step title="Create a file system">
    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        $ tl fs create agent-scratch
        Created filesystem agent-scratch (empty).
          mount it: tl fs mount agent-scratch <path>
          or push a folder: tl fs push <dir> 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 empty file system is created on our servers. It's ready to be mounted immediately on a sandbox or machine.
  </Step>

  <Step title="Mount it">
    <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 pathlib import Path

        # Tilde paths are not expanded by the SDK; pass a resolved path.
        mount = fs.mount(str(Path.home() / "work"))
        ```
      </Tab>

      <Tab title="TypeScript">
        ```typescript theme={null}
        import { homedir } from "node:os";
        import { join } from "node:path";

        // Tilde paths are not expanded by the SDK; pass a resolved path.
        const mount = await fs.mount(join(homedir(), "work"));
        ```
      </Tab>
    </Tabs>

    The file system is mounted at /work on the local machine. It's a normal POSIX compliant directory.
    You can write to the file system through the Python or TypeScript SDKs without mounting them. The SDKs use the
    HTTP API of the remote file system directly.
  </Step>

  <Step title="Work in it">
    Write into the mounted directory with POSIX read/write APIs. if you use the Python/TypeScript SDKs, writes go straight to the file system without a mount.

    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        $ echo "hypothesis: the parser is quadratic" > /work/notes.md
        $ mkdir /work/results && cp bench.json /work/results/
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        fs.write_file("notes.md", "hypothesis: the parser is quadratic\n")
        ```
      </Tab>

      <Tab title="TypeScript">
        ```typescript theme={null}
        import { readFile } from "node:fs/promises";

        await fs.writeFile("notes.md", "hypothesis: the parser is quadratic\n");
        await fs.writeFile("results/bench.json", await readFile("bench.json"));
        ```
      </Tab>
    </Tabs>

    The writes are asynchronously replicated to Tensorlake's remote file system. The server advances the file-system timeline.

    The file systems can be mounted on multiple machines at once. The other mounts will see the changes within seconds.

    You can create a permanent snapshot to create a point-in-time checkpoint of the file system. You can time travel across the snapshots: read files at a
    specific checkpoint or fork the file system from that 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 those changes, snapshotting a clean mount promotes that current
    automatic save to permanent retention in place. It uploads no file bytes and creates no second
    content version. If the current save is already permanent, the command is a quiet no-op.
  </Step>

  <Step title="Check status and history">
    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        $ tl fs status /work
        filesystem: agent-scratch
        session: 54398548341c (created 5m 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
        local: clean
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        status = mount.status()
        print(status.filesystem, status.mounted)
        ```
      </Tab>

      <Tab title="TypeScript">
        ```typescript theme={null}
        const status = await mount.status();
        console.log(status.filesystem, status.mounted);
        ```
      </Tab>
    </Tabs>

    History is browsed with the CLI:

    ```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  4m ago

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

    `local: clean` means the local journal has no changes waiting for autosave. History separates permanent snapshots from recent autosave recovery points.
  </Step>

  <Step title="Resume on another machine">
    The mount path is disposable; the session behind it is durable. If the sandbox crashes or you unmount and walk away, remount the file
    system and pick up from its last durable state:

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

    From **another** machine you recover everything through the last autosave checkpoint, and because autosave is frequent, that is
    typically seconds of work at most; anything written since the last checkpoint stays on the machine that wrote it.
    Remounting on the **same** machine can additionally recover a detached session's unsaved local changes from its overlay.
  </Step>
</Steps>

## Push a Folder Without Mounting

When you just want a directory's contents in a file system, you can push the directory into the file system:

```bash theme={null}
$ tl fs push ./results agent-scratch -m "run 42 results"
Pushed ./results to agent-scratch (14 file(s)).
```

Pushing the same directory again uploads only what changed. Passing `-m` creates a permanent snapshot.

## Mental Model

1. A **file system** is the durable, versioned store.
2. A **mount** gives a sandbox an ordinary directory backed by it.
3. A **session** is the state behind one mount, resumable after crashes and unmounts.
4. An **autosave checkpoint** replicates settled work through a session WAL and advances the shared timeline before it is acknowledged.
5. A **snapshot** keeps the invocation's exact state as a permanent, billed retention point until you delete it. If autosave already published that state, the existing save is promoted in place without uploading bytes or creating duplicate content.
6. Other mounts converge as acknowledged autosaves or permanent snapshots advance the shared timeline.

See [Core Concepts](/filesystems/core-concepts) for short definitions of each term.

## Summary of Features

* **Autosave**: settled changes replicate through durable server WAL and into the shared timeline automatically; a continuously-writing agent still checkpoints at a bounded interval.
* **Permanent snapshots and history**: browse both kinds of history with `tl fs history`; create a permanent, billed point with `tl fs snapshot` and remove it with `tl fs delete-snapshot`.
* **Time travel**: fork a file system at any permanent snapshot or retained autosave with the SDK's `fork`, or read files at a snapshot with `read_file(path, version=...)`.
* **Durable sessions**: crash a sandbox and remount elsewhere to recover through the last server autosave. On the same machine, the local journal can also recover changes that had not reached the server yet.
* **Shared file systems**: many writers on one file system; server-ordered disjoint changes merge automatically, same-path writes are last-writer-wins.
* **Read-only mounts**: serve a fixed snapshot or follow the file system's current state across many running sandboxes.

## Use Cases

<CardGroup cols={2}>
  <Card title="Distribute Files to Agents" icon="package-open" href="/filesystems/distribute-files">
    Roll out manuals, skills, configs, and tools to many agents with versioned read-only mounts.
  </Card>

  <Card title="Store Agent-Generated Code" icon="code-branch" href="/git/store-generated-code">
    Prefer a Git repository when generated projects need branches and explicit publication.
  </Card>
</CardGroup>

## Where To Go Next

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="book-open" href="/filesystems/core-concepts">
    Learn the vocabulary: file systems, mounts, sessions, autosave checkpoints, snapshots, and publishing.
  </Card>

  <Card title="File System Mounts" icon="folder-tree" href="/filesystems/filesystem-mounts">
    Choose between writable and read-only mounts.
  </Card>

  <Card title="Manage Sessions" icon="arrows-rotate" href="/filesystems/manage-sessions">
    Inspect status, resume, fork historical snapshots, and clean up.
  </Card>

  <Card title="Concurrent Writes" icon="users" href="/filesystems/concurrent-writes">
    How several mounts writing at once reconcile: disjoint paths merge, same-path is last-writer-wins.
  </Card>
</CardGroup>