LFS Cloud

LFS Cloud is a self-hosted Git LFS server and companion CLI. Git repositories and access control stay on GitHub, while large-file bytes are stored in Google Drive.

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

Each user authenticates with their own GitHub personal access token (PAT). LFS Cloud checks that user's current repository permission for every transfer: read access permits downloads, while write access permits uploads and migration. The CLI also maintains a shared local object cache and uses copy-on-write materialization where supported.

Requirements

• Git and Git LFS, initialized for the current user
• a Git credential helper for storing the local LFS Cloud session token
• Google Cloud CLI (gcloud)
• a Google Cloud Desktop OAuth client from a project with the Drive API enabled
• GitHub CLI (gh), authenticated for interactive repository setup
• a repository-scoped GitHub PAT for each LFS Cloud user

Install

Choose one installation method.

Install Script

On macOS ARM64 or Linux x86-64/ARM64:

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

On Windows x86-64:

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

The scripts verify the release checksum and executable version, install to ~/.local/bin by default, and neither elevate privileges nor modify PATH. See Installer options for version pinning and custom destinations.

Homebrew

On macOS or Linux:

brew install Quicksaver/tap/lfscloud

WinGet

Coming soon. LFS Cloud has been submitted to the WinGet Community Repository but will not be available until the submission is accepted. Once available:

winget install --exact --id Quicksaver.LFSCloud

From Source

This requires Rust 1.88 or newer:

cargo install --locked --path .

Quick Start

1. Prepare Google Drive

Create a Google Cloud Desktop OAuth client, enable the Drive API in its project, and download the client JSON. The Google Drive configuration guide explains the required scopes and folder access.

2. Configure The Server

Run the interactive setup:

lfscloud config repository add
lfscloud config storage add
lfscloud repository add

These commands configure GitHub, authorize an isolated Google Drive credential, and map a GitHub repository to its Drive storage. See Server configuration for the YAML format and non-interactive behavior.

3. Start LFS Cloud

lfscloud serve

4. Connect A Repository

From the configured Git repository:

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

After setup, normal Git and Git LFS pushes and fetches use LFS Cloud. Configure new LFS patterns as usual:

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

Client commands use the repository route, local credential helper, and local cache without reading or creating the server's private config.yml.

Human-readable command output and logs use semantic colors when an interactive terminal supports them. Redirected output stays plain; set a non-empty NO_COLOR value, such as NO_COLOR=1, to disable colors explicitly, including in automation that allocates a pseudo-terminal.

See Repository setup for credential-helper, local-only, and network guidance.

Migrate An Existing Repository

Use a non-shallow clone. Migration refreshes the selected source remote's branches and tags before scanning its refs. Keep the existing LFS endpoint configured, then preview and run the migration against LFS Cloud:

lfscloud login
lfscloud migrate --all-refs --dry-run
lfscloud migrate --all-refs
git add .lfsconfig
git commit -m "Route Git LFS through LFS Cloud"

Migration copies LFS objects without rewriting Git history and changes repository configuration only after every target object succeeds. Interrupted runs are safe to retry. See Migration for source selection, configuration changes, and retry behavior.

Limitations And Security

• GitHub and Google Drive are the only supported providers.
• Users authenticate with GitHub PATs; OAuth and device-flow login are not supported.
• Uploads and downloads pass through the LFS Cloud process, so the host must support long-lived large-file transfers.
• Release binaries are checksummed but are not signed or notarized.
• LFS Cloud does not provide TLS termination.

The default listener accepts loopback, trusted LAN, and direct Tailscale connections. Plain HTTP over a LAN exposes GitHub PATs during login, local LFS credentials, and object bytes to network observers. 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.

Documentation

• Configuration, authentication, networking, and migration
• Installation, development, and release workflow

Run lfscloud --help or lfscloud <command> --help for command and option reference.

License

LFS Cloud is available under the MIT License.