ArtifactFS: mounting a git repository without waiting for the clone

The tree appears before the blobs do

ArtifactFS is a filesystem daemon written in Go that mounts a git repository as an ordinary working tree, and the point of the design is that the two halves of a clone are separated. The operating system sees the full tree almost immediately, while the FUSE driver fetches file contents in the background. A read blocks only until the blob it needs has arrived. For the environments the project targets, which the README names as sandboxes, agents and other short-lived contexts where a full clone is too slow, that reordering is the whole value. The project describes itself as a beta release and warns that your mileage may vary, which is the appropriate frame for a driver that intercepts filesystem calls on behalf of a build tool.

Manifests and source are fetched before large binaries

Hydration is not a blind queue. The daemon prioritises code and manifests, with the README naming package.json, go.mod and README.md as examples, ahead of binary files. That ordering reflects how a toolchain actually uses a repository: a build needs the manifest to decide what to do, and only then reaches for the artefacts. It also means the worst case for a slow operation is a large binary, not the whole tree. The number of parallel blob-fetch workers is tunable through a --hydration-concurrency flag that defaults to 4, and each worker keeps a persistent git cat-file --batch process open, so raising the number trades memory for throughput. For a repository dominated by binaries the prioritisation buys less, and the flag becomes the only lever you have.

The daemon mounts, blocks and reports its own state

The CLI has three working parts. add-repo registers a remote, clones it and builds the initial snapshot, writing the result under a root directory. The daemon then starts, mounts through FUSE and blocks until it is killed. Third, status reports the condition of a mounted repository as a single line of key and value pairs, and the README documents each field.

export ARTIFACT_FS_ROOT=/tmp/artifact-fs-test

./artifact-fs add-repo \
  --name workers-sdk \
  --remote https://github.com/cloudflare/workers-sdk.git \
  --ref refs/heads/main \
  --mount-root /tmp

./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

Because the mount happens under the mount root, the repository path is the name you gave it, which is why the example reads files at /tmp/workers-sdk. The status output distinguishes states of mounted, unmounted, preparing and failed, and tracks hydrated_blobs and hydrated_bytes so you can see how much of the repository has actually landed.

An overlay holds local changes, and a dirty flag tells you they exist

The status fields describe two generations of content. base_commit is the commit backing the currently published filesystem generation, while head and ref are described as backward-compatible aliases for the current base commit and the Git HEAD ref. On top of that sits an overlay, and overlay_dirty is true when the overlay contains created or modified files. The README adds a precise caveat: delete-only overlays are not counted, so a clean flag does not strictly mean nothing was changed locally. A reader building a workflow on top of this needs to read that field carefully, because a mount that only removed files reports as clean.

Preparation is bounded by a timeout and a retry policy

The daemon does not wait forever. Preparation has a 30-minute timeout, and clone and fetch operations retry known transient transport failures up to three total attempts. Caller cancellation stops the active git command and the retry backoff, with synchronous preparation recording a redacted prepare canceled status, while daemon shutdown leaves asynchronous preparation queued for restart. Those two cancellation paths behave differently on purpose, and the difference matters if you script around the CLI. For an existing clone, the asynchronous path reports remote configuration, fetch and branch update as separate phases called configure_remote, fetch and update_branch, so a failure can be attributed to a step rather than to preparation as a whole.

Logs are newline-delimited JSON with a fixed shape

Everything the daemon emits goes to stderr as newline-delimited JSON, and the README shows representative lines for a successful preparation, a transient failure that recovers, and a timeout. The fields are stable enough to parse: time, level, msg, repo, mode, source, attempt, phase, state, duration_ms, deadline_set and timeout_ms appear on preparation lines, while failure lines add max_attempts, retryable, timed_out and canceled, and a recovery line reports the number of attempts and the total duration. The timeout line is truncated in the README itself, so the full shape of a failure record beyond the visible prefix is not documented there, though the accompanying table of status fields is complete.

Building it needs Go 1.26 and a FUSE implementation on the host

The build requirements are specific. Go 1.26 or newer is required, and the host needs a FUSE implementation: macFUSE on macOS, and fuse3 on Linux, which the README gives as apt install fuse3 on Debian and Ubuntu and dnf install fuse3 on Fedora. The CLI installs from the module path.

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

Or you can build the binary directly from the same module path.

go build -o artifact-fs github.com/cloudflare/artifact-fs/cmd/artifact-fs

The go.mod file confirms the small dependency surface: the jacobsa/fuse binding, urfave/cli for the command line, golang.org/x/sys and modernc.org/sqlite, which is a pure Go SQLite build and avoids a cgo toolchain requirement. The repository root shows the testing posture as well, with separate end-to-end files for async preparation, git operations, benchmarks and per-platform setup for Darwin and Linux.

Apache-2.0, release-candidate tags, and an example Docker image

The project is Apache-2.0 licensed, so it can be used in commercial and closed-source products with attribution, and it is published by Cloudflare as part of Cloudflare Artifacts, a versioned filesystem that speaks git, which the product page describes as built for agent toolchains, sandboxes and CI/CD systems. The releases are still labelled release candidates, with 1.0.0-rc.10 on 2026-08-12, 1.0.0-rc.9 on 2026-07-27 and 1.0.0-rc.8 on 2026-07-26, and the last push was on 2026-09-11. The repository ships an examples directory with a Dockerfile, an entrypoint script and a cloudflare-sandbox-sdk folder, which is the closest thing in the tree to a deployment recipe for the sandboxes the tool is designed for.

Editorial conclusion

ArtifactFS is a good fit for short-lived environments, agent sandboxes and CI steps that need a repository tree almost immediately, because the mount replaces a blocking clone with a background hydration that only stalls on the specific file being read. It is not a fit for a developer workstation, since the tree is assembled from a git remote plus an overlay and the README does not describe a workflow for committing local changes back. Verify first that your environment has a FUSE implementation available, macFUSE on macOS or fuse3 on Linux, and that the machine running the daemon can reach your git remote, since a failed fetch surfaces as a prepare_error in the status output rather than at mount time.

Frequently asked questions

Official sources

1. cloudflare/artifact-fs on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases