Tensorlake Documentation

Use Tensorlake repositories when your product creates or updates many user projects with coding agents. A coding agent platform may create thousands of repositories each day and keep updating existing applications as users ask for changes. Tensorlake gives every generated project a durable Git source of truth, a writable file system for agents, snapshots for checkpoints, and activity history for visibility.

Pattern

Create one repository per generated app, site, package, or user project.
Mount a writable workspace when an agent needs to change it.
Snapshot during the run so work is durable and inspectable.
Promote accepted changes back to the project branch.
Use repository activity to see what agents created, updated, merged, or published.

Create Repositories at Product Scale

Create repositories from your control plane when users start new projects:

Python
TypeScript

export TENSORLAKE_API_KEY=tlk_...

from tensorlake import RepositoryClient

with RepositoryClient.from_env() as repos:
    repo = repos.create("app-7f3c2a1b", default_branch="main")
    print(repo.url)

export TENSORLAKE_API_KEY=tlk_...

import { RepositoryClient } from "tensorlake";

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

console.log(repo.url);

Use stable repository names, such as an internal app id. Human-facing app names can change without changing the storage identity.

Why This Scales

A repository is the durable unit for a user project. A workspace is the temporary unit for one agent run. That separation keeps high-volume platforms simple: your control plane can create, list, fork, archive, and update repositories through the SDKs, while agents work in isolated mounted workspaces. Mounting does not copy the whole repository into the sandbox. File content is fetched as processes read it, and snapshots record incremental checkpoints instead of forcing every run to become one large final commit. Use branches for product states such as main, preview, or release. Use workspaces for in-progress agent attempts.

Store Generated Files

When a backend process already has a generated worktree, push it directly:

Python
TypeScript

report = repos.push_worktree(
    "app-7f3c2a1b",
    root="./generated-app",
    branch="main",
    message="create initial app",
)

print(report.commit)

const report = await repos.pushWorktree("app-7f3c2a1b", {
  path: "./generated-app",
  branch: "main",
  message: "create initial app",
});

console.log(report.commit);

push_worktree and pushWorktree create one commit from a local directory. They skip .git, honor .gitignore, preserve symlinks, and preserve executable bits on regular files. Use this for generated code, app assets, docs, migrations, configuration, and deployment metadata:

generated-app/
  src/
  public/
  docs/
  migrations/
  package.json

Let Agents Work in a File System

When an agent is editing an existing project, mount a writable workspace:

$ tl fs mount app-7f3c2a1b:main /work
Mounted app-7f3c2a1b:main at /work (workspace 3f9a2b7e1c4d)

The agent edits /work like a normal directory. Snapshot checkpoints as the run progresses:

$ tl fs snapshot /work -m "scaffold billing page"
Snapshot 8b21f6a9c3d5e7f1a2b4c6d8e0f3a5b7c9d1e3f5 (28 file(s), 28 of 28 chunks uploaded)

$ tl fs snapshot /work -m "wire billing API"
Snapshot 4d9a2f7e5b3d8c6a4f2e0d9b7c5a3f1e8d6b4c2a (12 file(s), 12 of 12 chunks uploaded)

Snapshots make long-running agent work durable. If a sandbox stops, the workspace can be reattached. If a run goes in the wrong direction, you can inspect or restore an earlier snapshot instead of losing the whole attempt. When the user accepts the result, publish it:

$ tl fs promote /work main -m "add billing page"
Promoted workspace 3f9a2b7e1c4d -> main at 1c4d9a2f7e5b3d8c6a4f2e0d9b7c5a3f1e8d6b4c (squashed)

After promotion, future agents that mount app-7f3c2a1b:main, build systems that clone it, and developers who fetch it get the published version.

Update Existing Repositories Safely

Generated applications keep changing after the first version. Users ask agents to add pages, fix bugs, change copy, update dependencies, or regenerate docs. For backend pushes, pass expect_oid in Python or expectOid in TypeScript when the update should fail if the branch moved:

Python
TypeScript

info = repos.info("app-7f3c2a1b")
current = next(b.oid for b in info.branches if b.name == "main")

report = repos.push_worktree(
    "app-7f3c2a1b",
    root="./generated-app",
    branch="main",
    message="update homepage",
    expect_oid=current,
)

const info = await repos.info("app-7f3c2a1b");
const current = info.branches.find((branch) => branch.name === "main")?.oid;

const report = await repos.pushWorktree("app-7f3c2a1b", {
  path: "./generated-app",
  branch: "main",
  message: "update homepage",
  expectOid: current,
});

Use server-side merge APIs when two agents or a user and an agent changed the same project branch. Preflight first when you want to know whether a merge is clean before publishing.

Visibility for Agent Fleets

Every repository and workspace has activity you can inspect through the API and dashboard:

Which repositories exist for user projects.
Which branches changed.
Which workspaces are live, detached, or resumable.
Which snapshots each agent created.
Which paths changed in a snapshot.
Which principal pushed, promoted, merged, or reconciled changes.

This gives the product control plane enough state to answer operational questions: which users have active generations, which agents are producing large changes, which runs published to production branches, and where a failed run can resume.

Scale Model

Need	Use
New user app or project	Create a repository
Agent edits an existing app	Mount a writable workspace from `main`
Long-running generation	Snapshot as the agent reaches milestones
User accepts a result	Promote the workspace to the project branch
Backend writes generated code or docs	Repository SDK `push_worktree`
Prevent overwriting newer work	`expect_oid` / `expectOid`
Inspect what agents did	Workspace status, snapshots, operations, and branch activity
Build or deploy generated code	Ordinary `git clone`, `git fetch`, or a read-only mount

Next Steps

Repository SDKs

Create repositories, push worktrees, merge branches, and inspect refs from application code.

Writable Workspaces

Mount, snapshot, and promote code generated by agents.

Merging Changes

Handle branches that moved while an agent was working.

Architecture

Understand snapshots, lazy content delivery, merge behavior, and observability.

​Pattern

​Create Repositories at Product Scale

​Why This Scales

​Store Generated Files

​Let Agents Work in a File System

​Update Existing Repositories Safely

​Visibility for Agent Fleets

​Scale Model

​Next Steps