English
YunBox works with Git LFS. PSDs, models, audio and video go straight into your own bucket on any S3-compatible storage, such as Cloudflare R2, AWS S3 or MinIO, or on Tencent Cloud COS, while your team keeps using git push and git clone as usual. No server sits in between.
npm install -g yunboxThe command line runs on macOS, Linux and Windows
Bring your own S3 bucket. Cloudflare R2 charges no egress fees, so pulling assets again and again costs nothing in download traffic. AWS S3, MinIO and any other S3-compatible service work the same way. Tencent Cloud COS is supported natively too, down to one-command sub-accounts limited to a single repository. The macOS app and these docs are in English; command-line messages are still in Chinese.
Pointer file as Git stores it
Once an asset is in, its pointer shows up here.An airport story about why code and large assets take different paths. Watch the weightlifting story and feature demo for two more ways to meet YunBox.
Code and a few lines of pointers go to your Git host as always. Assets are signed by a transfer agent on your machine and uploaded straight to your bucket. There is no server to deploy, pay for or babysit.
Your computer
git pushgit-lfs finds 3 assetsgit-yunbox lfs-agent signs with your local keyCode host
GitHub, GitLab or any Git host, as before
Received 1 commit and 3 pointer files
Your bucket
R2, S3 or COS · private, content-addressed
yunbox/team/game/04/26/0426c139eb…yunbox/team/game/59/d0/59d0ddff63…yunbox/team/game/c7/f5/c7f5f645ef…An admin connects the repository to R2 or any S3-compatible bucket (or to COS) once and gives each collaborator a key of their own. Collaborators sign in and clone; assets download on their own. If anything is off, run yunbox doctor: every failed check comes with the command that fixes it.
Connecting a repository to Cloudflare R2, done once
The command line prints its messages in Chinese for now; they are shown in English here.
The macOS app and yunbox inspect --push run the same check: Git pack and LFS candidates are counted separately, every file is listed by size, and anything over budget is flagged. Try the window below; it works.
game
/Users/alice/game
Git pack
1.24 MiB
Estimated upload after compressionBudget 900 KiB
LFS candidates
74.2 MiB
3 asset objectsBudget 100 MiB
The LFS remote has not been queried, so the actual upload size is unknown; objects already on the remote may be skipped.
Files6 of 6 objects · largest first
Git · 1,153,434 bytes
b0332ac18c4a94b5a97b3af8584d3952f79e49ef…
This image went into Git instead of LFS, which pushes Git pack over budget. Check whether .gitattributes tracks *.png.
Install the hook with yunbox hook install --confirm and an over-budget git push is not simply refused. You get the dialog below instead: which remote, which files are over, how big each one is. Then you decide whether to cancel or push anyway. You can add a one-line reason at the bottom: when an AI coding assistant started the push, it reads “cancelled, reason: compress the video first” in the output and does that, instead of raising the budget or bypassing the check with --no-verify. (The real dialog is in Chinese for now.)
Push to github.com/owner/game-assets is over the limit
Local repository game-assets (main)
1 file versions are over the per-file limit of 200.0 MiB
Git pack
2.84 MiB / 50.0 MiB
Estimated upload after compression6%
LFS candidates
810.5 MiB / 1.00 GiB
3 assets; ones already on the remote are skipped79%
Largest fileOver
412.0 MiB / 200.0 MiB
Original size206%
Changed files6 files · Added 2 · Modified 3 · Deleted 1Sorted by upload size
“This push” is the original file size; Git compresses and sends deltas. Each past version of a file counts separately.
Compress opening.mp4 under 200 MiB before pushing
What the push check countsConfirming over-budget pushesEverything the macOS app does
Set push freeze windows in opening_hours syntax, such as Mo-Fr 09:00-18:00; We off. Rules for this repository, the team and every repository on your machine all apply at once, and a push that falls inside a window stops before anything uploads. For an urgent fix, yunbox freeze off --for 1h switches it off; the rules stay and come back on by themselves.
When the current repository is in a push freeze, the YunBox icon in the menu bar gets a dot. Open the panel to see whether you can push now, today's and the next 7 days' freeze windows, and each project's rules. Tick a preset to set one; the switch and timer at the top switch off every repository at once. The demo panel here works too: tick a preset or flip the switch.
yunbox freeze set "Mo-Fr 09:00-18:00"
yunbox freeze off --until 18:00
yunbox freeze check --jsonThe app's Storage panel has Copy Setup Prompt for AI: paste it into Claude Code, Codex or Cursor. Every YunBox command runs without prompts and has JSON output, so a coding assistant can check, connect and set freeze windows by itself. Saving your storage key is the one step left to you.
Freeze window syntax and examplesSet up with an AI coding assistant
Push freeze in effectgame · Pushing opens at 18:00
Mo-Fr 09:00-18:00 (This repository)
No global rulesPick a preset with + at the top right; it applies to every repository on this Mac
The repository only records which bucket and prefix the assets live in. Everyone has their own storage key, kept in their own computer's keychain.
Committed and shared with the team
.yunbox/config
[cos]
bucket = team-assets-1250000000
region = ap-shanghai
prefix = yunbox/team/game.gitattributes
*.psd filter=lfs diff=lfs merge=lfs -text
*.fbx filter=lfs diff=lfs merge=lfs -text
*.wav filter=lfs diff=lfs merge=lfs -textOnly where the assets live, never a key. Each project can have its own bucket, or several can share one bucket with a prefix each.
Only on your own computer
macOS Keychain (yunbox)
SecretId AKID••••••••••••••••
SecretKey ••••••••••••••••••••.git/config
[lfs]
standalonetransferagent = yunbox
locksverify = falseEveryone gets a sub-account that can only read and write this prefix. When someone leaves, yunbox subaccount delete revokes their key at once. On Linux and Windows the key lives in a file only you can read.
The app is for everyday checks and setup; the command line does the transfers, so every collaborator needs it. Use both side by side.
Pick a repository to see its push size, files over budget and storage status (S3-compatible storage such as R2, or Tencent Cloud COS). You can also save your keys and connect a bucket right from the window.
Download YunBox-macOS.zipbrew install git-lfs)From 0.1.5 on, the app is notarized by Apple and opens with a double-click. Earlier versions are not notarized: if the first launch says the developer cannot be verified, go to System Settings → Privacy & Security and click Open Anyway, or run this in Terminal:
xattr -dr com.apple.quarantine /Applications/YunBox.appWorks on macOS, Linux and Windows. Installing it gives you both yunbox and git-yunbox; git yunbox init and yunbox init are the same thing.
npm install -g yunbox