# TiDB Filesystem ### Server-side workspace kernel for AI agents **Sandboxes are disposable. Workspaces should not be.** [![CI](https://img.shields.io/github/actions/workflow/status/mem9-ai/drive9/code-ci.yml?branch=main&label=ci&labelColor=0C0C0C&color=0C0C0C)](https://github.com/mem9-ai/drive9/actions/workflows/code-ci.yml) [![Go](https://img.shields.io/badge/go-1.25+-0C0C0C?labelColor=FAFAFA&logo=go&logoColor=0C0C0C)](go.mod) [![License](https://img.shields.io/badge/license-Apache--2.0-0C0C0C?labelColor=FAFAFA)](#license) [![Docs](https://img.shields.io/badge/docs-design%20notes-0C0C0C?labelColor=FAFAFA)](docs/)
TiDB Filesystem is a durable workspace server for AI agents. It keeps workspace state server-side so a sandbox can be replaced without losing files, logs, branches, attempts, or credentials, and it exposes that state through an HTTP API. This repository contains **only the server**: the HTTP API, tenant provisioning, metadata store, object storage integration, semantic search, vault, journal, and layered filesystem semantics. Client code — the CLI, FUSE mounts, and language SDKs — lives in separate repositories. ## What the server provides - **Workspace state** — paths, revisions, files, directories, and mutations with server-side conflict detection. - **Multi-tenancy** — tenant provisioning, schema management, quota enforcement, and TiDB Cloud integration (including shared-schema multi-tenant mode). - **Search and embeddings** — `find`, `grep`, semantic recall, and image/audio/text description extraction. - **LayerFS** — writable attempts layered over a read-only base, with checkpoint, diff, rollback, and conflict-preserving commit. - **Vault and journal** — scoped secret grants and append-only audit trails. - **Git workspaces** — server-side Git workspace metadata and object packs for fast clone/hydrate workflows. ## Architecture ```mermaid flowchart TB C[TiDB Filesystem server] C --> D[Workspace state
paths, revisions, layers,
checkpoints, scoped tokens] C --> E[Client execution layer
.git, deps, build cache,
tool state, packs] C --> F[Vault + journal
secrets, grants,
agent/workflow audit] D --> G[(TiDB / MySQL-compatible
metadata store)] F --> G D --> H[(S3-compatible
object storage)] E --> H ``` Small files and metadata live in the metadata store. Large content, LayerFS objects, and local-state packs use S3-compatible object storage. ## Quick Start Build the server binaries: ```bash go build -o bin/drive9-server ./cmd/drive9-server ``` Start the local server (`DRIVE9_TENANT_PROVIDER=local`) against TiDB: ```bash export DRIVE9_LOCAL_DSN='root@tcp(127.0.0.1:4000)/drive9_local?parseTime=true' make run-server-local ``` Then probe it with curl: ```bash curl http://127.0.0.1:9009/healthz curl -X POST http://127.0.0.1:9009/v1/provision ``` Public HTTP / CLI / FUSE smokes live in `mem9-ai/drive9`. `make e2e-local` builds this server and grafts that e2e. Blackbox (POSIX / perf / workflow) is the same graft onto drive9 `blackbox/run.py`. Shared-schema stays here: ```bash make e2e-local make blackbox-local bash e2e/shared-smoke-test.sh ``` ## Development ```bash make test make lint make build ``` TiDB-backed tests use testcontainers automatically; set `DRIVE9_TEST_TIDB_DSN` to reuse an existing instance. See `AGENTS.md` for the full development guide. ## Boundaries - This repository maintains server-side code only; client code lives elsewhere. - TiDB Filesystem keeps workspace state; another system still runs the sandbox process. - It does not preserve live processes, sockets, terminals, or in-memory model context. - It is not a Git replacement; Git remains the final review and history layer. ## Documentation - [LayerFS V1 design](docs/design/layered-filesystem-v1-design.md) - [Metadata schema refactor](docs/design/metadata-schema-refactor.md) - [Git fast clone workspace design](docs/design/git-fast-clone-workspace.md) - [Agent vault phase 0 design](docs/design/agent-vault-phase0.md) ## License Apache 2.0.