ArtifactFSとは：巨大gitリポジトリをcloneせず即マウントするCloudflareのFUSEドライバ

巨大なモノレポをAIエージェントやサンドボックスに渡したいとき、最初の git clone がボトルネックになる。数GBのリポジトリを丸ごとダウンロードし終えるまで、エージェントは何もできない。この「起動の待ち時間」を、ArtifactFS（cloudflare/artifact-fs）は「cloneを待たずにマウントし、ファイル内容は読まれた瞬間に取りに行く」という発想で削りにきた。GitHubのリポジトリ説明はこうだ——「a filesystem driver designed to mount large git repos as quickly as possible, hydrating file contents on-the-fly instead of blocking on the initial clone. It’s ideal for agents, sandboxes, containers and other use-cases where startup time is critical.」。

本記事では、artifactfs の正体・仕組み（遅延ハイドレーション）・インストール・アーキテクチャ・制限までを、公式README／go.mod／連携サンプルの一次情報だけで日本語に整理する。Go製・Apache-2.0・GitHubスター約1,080（2026-08-11時点）で、日本語の解説はまだほぼ存在しない。

このプリミティブが誰のためのものかは、エージェント全体像の中で捉えると分かりやすい。まずAIエージェントフレームワーク比較2026｜LangGraph・CrewAI・Dify等9種をStar数・実コードで検証で「エージェントに作業環境を与える」層の位置づけを押さえると、ArtifactFSが「フレームワーク」ではなく「エージェントが踏む足場（ファイルシステム）」の側であることが見えてくる。

ArtifactFSとは——巨大gitリポジトリを「cloneせず」即マウントするFUSEドライバ

READMEの定義はこうだ。「ArtifactFS is a Git-backed filesystem daemon (FUSE driver) in Go that mounts repositories as normal working trees while avoiding eager blob downloads.」——gitを裏に持つFUSEファイルシステム・デーモンで、リポジトリを普通のワーキングツリーとしてマウントしつつ、blob（ファイル内容）の先読みダウンロードを避ける。続けて「It exposes the tree quickly, then hydrates file contents on demand. That makes it useful for sandboxes, agents, and other short-lived environments where waiting for a full clone is too expensive.」——ツリーを素早く見せ、内容はオンデマンドで“注水（hydrate）”する。だからclone待ちが高くつく短命環境で有用だ、と。

ここで押さえるべきは、ArtifactFSが単体の魔法ではなく Cloudflare Artifacts という文脈の中の一部品だという点だ。READMEの「What are Cloudflare Artifacts?」節はこう説明する。「Cloudflare Artifacts is a versioned filesystem that speaks git. It is built for agent toolchains, sandboxes, and CI/CD systems that need fast access to code repositories.」——gitを話すバージョン付きファイルシステムで、エージェントのツールチェーン・サンドボックス・CI/CDのために作られている。そして「ArtifactFS is the optional FUSE driver – it lets you mount an Artifact (or any git repo) as a local filesystem without waiting for a full clone.」と、ArtifactFSはそのオプションのFUSEドライバだと位置づける。

Cloudflareは「エージェントにファイルシステムを与える」という同じ課題に、複数のプリミティブで別々の角度から取り組んでいる。Cloudflare Computer（Durable Object内の永続仮想FS）が「エッジに小さな作業机を常設する」側だとすれば、cloudflare artifact-fs は「既存の巨大gitリポジトリを待たずに開く」側だ。両者は公式に連携が明記されているわけではないが、担う仕事が対照的で、組み合わせ方を考えるうえで両方を知っておく価値がある。各プリミティブが「何を主眼にするか」を、それぞれの公式説明ベースで並べると位置づけがはっきりする。

※上表は各リポジトリ/製品の公式説明を基にした位置づけの整理で、3者が相互に依存すると主張するものではない（ArtifactFSとSandbox SDKの連携のみ公式サンプルで明示されている）。「git マウント」という切り口で見ると、ArtifactFSはこの3者の中で唯一「既存リポジトリを開く速度」に特化している。

仕組み：ツリーは即表示、blobはオンデマンド（遅延ハイドレーション）

ArtifactFSの肝は「ハイドレーション（blobのダウンロード）が透過的」であることだ。READMEはこう書く。「Hydration (blob downloading) is transparent: the file tree is visible immediately after mount, and reads block only until the requested blob is fetched. The daemon prioritizes code and manifests (package.json, go.mod, README.md) over binary files.」——マウント直後にファイルツリーが見え、読み取りは要求されたblobが取得されるまでの間だけブロックする。デーモンはコードやマニフェスト（package.json・go.mod・README.md）をバイナリより優先する。

