Tensorlake Documentation

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.

Quickstart

Install the Tensorlake CLI and sign in:

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.

Create a repository

CLI
Python
TypeScript

$ tl git create agent-outputs --default-branch main
created https://git.tensorlake.ai/project_9f3c2a1b/agent-outputs

$ pip install tensorlake
$ export TENSORLAKE_API_KEY=tlk_...

from tensorlake import RepositoryClient

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

$ npm install tensorlake
$ export TENSORLAKE_API_KEY=tlk_...

import { RepositoryClient } from "tensorlake";

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

console.log(repo.url);

agent-outputs is an ordinary Git repository. Its default branch is main.

Commit and push files

Use Git directly, or push a local worktree from your application.

Git CLI
Python
TypeScript

Clone with a short-lived credential, then use Git as usual:

$ 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

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

$ 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

$ mkdir -p initial-app
$ echo "# Agent Outputs" > initial-app/README.md

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)

$ 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

$ mkdir -p initial-app
$ echo "# Agent Outputs" > initial-app/README.md

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);

$ 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

The repository now has a normal Git commit on main.

Mount the repository into a sandbox

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

Edit and snapshot

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

Promote to main

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

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:

$ 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:

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

See 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

Store Agent-Generated Code

Store generated apps, docs, and assets with snapshots, promotion, and activity history.

Distribute Files to Agents

Roll out manuals, skills, configs, and tools to many agents with versioned read-only mounts.

Where To Go Next

Core Concepts

Learn the vocabulary: repositories, workspaces, mounts, snapshots, promotion, and mount modes.

File System Mounts

Choose between writable, read-only, pinned, and following mounts.

Writable Mounts

Mount, snapshot, and promote agent work.

Git Repositories

Use Tensorlake repositories with ordinary Git commands.

Repository SDKs

Create repositories, push worktrees, and merge branches from Python or TypeScript.

Overview

Git Workflows

File System Workflows

Reference

Use Cases

Versioned Directories

Quickstart

Resume from Snapshots on Another Machine

Mental Model

What Tensorlake Provides

Use Cases

Store Agent-Generated Code

Distribute Files to Agents

Where To Go Next

Core Concepts

File System Mounts

Writable Mounts

Git Repositories

Repository SDKs

​Quickstart

​Resume from Snapshots on Another Machine

​Mental Model

​What Tensorlake Provides

​Use Cases

Store Agent-Generated Code

Distribute Files to Agents

​Where To Go Next

Core Concepts

File System Mounts

Writable Mounts

Git Repositories

Repository SDKs

Quickstart

Resume from Snapshots on Another Machine

Mental Model

What Tensorlake Provides

Use Cases

Where To Go Next