Freestyle Docs

Freestyle / Guides

How to Use S3 as a Git Remote in a Sandbox

Mount an S3-backed Git repository without downloading every file first, keep dependency I/O on local disk, and scope storage access at the edge.

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@latest
bun add freestyle@latest
npm install freestyle@latest
yarn add freestyle@latest

Supply these environment variables to the controller:

  • FREESTYLE_API_KEY: your Freestyle API key.
  • AWS_ACCESS_KEY_ID and AWS_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_bundle points boto3 at the system trust store, which holds the Freestyle platform CA.
  • request_checksum_calculation = when_required stops 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.

esc