従来のワークフローでは、リポジトリを使うには「まず全部を手元に持ってくる（clone）」ことが暗黙の前提だった。ArtifactFSはこの前提を外し、「まずツリー構造という“目次”だけを持ち、本文（blob）は開いたページから取り寄せる」という図書館的な発想に切り替える。つまり利用者から見た体験はこうなる。

・マウント直後、ls はリポジトリ全体のツリーをほぼ即座に返す（内容はまだ無い）
・あるファイルを cat した瞬間、そのblobだけがネットワーク越しに取得され、その読み取りだけが一瞬待つ
・依存解決に必要な package.json / go.mod などは優先的に注水され、巨大バイナリは後回し
・裏では watcher が HEAD/refs を500msごとにポーリングし、HEADの変化を反映する

この「ツリー即・内容遅延」というモデルが効くのは、実際に読まれるファイルがリポジトリ全体のごく一部に留まるケースだ。数GBのモノレポでも、ある1つのパッケージをビルドしたり、エージェントが数十ファイルを読んで1機能を直したりする作業では、触るファイルは全体の数%に過ぎないことが多い。従来のフルcloneは「使うか分からない残り97%」まで含めて全部ダウンロードし終えるまで待たせるが、ArtifactFSは触れられたものだけを取りに行くので、体感の立ち上がりが「リポジトリの大きさ」ではなく「実際に読む量」に比例するようになる。逆に、全ファイルを満遍なく舐める処理（後述の git status のようなツリー全走査）ではこの前提が崩れ、FUSE越しのオーバーヘッドが表に出る。つまりArtifactFSは「広く浅く全部を読む」用途ではなく、「大きいリポジトリの一部を素早く使い始める」用途に最適化されたトレードオフを取っている。

図の通り、初回の取得は「blobless clone」——リモートが部分clone（partial-clone filtering）に対応していれば、最初はcommits・trees・refsだけを取得し、blobは落とさない。READMEいわく「When the remote advertises partial-clone filtering, only commits, trees, and refs are fetched initially; otherwise Git falls back to downloading blobs eagerly.」（対応していないリモートでは従来通りblobを先読みしてしまう点は要注意）。全パスは git ls-tree -r -t -z で列挙し、サイズは git cat-file --batch-check（GIT_NO_LAZY_FETCH=1）でローカル解決して、SQLiteの base_nodes テーブルに一括投入する。

Cloudflare ArtifactFSのインストールと使い方

要件はシンプルだ。READMEは「Requires Go 1.25+ and a FUSE implementation」とし、FUSE実装として macOS＝macFUSE / Linux＝fuse3（apt install fuse3 ないし dnf install fuse3）を挙げる。インストールは go install 一発。

go install github.com/cloudflare/artifact-fs/cmd/artifact-fs@latest

FUSE実装が未導入なら先に入れておく（ソースからビルドする場合はあわせて go build）。

# Linux（Debian/Ubuntu）
sudo apt install fuse3
# macOS は https://osxfuse.github.io/ から macFUSE を導入

# ソースからビルドする場合
go build -o artifact-fs github.com/cloudflare/artifact-fs/cmd/artifact-fs

使い方は「リポジトリを登録してスナップショットを作る（add-repo）」→「デーモンを起動してFUSEマウントする（daemon）」の2段だ。READMEのクイックスタートがそのまま最短経路になる。

export ARTIFACT_FS_ROOT=/tmp/artifact-fs-test

# 登録・（blobless）clone・初期スナップショット作成
./artifact-fs add-repo \
  --name workers-sdk \
  --remote https://github.com/cloudflare/workers-sdk.git \
  --ref refs/heads/main \
  --mount-root /tmp

# デーモン起動（FUSEマウント。killするまでブロック）
./artifact-fs daemon --root /tmp &
DAEMON_PID=$!

# 使う
ls /tmp/workers-sdk/
cat /tmp/workers-sdk/README.md
git -C /tmp/workers-sdk log --oneline -5

# 後始末
kill $DAEMON_PID

マウント先の中に合成された .git（gitfile）が置かれ、実gitdirを指すので、マウント内で git コマンドがそのまま動く。運用で効くフラグも押さえておきたい。

アーキテクチャ：setup と daemon の2フェーズ

ArtifactFSは大きく 一度きりのセットアップ（add-repo：登録と高速なbloblessクローンの準備）と、常駐デーモン（FUSEでマウントしファイル操作を提供）に分かれる。デーモン側は複数のサブシステムで構成される。

