ArtifactFS - 大きな Git リポジトリをファイルシステムのように即マウントする

agent、sandbox、CI を触っていると、結局いつも同じ待ち時間にぶつかります。実際の処理を始める前に、大きな repository を丸ごと clone する時間です。多くの job は最初から全 blob を必要としているわけではなく、まずは directory を見て、設定 file を数個読み、少し解析できれば十分なのに、起動時間は full clone に引っ張られます。

今日取り上げたい cloudflare/artifact-fs は、まさにそこを狙った project です。Go で書かれた Git-backed FUSE filesystem daemon で、考え方はかなり明快です。まず blobless clone で repository tree をすばやく用意し、その後に FUSE で working tree として見せ、実際に file を読むタイミングで必要な blob だけを取得します。つまり、tree は先に見え、code や manifest は優先して hydration され、大きな blob は後回しになります。

公開時点の GitHub page では、project は約 991 stars、38 forks。主言語は Go、license は Apache-2.0 です。Repository の作成日は 2026-03-29。README では現在の状態を beta と明記していて、公開されている最新 tag は 1.0.0-rc.1 でした。

Project overview

項目	内容
Repository	cloudflare/artifact-fs
位置づけ	Git repository を高速に mount する FUSE ベースの working tree
Stars	約 991
Forks	38
主要言語	Go
License	Apache-2.0
現在の状態	Beta
Latest tag	`1.0.0-rc.1`

解いているのは clone の高速化より「先に作業開始すること」

repository download を速くする tool はいろいろありますが、artifact-fs の発想は少し違います。大事なのは「できるだけ早く全部取ること」ではなく、「全部取る前に仕事を始められること」です。

README にある基本の流れは二段構えです。

add-repo で git clone --filter=blob:none を実行する
daemon でその repo を FUSE 経由で mount する
file を読む時だけ backend で必要な blob を取得する

この設計だと、OS からは directory tree がほぼすぐ見えます。agent 側は full clone 完了を待たずに、先に次のような作業へ入れます。

package.json や go.mod、README.md を探す
directory structure を走査する
軽い解析や index を作る
少数の source file だけ開く

短命な execution environment では、最初に必要なのは完全な working copy ではなく、まず見える tree であることが多いので、この方向性はかなり実務的です。

agent と sandbox 向けに効くのは lazy hydration だけではない

この project が面白いのは、単に file content を後から取るだけで終わっていないことです。周辺の runtime model まで含めて、agent 向けの現実的な working tree に寄せています。

README では主な利用先として次が挙げられています。

agents
sandboxes
containers
CI/CD

これは単なる説明文ではなく、実際にその用途を意識した実装になっています。

まず、mount は read-only ではありません。local な変更は overlay に入り、tracked file は copy-on-write で昇格し、delete は whiteout として記録されます。新しい file や directory も overlay 側に保持されます。つまり、単なる repo browser ではなく、普通の working tree に近い操作感を目指しています。

さらに、README 上で検証済みとして挙げられている Git 操作も意外と広いです。

git log
git status
git diff
git add
git commit
git checkout
git fetch

agent 用の mount layer は「読めるが書けない」か、「書けても Git が追随しない」ことが多いので、ここまで揃っているのはかなり重要です。

snapshot、overlay、hydrator、watcher まで分けた構成が堅い

README の architecture section も見どころです。単純な proxy 的実装ではなく、役割分担がかなり明確です。

snapshot: Git tree を SQLite に index する
overlay: local write と delete 状態を保持する
hydrator: 優先度付きで blob を取得する
watcher: HEAD、refs、index の変化を監視する
resolver / engine: snapshot と overlay を統合して見える tree を作る

特に重要なのは二点あります。

第一に、tree metadata と blob content を意図的に分離していることです。git ls-tree と git cat-file --batch-check で tree 側を先に固め、実 content は必要時に git cat-file --batch で取る。この分離があるからこそ、「先に mount、後で hydration」が成立しています。

第二に、local change がきちんと状態として持続することです。overlay と upper/ directory を持ち、HEAD 変化後には reconciliation も走ります。つまり、commit や checkout をまたいでも mount view を保つ前提で考えられていて、demo を超えた構造になっています。

container 向けの入口も最初から用意されている

この種の tool は、container に入れた瞬間に運用条件が急に重くなることがあります。artifact-fs はその点も README でかなり具体的です。

Repository には examples/Dockerfile があり、実行時には次が必要だと明記されています。

--cap-add SYS_ADMIN
--device /dev/fuse

さらに Ubuntu など AppArmor 有効な host では、

--security-opt apparmor:unconfined

も推奨されています。

つまり、作者は最初から「隔離環境で mount して使う」ことを現実的な main use case として見ています。agent runtime や code analysis sandbox を作る側にとって、ここまで書かれているのは助かります。

制約もかなり正直に書かれている

この project で好印象なのは、README が現状の限界を隠していないことです。

たとえば大きめの repo では、

git status が約 7 秒
git reset の index refresh が約 6.5 秒

かかる場合があると書かれています。原因も明確で、tree walk や index refresh がまだ重いからです。しかも project 自体が beta で、前提として macFUSE か Linux の fuse3 が必要です。

なので、これは「今日からすべての clone を置き換える完成品」というより、

repository が大きい
execution は短命
最初に読む file は少ない
full local copy より startup latency が重要

という workload に強い、かなり筋の良い基盤と見るのが自然です。逆に、長時間の重い編集や全量 Git 操作をひたすら回す用途では、まだ default choice とは言いにくいはずです。

まとめ

cloudflare/artifact-fs の面白さは、単なる lazy blob download ではなく、それを本当に使える working-tree 風の FUSE layer に仕立てているところです。blobless clone で tree を先に出し、SQLite の snapshot と overlay で view を管理し、hydrator で必要な file content を後から埋める。この構成は agent や sandbox の起動コストをかなり素直に削りに行っています。

大きな repository を扱うのに、実際に読む file は最初の数個だけ、という workload を抱えているなら、この 1000 stars 未満の project はかなり見る価値があります。