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

# Versioned Directories

> Git repositories that mount as directories, persist snapshots, and promote changes back to branches.

Agentic harnesses start versions it's internal state, and data when agents need to interact with code, documents, or artifacts. This workflow is a
natural good fit for distributed version control systems, like Git. However, Git becomes slow as soon as you throw large amounts of data at it.
For example, if an agent needs just one file from a repository, it needs to clone at least one branch,
and download every file existent in that branch.

We built a disaggregated Git infrastructure to scale to tens of millions of repositories and absorb
hundreds of thousands of pushes per second, by re-engineering how Git's metadata, ingestion, and storage work.

These are some use cases for versioned directories:

* Version an agent's state
* Distribute documents that need their own independent history
* Store code and artifacts that version automatically as agents work through them
* Fork or clone working sessions, picking up existing state and branching off them

Every repository can be mounted as a live directory on a sandbox. The mounts gives your agents access to your versioned data, on demand, without having to perform expensive clone
and fork operations. Changes don't hit a git branch until you explicitly promote them.

<img src="https://mintcdn.com/tensorlake-35e9e726/nq8YhtvAhQjxPmqU/images/git_repo.png?fit=max&auto=format&n=nq8YhtvAhQjxPmqU&q=85&s=c9a9a2a9a558d0d9bb5b75833af1a19f" alt="Git Repository Dashboard" width="1600" height="894" data-path="images/git_repo.png" />

## Quickstart

Install the Tensorlake CLI and sign in:

```bash theme={null}
curl -fsSL https://tensorlake.ai/install | sh
tl login
```

Then create a repository, commit files to `main`, and verify the history with Git. After that, mount the same repository as a file system, edit it, snapshot it, and promote the change back to `main`.

<Steps>
  <Step title="Create a repository">
    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        $ tl git create agent-outputs --default-branch main
        created https://git.tensorlake.ai/project_9f3c2a1b/agent-outputs
        ```
      </Tab>

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

        ```python theme={null}
        from tensorlake import RepositoryClient

        with RepositoryClient.from_env() as repos:
            repo = repos.create("agent-outputs", default_branch="main")
            print(repo.url)
        ```
      </Tab>

      <Tab title="TypeScript">
        ```bash theme={null}
        $ npm install tensorlake
        $ export TENSORLAKE_API_KEY=tlk_...
        ```

        ```typescript theme={null}
        import { RepositoryClient } from "tensorlake";

        const repos = await RepositoryClient.fromEnv();
        const repo = await repos.create("agent-outputs", {
          defaultBranch: "main",
        });

        console.log(repo.url);
        ```
      </Tab>
    </Tabs>

    `agent-outputs` is an ordinary Git repository. Its default branch is `main`.
  </Step>

  <Step title="Commit and push files">
    Use Git directly, or push a local worktree from your application.

    <Tabs>
      <Tab title="Git CLI">
        Clone with a short-lived credential, then use Git as usual:

        ```bash theme={null}
        $ TOKEN=$(tl git token --repo agent-outputs --json | jq -r .token)
        $ git clone https://t:$TOKEN@git.tensorlake.ai/project_9f3c2a1b/agent-outputs
        $ cd agent-outputs
        ```

        <Note>
          First commit on a fresh machine? Git needs an identity: `git config user.name "Agent User"` and `git config user.email "agent@example.com"`.
        </Note>

        ```bash theme={null}
        $ echo "# Agent Outputs" > README.md
        $ git add README.md
        $ git commit -m "initial app"
        $ git push origin main
        $ git log --oneline -1
        4f8c2a1 initial app
        ```
      </Tab>

      <Tab title="Python">
        ```bash theme={null}
        $ mkdir -p initial-app
        $ echo "# Agent Outputs" > initial-app/README.md
        ```

        ```python theme={null}
        from tensorlake import RepositoryClient

        with RepositoryClient.from_env() as repos:
            report = repos.push_worktree(
                "agent-outputs",
                root="./initial-app",
                branch="main",
                message="initial app",
            )
            print(report.commit)
        ```

        ```bash theme={null}
        $ TOKEN=$(tl git token --repo agent-outputs --json | jq -r .token)
        $ git clone https://t:$TOKEN@git.tensorlake.ai/project_9f3c2a1b/agent-outputs
        $ git -C agent-outputs log --oneline -1
        4f8c2a1 initial app
        ```
      </Tab>

      <Tab title="TypeScript">
        ```bash theme={null}
        $ mkdir -p initial-app
        $ echo "# Agent Outputs" > initial-app/README.md
        ```

        ```typescript theme={null}
        import { RepositoryClient } from "tensorlake";

        const repos = await RepositoryClient.fromEnv();
        const report = await repos.pushWorktree("agent-outputs", {
          path: "./initial-app",
          branch: "main",
          message: "initial app",
        });

        console.log(report.commit);
        ```

        ```bash theme={null}
        $ TOKEN=$(tl git token --repo agent-outputs --json | jq -r .token)
        $ git clone https://t:$TOKEN@git.tensorlake.ai/project_9f3c2a1b/agent-outputs
        $ git -C agent-outputs log --oneline -1
        4f8c2a1 initial app
        ```
      </Tab>
    </Tabs>

    The repository now has a normal Git commit on `main`.
  </Step>

  <Step title="Mount the repository into a sandbox">
    ```bash theme={null}
    $ tl fs mount agent-outputs:main /work
    Mounted agent-outputs:main at /work (workspace 3f9a2b7e1c4d)
    $ ls /work
    README.md
    $ cat /work/README.md
    # Agent Outputs
    ```

    So far, `agent-outputs` has behaved like a normal Git repository, and `git clone` would work here too. Mounting skips the clone — content streams in as it's read — and creates a workspace that survives independently of this sandbox.

    Tensorlake creates that workspace behind the writable mount. It's the isolated history where snapshots are stored.
  </Step>

  <Step title="Edit and snapshot">
    ```bash theme={null}
    $ printf "\n## Parser Notes\n" >> /work/README.md
    $ tl fs snapshot /work -m "add notes"
    Snapshot 8b21f6a9c3d5e7f1a2b4c6d8e0f3a5b7c9d1e3f5 (1 file(s), 1 of 1 chunks uploaded)
    ```

    Snapshotting persists the current `/work` file state as a Git commit on the workspace. The branch is unchanged until promotion.
  </Step>

  <Step title="Promote to main">
    ```bash theme={null}
    $ tl fs promote /work main -m "add notes"
    Promoted workspace 3f9a2b7e1c4d -> main at 1c4d9a2f7e5b3d8c6a4f2e0d9b7c5a3f1e8d6b4c (squashed)
    $ git -C agent-outputs fetch origin main
    $ git -C agent-outputs log --oneline -2 origin/main
    1c4d9a2 add notes
    4f8c2a1 initial app
    $ git -C agent-outputs show origin/main:README.md
    # Agent Outputs

    ## Parser Notes
    ```

    After promotion, `main` contains the snapshotted file-system change. New mounts, `git clone`, and `git fetch` all see the same files.
  </Step>
</Steps>

## Resume from Snapshots on Another Machine

The mount path is disposable. The workspace is the resumable state behind it.

If your sandbox crashes, or you want to come back to the work later, remount the workspace on another machine:

```bash theme={null}
$ tl fs ls agent-outputs
Workspace      File system      Base   Snapshots   Mode        Mounted   Age
3f9a2b7e1c4d   agent-outputs    main   1           workspace   no        2h

$ tl fs mount 3f9a2b7e1c4d /work
Mounted workspace 3f9a2b7e1c4d (agent-outputs) at /work, resumed at its last snapshot
```

You continue from the latest snapshot, make more file changes, snapshot again, and promote when the work is ready. The branch stays unchanged until promotion.

## Mental Model

The workflow is:

1. A **repository** stores the durable Git history.
2. A **mount** gives a sandbox an ephemeral directory, such as `/work`.
3. A **workspace** is the isolated history behind a writable mount.
4. A **snapshot** persists the mounted file state as a Git commit on the workspace.
5. **Promotion** publishes a workspace snapshot to a branch so future mounts and Git users can use that version.

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

## What Tensorlake Provides

* **Plain Git repositories**: clone, branch, commit, merge, push, and fetch over Git smart HTTP.
* **Writable mounts**: ephemeral sandbox directories backed by isolated workspaces.
* **Snapshots**: incremental checkpoints that persist mounted file state as Git commits.
* **Promotion**: publish workspace snapshots as Git commits on shared branches, with conflict handling and activity attribution.
* **Read-only mounts**: serve a fixed commit or follow a branch across many running sandboxes.

## Use Cases

<CardGroup cols={2}>
  <Card title="Store Agent-Generated Code" icon="code-branch" href="/filesystems/store-generated-code">
    Store generated apps, docs, and assets with snapshots, promotion, and activity history.
  </Card>

  <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>
</CardGroup>

## Where To Go Next

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="book-open" href="/filesystems/core-concepts">
    Learn the vocabulary: repositories, workspaces, mounts, snapshots, promotion, and mount modes.
  </Card>

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

  <Card title="Writable Mounts" icon="pen-line" href="/filesystems/writable-workspaces">
    Mount, snapshot, and promote agent work.
  </Card>

  <Card title="Git Repositories" icon="code-commit" href="/filesystems/git-repositories">
    Use Tensorlake repositories with ordinary Git commands.
  </Card>

  <Card title="Repository SDKs" icon="rectangle-code" href="/filesystems/repository-sdks">
    Create repositories, push worktrees, and merge branches from Python or TypeScript.
  </Card>
</CardGroup>