LFS Cloud

LFS Cloud is a self-hosted Git LFS server and companion CLI that stores large files in Google Drive while keeping the Git repository on GitHub.

LFS Cloud is preparing for its first release. The release tooling now builds checksummed binaries, direct installers, Debian packages, Homebrew metadata, and WinGet manifests; Cloudsmith APT publication is optional. These channels will not resolve until the first release is published. Binary signatures and macOS notarization are not available yet.

Maintainers should use yarn release:all patch (or minor/major) as the preferred manual release entry point. See the all-in-one fleet release guide for prerequisites, recovery behavior, and lower-level commands.

LFS Cloud keeps repository history and permissions on GitHub, proxies Git LFS uploads and downloads, and stores the object bytes in a private Google Drive folder:

Git LFS client <-> LFS Cloud <-> Google Drive
                         |
                         +-> GitHub permission checks

It also provides a shared local object cache. On supported filesystems, checked out files can use copy-on-write materialization to reduce duplicate disk usage.

Each user logs in with their own GitHub PAT. LFS Cloud verifies that identity with GitHub and checks the user's current permission on every configured repository: read access permits LFS downloads, while write access permits uploads and migration.

Every installation needs:

• Git and Git LFS
• Google Cloud CLI (gcloud)
• a Git credential helper
• a GitHub personal access token limited to the repositories you will serve
• GitHub CLI (gh) for the repository ID lookup shown below (optional)

Choose one of the following installation methods.

On macOS ARM64 or Linux x86-64/ARM64:

curl -fsSL https://github.com/Quicksaver/lfs-cloud/releases/latest/download/lfscloud-installer.sh | sh

On Windows x86-64:

irm https://github.com/Quicksaver/lfs-cloud/releases/latest/download/lfscloud-installer.ps1 | iex

The install scripts verify the release checksum and executable version, install into ~/.local/bin by default, and do not modify PATH or invoke elevated privileges. Version pinning and custom install directories are documented in Install, build, and release details.

Install with Homebrew:

brew install Quicksaver/tap/lfscloud

Install with WinGet:

winget install --exact --id Quicksaver.LFSCloud

This option requires Rust 1.88 or newer:

cargo install --locked --path .

Initialize Git LFS after installing LFS Cloud:

git lfs install

Create a Google Cloud Desktop OAuth client, enable the Google Drive API, and authorize an isolated Application Default Credentials directory with the cloud-platform and drive.file scopes. The complete setup commands and folder-access requirements are in the configuration guide.

Create or choose the private Drive folder that will hold LFS objects, then keep its folder ID for the server configuration.

Create a private server configuration file at ${HOME}/lfscloud.yml. On Windows, LFS Cloud falls back to %USERPROFILE%\lfscloud.yml when HOME is not set. This is the default path whenever --config PATH is omitted. Do not commit the file.

server: {}

repository_providers:
  github:
    type: github

storage_providers:
  drive-personal:
    type: google_drive
    credentials:
      type: gcloud
      config_dir: ${HOME}/.config/lfscloud/gcloud-drive
    root_folder_id: YOUR_DRIVE_FOLDER_ID

repositories:
  - id: github:OWNER/REPOSITORY
    repo_provider: github
    host: github.com
    owner: OWNER
    name: REPOSITORY
    provider_repository_id: '123456789'
    storage_provider: drive-personal

The server defaults to port 15370 on 0.0.0.0, so it accepts connections through loopback, LAN, and direct Tailscale IPv4 addresses without network fields in the config. Git LFS action URLs are inferred from the interface each client connected to. Set server.public_url only when clients should receive a different hostname or path, such as a MagicDNS name or reverse proxy URL.

GitHub providers use https://api.github.com by default. Set api_url only for an alternative REST endpoint such as GitHub Enterprise Server.

The same provider and repository entries can be added interactively:

lfscloud config repository add
lfscloud config storage add
lfscloud repository add

Create the file and its server section first. Passing no entry flags prompts for the complete entry; passing any entry flag makes add non-interactive. Existing IDs can be updated with only the fields that should change. See Manage Configuration From The CLI for every flag plus list and remove.

Get GitHub's stable numeric repository ID with:

