Store Git repositories in an S3 bucket and mount a working tree in a sandbox
without downloading all file contents first. The sandbox can start before the
repository is mounted. There is no Git server: the bucket is the remote, and
each repository is a key prefix such as s3+lazy://my-bucket/repos/<repoId>.
The sandbox never holds the storage key. A TLS rule with an
s3 transform
signs requests at the edge and rejects requests outside the repository prefix.
Freestyle’s Ubuntu sandboxes include the open-source S3 Git helpers and a pinned build of
Cloudflare ArtifactFS.
The helpers support prefix-scoped access and s3+lazy://: commits and
trees arrive first, while Git blobs are fetched when files are read. ArtifactFS
exposes those files through FUSE. Metadata still has to transfer and the tree
still has to be indexed; this is not a zero-download mount.
Start a VM from freestyle/ubuntu or any Ubuntu size variant, configure its S3
access, and mount your repository. Git, Git LFS, FUSE 3, git-remote-s3,
git-remote-s3+lazy, git-lfs-s3, git-s3-workspace, and ArtifactFS are already
installed. You do not need to install packages, access the helper’s source
repository, or create a custom base snapshot.
Prepare the Controller
Run the TypeScript examples in your trusted controller, outside the sandbox. Install the SDK there:
pnpm add freestyle@latestbun add freestyle@latestnpm install freestyle@latestyarn add freestyle@latest Supply these environment variables to the controller:
FREESTYLE_API_KEY: your Freestyle API key.AWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEY: a key with access to the bucket.
Start the Sandbox
Create a standard Ubuntu sandbox from the controller. The S3 workspace tools are ready to use when it starts:
import { Freestyle } from "freestyle";
const freestyle = new Freestyle();
const { vm, vmId } = await freestyle.vms.create({
snapshotId: "freestyle/ubuntu",
firewall: { rules: [{ action: "allow", source: {}, destination: { public: true } }] },
});
Next, grant this sandbox access to your repository prefix and configure its AWS
profile. Then run git-s3-workspace mount inside it. The sandbox does not need
package-registry or GitHub access to install these tools at startup.
Grant the Sandbox One Repository
Create a TLS rule for the sandbox, scoped to one repository prefix. End the
prefix with /: repos/p1 also matches repos/p10.
const endpoint = "https://s3.us-west-2.amazonaws.com";
const repoId = "my-repo";
const READ = ["GetObject", "HeadObject", "ListObjects", "ListObjectsV2"];
const WRITE = [
...READ, "PutObject", "DeleteObject",
"CreateMultipartUpload", "UploadPart", "ListParts",
"CompleteMultipartUpload", "AbortMultipartUpload", "ListMultipartUploads",
];
const { id: ruleId } = await freestyle.tls.rules.create({
action: "allow",
domain: new URL(endpoint).host,
source: { vmId },
destination: { public: true },
transform: [{
s3: {
region: "us-west-2",
credentials: {
accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
},
scope: {
bucket: "my-bucket",
prefix: `repos/${repoId}/`,
operations: WRITE,
},
},
}],
});
READ is enough for mount, on-demand reads, clone, fetch, and LFS downloads.
Push needs WRITE. The storage service must support conditional PutObject
with If-Match and If-None-Match; lazy ref publication uses those conditions
to reject concurrent stale writers.
git-lfs-s3 uploads files over 8 MiB in parts, which uses the multipart
operations.
Point the Sandbox at the Edge
Write an AWS profile with the endpoint, path-style addressing, the system CA bundle, and placeholder keys. The edge replaces the placeholder signature with one made from the rule’s credentials.
await vm.exec("mkdir -p /home/ubuntu/.aws");
await vm.fs.writeTextFile(
"/home/ubuntu/.aws/config",
`[default]
region = us-west-2
endpoint_url = ${endpoint}
ca_bundle = /etc/ssl/certs/ca-certificates.crt
request_checksum_calculation = when_required
s3 =
addressing_style = path
`,
);
await vm.fs.writeTextFile(
"/home/ubuntu/.aws/credentials",
`[default]
aws_access_key_id = placeholder
aws_secret_access_key = placeholder
`,
);
ca_bundlepoints boto3 at the system trust store, which holds the Freestyle platform CA.request_checksum_calculation = when_requiredstops boto3 from adding checksum trailers to uploads, which the edge rejects.
Seed a Lazy Repository Once
Run these commands inside a sandbox with a write rule, or from a trusted machine with bucket credentials. Start from a complete checkout:
cd repo
git remote add lazy s3+lazy://my-bucket/repos/my-repo
git push lazy HEAD:refs/heads/main
The seed uploads file blobs separately and publishes a blobless metadata pack.
The new layout is stored under repos/my-repo/v2/. The seed must finish before
another sandbox mounts that branch. Subsequent pushes upload new reachable
blobs and publish refs with a conditional write.
For a repository created with the original s3:// helper, clone it once in a
trusted environment and push to a new prefix with s3+lazy://. Push every
branch or tag you want to migrate. Existing bundle repositories stay readable
with s3://; changing the URL alone does not convert their bundles or make
them lazy. Old clients cannot read the new format.
Mount and Work
Run this inside the new sandbox, after configuring the TLS rule and AWS profile:
git-s3-workspace mount s3+lazy://my-bucket/repos/my-repo /home/ubuntu/repo \
--ref refs/heads/main
cd /home/ubuntu/repo
cat README.md
npm install
mount starts a background daemon and returns after the working tree and native
local directories are ready. It fetches commits and trees before returning;
file reads fetch the requested contents. Directory reads can prefetch a bounded
set of files. Git commands that inspect many files, such as git grep or
git status, can hydrate additional contents.
Edit files and use normal Git commands:
git add README.md
git commit -m "Update README"
git push origin HEAD:refs/heads/main
git-s3-workspace status /home/ubuntu/repo
A stale push is rejected. Fetch, merge, and retry. Remote refresh is explicit
in this wrapper; use git fetch origin and git pull --ff-only when you want
another writer’s changes. Git branch changes are reconciled by ArtifactFS.
For an ordinary checkout, use git clone s3+lazy://my-bucket/repos/my-repo repo-copy.
It downloads working-tree contents. To fetch metadata without a mounted tree:
git clone --filter=blob:none --no-checkout \
s3+lazy://my-bucket/repos/my-repo repo-metadata
A neighboring repository remains outside the rule:
git ls-remote s3+lazy://my-bucket/repos/other-repo
Keep Dependencies and Caches Fast
The wrapper bind-mounts ignored node_modules, .next, .cache, .turbo,
.venv, dist, and build directories from the VM’s local disk. It also finds
tracked package.json files and prepares ignored node_modules in those
packages. Operations inside these directories bypass FUSE and its metadata
database. npm’s relative links keep normal directory semantics.
These paths must already be ignored. Tracked files are never hidden; existing nonempty directories are preserved and skipped. Specify additional hot ignored directories at mount time:
git-s3-workspace mount s3+lazy://my-bucket/repos/my-repo /home/ubuntu/repo \
--local-dir packages/web/.next
Other ignored files still use the writable FUSE overlay. Put a high-I/O cache
in a native directory and request it with --local-dir when it is not detected
automatically. Ignoring an arbitrary file alone does not bypass FUSE.
Bind mounts require root or passwordless sudo mount and sudo umount.
Freestyle’s Ubuntu user has passwordless sudo. Native data and hydration caches
live in the mounting user’s ~/.local/share/git-s3-workspaces/; they survive
stopping and restarting the workspace and are captured by VM snapshots. They
are not included in Git pushes.
Stop the workspace before moving or removing it, or before a command removes or renames a native mountpoint itself:
git-s3-workspace stop /home/ubuntu/repo
Run mount with the same URL and path to reopen it, including after a VM reboot.
Keep its state directory while you need local changes or installed dependencies.
Store Large Files With Git LFS
For bundle repositories, track large binary files by pattern. Everything else
stays in the Git bundle. The same LFS helper also accepts s3+lazy:// URLs,
but ArtifactFS serves canonical Git blobs and does not apply LFS smudge filters.
A mounted LFS file initially contains its pointer, not the asset. Use an ordinary
clone and git lfs pull when you need materialized LFS assets.
git-lfs-s3 install sets the LFS transfer agent in the repository’s local config.
cd repo
git-lfs-s3 install --remote origin
git lfs track "*.psd" "*.mp4" "*.zip"
git add .gitattributes assets/
git commit -m "Add assets"
git push origin HEAD:refs/heads/main
LFS objects are stored at repos/my-repo/lfs/<sha256>, inside the rule’s
scope.
A clone has no LFS config until git-lfs-s3 install runs in it. Clone with
smudge off, install the agent, then download the LFS files:
GIT_LFS_SKIP_SMUDGE=1 git clone s3://my-bucket/repos/my-repo repo-copy
cd repo-copy
git-lfs-s3 install --remote origin
git lfs pull origin
Preview Limits
The lazy transport currently supports SHA-1 repositories and complete commit/tree
history with blob:none filtering. It does not support shallow history, lazy LFS
smudging, or submodule initialization. Failed pushes may leave unreachable objects;
this preview does not garbage-collect them. Use a store with working conditional
writes and keep a separate backup policy.
Remove Access
Delete the rule from the controller:
await freestyle.tls.rules.delete(ruleId);
Rules are also deleted with their sandbox. The repository stays in the bucket.