・gitstore：リモートからのblobless clone／検証済みソース取得
・snapshot：git ls-tree で列挙した全パスを SQLite base_nodes に「世代（generation）」として保持
・fusefs：ツリーを即公開するFUSE層。合成 .git gitfileで実gitdirへ橋渡し
・hydrator：優先度キュー。読み取り時に永続 git cat-file --batch プロセスでblobを取得しキャッシュへストリーム
・overlay：書き込みはコピーオンライトでbaseからoverlay（SQLite＋upper/ディレクトリ）へ昇格。削除はwhiteoutで記録
・watcher：HEAD/refsを500msごとにポーリングし、HEAD変更を再公開

SQLiteは WAL モードのピュアGo実装（modernc.org/sqlite）を使い、FUSEは github.com/jacobsa/fuse、CLIは github.com/urfave/cli に依存する。準備のタイムアウトは30分、一時的な転送失敗は最大3回まで再試行する、といった運用パラメータもREADMEに明記されている。実装は TigrisFS・gitfs・SlothFS から着想を得たとクレジットされている。

何に使える？sandbox / agents / CI と Sandbox SDK連携

用途はREADMEが繰り返し述べる通り、「起動時間が命の短命環境」だ。具体的には——

・サンドボックス／コンテナ：起動のたびにフルcloneせず、即マウントして必要な分だけ取得
・AIエージェントのツールチェーン：エージェントが巨大リポジトリを「開いた瞬間」から読み書きできる
・CI/CD：ジョブが「デプロイで選ばれた正確なリビジョン」を検証したい場合に --require-commit で固定

CIでの「検証済みソース」運用も具体的だ。ジョブが「デプロイで実際に選ばれたコミット」を必ず読みたい場合、--require-commit "$DEPLOY_SHA"（40桁か64桁の完全オブジェクトID）を指定すると、そのリビジョンだけをマウント対象に固定できる。--depth 1 や --refresh never と組み合わせれば、更新を追わない浅い一回きりのマウントになり、CIランナーの立ち上げを軽くできる。書き込みはコピーオンライト（overlay）で扱われ、baseのファイルは編集時にupperへ昇格、削除はwhiteoutで記録されるため、エージェントがマウント内のコードを編集しても元リポジトリを汚さない——この点は、コードを書き換えながら試行錯誤するエージェント用途と相性がよい。

とりわけ Cloudflare Sandbox SDK との連携 は公式サンプルとして用意されている（examples/cloudflare-sandbox-sdk）。Workerが隔離コンテナを起動し、公開gitリポジトリをコンテナ内にマウントして、ArtifactFSがFUSEで内容をオンデマンド取得する構成だ。同じく隔離実行を扱うCubeSandbox（60ms起動のmicroVMでエージェントを安全実行）が「実行環境そのものを速く立てる」アプローチなら、ArtifactFSは「その環境に載せるコード（gitツリー）を速く見せる」レイヤーであり、レイヤーが異なる。

コードを自律的に編集・実行するOpenHandsのようなエージェントでも、対象が数GB級のモノレポなら「最初のcloneで詰まる」問題は共通だ。ArtifactFSはその足場を「clone待ちゼロ」で用意する部品として噛み合う（ただし前述の通りベータで、FUSE全走査系の操作は遅い点に留意）。

制限と注意点

導入前に、READMEが率直に挙げる制約を押さえておく。

・ベータ：安定版1.0.0は未リリース（最新 1.0.0-rc.9）。破壊的変更があり得る
・FUSE全走査が遅い：git status ~7秒（5,800エントリ超）、git reset ~6.5秒。ツリー全体を舐める操作は不利
・要件：Go 1.25+ と FUSE 実装（macOS=macFUSE / Linux=fuse3）。WindowsネイティブFUSEはREADMEに記載なし
・partial-clone非対応リモート：blobを先読みしてしまい、「cloneしない」利点が薄れる
・速度の“倍率”は非公表：起動の速さは定性的な主張で、公式に「N倍速」といった数値は無い

参照ソース

・cloudflare/artifact-fs（公式リポジトリ・README） — 定義・遅延ハイドレーション・アーキテクチャ・制限・要件の一次情報
・Cloudflare Artifacts（製品ページ） — 「gitを話すバージョン付きファイルシステム」という上位文脈
・artifact-fs examples/cloudflare-sandbox-sdk（連携サンプル） — Sandbox SDK上でのマウント構成
・artifact-fs go.mod（依存関係） — Go 1.25・jacobsa/fuse・modernc.org/sqlite 等の裏取り