gh api repos/OWNER/REPOSITORY --jq .id

See the configuration guide for the full schema, security constraints, request limits, metadata paths, and LAN/HTTPS setup.

Start LFS Cloud:

lfscloud serve

On first run, LFS Cloud generates its durable-session encryption key and stores it in the operating system's native credential store: macOS Keychain, Windows Credential Manager, or Secret Service on Linux. The server validates its configuration, native key access, Google Drive credentials, and Drive root before it begins accepting requests.

From the configured Git repository:

lfscloud init --server http://127.0.0.1:15370
lfscloud login --server http://127.0.0.1:15370
lfscloud status

init writes the repository-specific endpoint to .lfsconfig. Use --local to write only repository-local Git config instead. login verifies your GitHub PAT, creates a short-lived LFS Cloud session, and stores only the opaque local token through Git's credential helper. The PAT stays encrypted on the server for current GitHub permission checks.

After setup, normal Git and Git LFS pushes and fetches use LFS Cloud. For a new LFS pattern, configure Git LFS as usual:

git lfs track "*.bin"
git add .gitattributes .lfsconfig

Use a non-shallow clone with all source branches and tags available. Keep the source LFS endpoint configured while planning and transferring:

lfscloud login --server http://127.0.0.1:15370
lfscloud migrate \
  --server http://127.0.0.1:15370 \
  --all-refs \
  --dry-run
lfscloud migrate \
  --server http://127.0.0.1:15370 \
  --all-refs
git add .lfsconfig
git commit -m "Route Git LFS through LFS Cloud"

Execution authenticates a write request to the repository's LFS Cloud route, refreshes the selected source remote's branches and tags, and inventories every historical LFS pointer. It asks the server which objects are already present before fetching source bytes, fetches only the target-missing subset, and uploads those bytes through server-issued Git LFS actions. The client never reads the private server config or accesses Google Drive directly. Repository configuration is updated only after the complete target inventory succeeds.

If any target object fails, neither target config location is changed. A retry safely asks LFS Cloud again, so objects completed by an earlier user or interrupted run are skipped. If .lfsconfig already names the target, rerun the same migration command; migration ignores that target as a source and falls through to the committed legacy remote URL or the selected Git remote's default LFS endpoint for any remaining target-missing objects.

Migration writes the target to both .lfsconfig and repository-local lfs.url. Before switching, it also records the old endpoint as the standard remote.<source>.lfsurl field in .lfsconfig; follow-up users can therefore migrate their local-only objects without private server configuration. The repository-wide target remains active for normal Git LFS traffic, while migration applies the legacy URL only to its source fetch command. Git history and LFS pointers are not rewritten, and URLs containing credentials are never committed.

Follow-up migration fetches request only the target-missing object IDs. Git LFS currently resolves those through one bounded smudge invocation per object, so source recovery time scales with the number of missing objects rather than the complete repository inventory.

Execution requires --all-refs; narrower current-checkout and --ref scopes remain available for dry-run investigation only. --source-remote defaults to origin. Use --allow-cross-remote only for an intentional copy between different repository identities. --purge-source-lfs reports cleanup guidance but never automatically deletes source objects.

Run lfscloud <command> --help for all options.

• GitHub and Google Drive are the only implemented providers.
• Users supply their own GitHub PATs; OAuth/device-flow login is not implemented.
• Uploads and downloads are proxied through the LFS Cloud process, so the host must support long-lived large-file transfers.
• The package channels will remain unavailable until the first release is published; release binaries are not signed or notarized yet.

The default listener makes the server reachable from trusted LAN and Tailscale interfaces, but it does not add TLS. Plain HTTP over a LAN exposes GitHub PATs during login, local LFS credentials, and object bytes to network observers; client commands therefore require --allow-insecure-http for non-loopback HTTP. Prefer HTTPS on any network you do not fully trust. Direct Tailscale traffic is encrypted by the tailnet tunnel, although the application URL remains HTTP.

• Server configuration
• Install, build, and release details
• Historical implementation notes
• Historical implementation review findings
• Archived pre-release README

The historical documents preserve design and implementation context; they are not the current user guide and may describe superseded plans.

LFS Cloud is available under the MIT License.