TiDB Cloud FilesystemThe Workspace Your Agents Share
One filesystem, held by several runtimes at once, that knows what an agent leaves behind — dirty tree, new objects, test output, artifacts.
For an existing filesystem. First time? Follow the quickstart.
What Makes It Different
Three Things TiDB Cloud Filesystem Does That Your Sandbox Disk Can't
All three exist for one reason: a distributed database sits under this filesystem, so it can promise things a disk can't.
Git-Aware Workspace
A Resumed Workspace Still Has Its Git State
Save your agent's Git working state before the sandbox ends: push your commits, or pack the Git metadata with pack-file-system. The next sandbox restores the branch and working files from the saved workspace — not a fresh clone. Untracked files come back only if you list them.
WHAT IS SAVED, IN ORDER
01clean tree
the committed baseline
02dirty overlay
uncommitted modifications
03object pack
objects the agent created
ti fs-git clone-git-workspace · hydrate-git-workspace · add-git-worktree
Rebuildable vs. Persistent
Keep What Your Agent Needs. Drop the Noise
Mount with --mount-profile coding-agent and node_modules, dist and caches stay local, because they can be rebuilt anywhere. What can't be rebuilt — test results, failure logs, patches — is what persists.
THE SPLIT, FILE BY FILE
PERSISTED
sourcelock filepatchestest resultsfailure logsLOCAL-ONLY
node_modules.tsbuildinfodist.turbocoverageChosen when you mount. With this profile, Git metadata stays local too.
Any File, Any Format
One Place for Everything the Agent Touches
An agent's working set is never just code — it's source, uploads, datasets, test output, artifacts. One durable workspace holds all of it, instead of a repo plus a bucket plus a log shipper.
THE WORKING SET, IN ONE PLACE
The same path from CLI, IDE, agent and CI — one namespace.
Proof at Scale
Agent Workspace Continuity, Running in Production
0+
file systems in production behind Kimi Work (Moonshot AI)
TiDB Cloud Filesystem holds the agent workspaces behind Kimi Work, Moonshot AI's desktop AI agent for knowledge workers — which is why the runtimes that execute those agents stay disposable.
How It Works
Execution Is Disposable. State Is Not
Two planes, one namespace. Runtimes come and go above; the workspace below is addressed as a service and outlives all of them.
One Coding Agent Task, Eight Steps — Each Leaves State the Next One Needs
A coding agent doesn't touch a filesystem once. It touches it at every step, and the loop ends where a sandbox volume can't follow.
Enter the Repository
Tree and metadata arrive first; content loads on access.
metadata-first · lazy hydration
Search
Find files by name or content. Configure an embedding provider to search by meaning.
fs search-file-content · fs find-files
Read Context
Handler, config, test and failing log arrive as one batch.
inline small files · batch read
Edit Files
Writes land locally first; a journal keeps them recoverable.
local-first write · journal · async writeback
Build and Test
Rebuildables stay local. Results, logs and patches persist.
build profile · local-only overlay
Save Git State
Baseline, dirty overlay and new objects — modelled separately.
ti fs-git · clean tree · dirty overlay · object pack
Checkpoint
Save a layer checkpoint before an experiment. Fork from it to continue from the saved state.
fs create-layer · create-layer-checkpoint · fork-layer · rollback-layer
Hand Off
The next runtime opens the same workspace. Same token, no mount required.
filesystem token · one namespace · fs read-file, mountless
Where It Fits
Start with the Boundary Your State Has to Cross
You're in the right place if —
A sandbox or ephemeral job ends before the task is done.
Each run clones and prepares the same repository again.
Several agents need the same repository or document set at once.
Work moves between E2B, Modal, Daytona, CI or a local tool.
Several kinds of storage persist real work.
Which one is right depends on what has to survive, and what it has to cross.
WHAT YOU NEED TO KEEP
USE
A durable disk attached to one workload
Block storage
A shared POSIX filesystem for compute clients in one cloud
Network file storage
Objects, artifacts, datasets, backups or archives
Object storage
Analytics over large tables, or an AI data workflow
Committed source history, branches and merges
Git hosting
What an agent remembers across conversations
Agent memory
Snapshots and forks of work inside one sandbox platform
Platform-native persistence
One active working directory crossing runtime, session, agent or reviewer boundaries
TiDB Cloud Filesystem
Hands-On Lab
Try It in a Real Sandbox
A guided, 120-minute lab using a virtual machine.
Straight Answers
What TiDB Cloud Filesystem Is, and What It Isn't Yet
ti fs drain-file-system (the mount stays up) or unmount normally, which drains automatically, then confirm with ti fs read-file. Avoid concurrent writes to the same file: changes are not merged. See Share a File System Across Machines.ti fs read-file doesn't require a mount at all.fs search-file-content matches literal text (the pattern is a text query, not a regex or glob) and fs find-files matches on name, tag, size and time. See Configure AI providers for the setup.create-layer-checkpoint and rollback-layer are documented commands. Drain a mounted layer before you checkpoint it. Rollback discards a layer's uncommitted changes; it does not return to a checkpoint, so to continue from one, fork a new layer. One caveat carried over from the docs: complex histories involving repeated changes to layer-created files, or inherited metadata, might have limitations during public preview. See Layers and checkpoints.aws-us-east-1 and may change at general availability. Full rates, free-tier details and no-card limits are on the pricing details page.Get Started
Nothing to Rebuild. Everything to Build On
Write from one runtime. Sync your changes. Let it end. Reopen the workspace from another and check that the second run continues from the first. That's the whole test.