trunks 1.0.0

Powerful, high-performance Git-compatible repositories backed by your own storage.

Trunks

The most powerful open-source POSIX-compatible, Git-native filesystem for AI agents.

Trunks turns any backend into a Git-compatible remote. Point it at S3, R2, Tigris, GCS, Azure Blob, MinIO, Postgres, SFTP, a fileshare, or local disk. You get branches, commits, refs, push, pull, the whole protocol. No Git server. No service to operate. No control plane. No repo copy per agent.

Agents write normal files. Developers run normal Git.

git checkout -b agent/run-7
git add .
git commit -m "agent output"
git push

That git push writes commit objects and advances the branch ref straight into your bucket. No GitHub. No remote URL. No server in between.

Install

pip install trunks
npm install @layerbrain/trunks

Quick Start

trunks mount --repo my-app --backend s3://company-trunks --path ./my-app

That's it. ./my-app is a normal folder now. Run your agent in it. Edit code in it. trunks push syncs to your bucket. Another machine runs the same mount and sees the same files.

S3 here is whatever you have: GCS, Azure Blob, R2, Tigris, MinIO, Postgres, SFTP, fileshare, local disk. Trunks makes each one act like a Git remote. No Trunks server in the middle. No Git server in the middle.

How It Works

Trunks stores repos as Git-shaped objects in your backend.

s3://company-trunks/trunks/my-app.trunk/
├── objects/       blobs, trees, commits (sha-keyed, immutable)
├── refs/heads/    branch pointers (compare-and-swap)
└── journals/      crash recovery

• When an agent writes a file, Trunks hashes the bytes into objects.
• When it checkpoints, Trunks writes a tree and a commit.
• When it pushes, Trunks advances the branch ref with compare-and-swap.

That's the whole protocol. Two writers can't clobber each other. Crashes don't corrupt state. Two machines sync by pointing at the same prefix.

Why It Exists

Agents make a lot of files. Without history, every run is a coin flip. Did the agent leave you something useful, or did it stomp the last version?

Git solves history. But Git expects a hosted server, a clone per worker, and has no native story for large or many repos.

Trunks keeps Git's commit objects and refs, drops the server, and writes straight to storage you already use. The bucket is the remote. So is the database, or the SFTP host. Agents check out a branch, write files, save versions, and you review the diff like a normal pull request.

What You Get

• Real files. Agents read and write with cat, vim, grep, npm, python. The SDKs are a convenience, not a requirement.
• Real Git. Every checkpoint is a Git commit object. git log, git diff, git blame all work. So does git push through the Trunks shim.
• Real concurrency. Branches are pointers. Different branches never collide. Same branch is one CAS. One writer wins, the others retry.
• Real backends. S3, R2, Tigris, GCS, Azure Blob, MinIO, Postgres, SFTP, fileshare, local disk. Each one passes the same multi-commit, branch, merge, and CAS-conflict contract test.
• Real scale. Virtual mode mounts a 100GB repo without materializing it.
• Real portability. Same commands on a laptop, EC2, Lambda, Cloudflare Worker, Modal sandbox, Daytona, CI runner.

Mount Modes

trunks mount --repo my-app --path ./my-app
trunks mount --repo my-app --path ./my-app --watch
trunks mount --repo big-repo --path ./big-repo --mode virtual

Default is plain files. --watch keeps a journal so a crash doesn't lose work. --mode virtual sparsely materializes huge repos.

Branches Are Pointers

One branch per agent run. Creating one is a single ref write. No copy.

trunks branch create --name agent/run-7 --from main
trunks branch switch --name agent/run-7
trunks checkpoint -m "agent output"
trunks push

Two agents on different branches don't collide. Two agents on the same branch race a compare-and-swap. One wins. The other retries.

Git Without GitHub

cd ./my-app
trunks
git checkout -b agent/run-7
git add .
git commit -m "agent output"
git push

trunks opens a shell where git writes Trunks objects to your backend. Same commits. Same refs. Your storage. No GitHub. No remote URL.

Python

Use the Python SDK when your agent wants files and commits without shelling out.

from trunks import Trunk

with Trunk(name="my-app") as trunk:
    trunk.write("task.md", b"Fix auth\n")
    trunk.commit(message="agent output")
    trunk.push()

async with Trunk(name="my-app") as trunk:
    await trunk.write("task.md", b"Fix auth\n")
    await trunk.commit(message="agent output")
    await trunk.push()

Node

import { Trunks } from "@layerbrain/trunks";

const trunks = new Trunks();
const fs = await trunks.mount({ repo: "my-app", path: "./my-app", watch: true });

await fs.write("task.md", "Fix auth\n");
await fs.checkpoint("agent output");
await fs.push();

Resource API

CLI, Python, and Node share a Stripe-shaped API.

trunks repo create --name my-app --backend s3://company-trunks --json
trunks branch list --json --limit 20 --offset 0

client = Trunks(cwd="./my-app")
client.branches.create(name="agent/run-7", from_ref="main")

const trunks = new Trunks();
await trunks.branches.create({ name: "agent/run-7", from: "main" });

List calls return the same envelope everywhere:

{
  "object": "list",
  "data": [],
  "limit": 20,
  "offset": 0,
  "total_count": 0,
  "has_more": false
}

Where To Next

Want to do	Page
Walk through your first repo	Tutorial
See every command	CLI reference
Use Python	Python SDK
Use Node	Node SDK
Resource shapes	Resources
Pick a backend	Backends
Wire up an agent framework	Agents
Understand the bytes	Architecture

Backend guides:

• S3-compatible storage
• Azure Blob Storage
• Google Cloud Storage
• Postgres
• SFTP
• Local disk and fileshares

Examples:

• Mastra
• OpenAI Agents SDK
• LangChain / LangGraph
• CrewAI
• Pydantic AI
• Agno
• E2B
• Daytona
• Blaxel

MIT licensed.