English
Cloudflare R2 and S3-compatible storage
Besides Tencent Cloud COS, YunBox can connect git-lfs directly to S3-compatible object storage: Cloudflare R2 (which charges no egress fees, a good fit for teams whose assets get pulled a lot), AWS S3, MinIO, and other services that support the S3 object API with Signature Version 4. Just as with COS, there is no server in between: git-yunbox lfs-agent on each person's computer signs requests with that person's own key and uploads and downloads directly.
git push / clone ──▶ git-lfs ──▶ git-yunbox lfs-agent ──▶ R2 / S3 / MinIOThe command line is installed the same way as for COS; see Quick start.
R2 tokens can be limited to buckets, not to prefixes
An R2 API token can be scoped to one or a few buckets, but there is no option to scope it to a folder (prefix) inside a bucket. A token that can access a bucket can read and write every prefix in it.
So with R2, create a separate bucket for each project and scope your collaborators' tokens to that bucket. Don't share one bucket between projects with a prefix each, as you might with COS: on R2, any project's token could read and write every other project's assets.
Admins: create a bucket and tokens (R2 example)
- In the Cloudflare dashboard, open R2 Object Storage and create a bucket, such as
game-assets. Keep it private: don't turn on public access (an r2.dev subdomain or a custom domain), or anyone who knows an object key could download assets without a token. - Note the Account ID (32 hexadecimal characters) on the right of the R2 overview page.
- Under Manage R2 API Tokens, create a token:
- For permissions, choose Object Read & Write; for people who only need to pull, choose Object Read only.
- Under Specify bucket(s), pick only this project's bucket.
- Once created, the page shows the Access Key ID and Secret Access Key. The Secret Access Key is shown only once, so hand it to its owner right away through a secure channel (a shared item in a password manager, for example).
- Give each collaborator their own token. When someone leaves, delete their token in the dashboard; nobody else is affected.
YunBox doesn't call Cloudflare's management APIs: yunbox buckets, yunbox policy and yunbox subaccount support Tencent Cloud COS only, and in an S3 repository they tell you to use the dashboard instead.
Admins: connect the repository to R2
bash
yunbox login --provider s3 # enter the Access Key ID and Secret Access Key
git yunbox init --preset r2 --account-id <account-id> --bucket game-assets
git add .gitattributes .yunbox/config
git commit -m "chore: store LFS assets in R2 with YunBox"
git pushRunning git yunbox init --provider s3 without options asks for each value in turn. Before changing the repository, init uses your key to write and read a test object at <prefix>/_yunbox/probe; if that fails, no files are touched.
.yunbox/config is committed so the whole team shares it. It contains no keys:
ini
[storage]
provider = s3
[s3]
endpoint = https://<account-id>.r2.cloudflarestorage.com
bucket = game-assets
region = auto
prefix = yunbox/team/game
addressingStyle = pathObject keys are <prefix>/<first two characters of the oid>/<characters 3–4 of the oid>/<oid>, the same as on COS. With one bucket per project, you can keep the default prefix or use --prefix '' to store objects at the bucket root.
Other services
| Service | Command | Notes |
|---|---|---|
| Cloudflare R2 | --preset r2 --account-id <account-id> | Endpoint https://<account-id>.r2.cloudflarestorage.com, region auto, path-style |
| AWS S3 | --preset aws --region <region> | Endpoint https://s3.<region>.amazonaws.com, virtual-hosted style (<bucket>.s3.<region>.amazonaws.com). Use an IAM policy to limit access to s3:PutObject and s3:GetObject on arn:aws:s3:::<bucket>/<prefix>/* |
| MinIO | --preset minio --endpoint https://minio.example.com | Path-style; region defaults to us-east-1 (pass --region if your server uses another) |
| Others | --endpoint <url> --region <region> | Path-style by default; --addressing virtual switches to virtual-hosted style |
The endpoint must use https; only local addresses (localhost, 127.0.0.1) may use http. Bucket names containing "." only work with path-style addressing.
Joining as a collaborator
Once you have an Access Key ID and Secret Access Key:
bash
npm install -g yunbox
git yunbox clone <repository-url> # the first time, it tells you there is no key yet
cd <repository-folder>
yunbox login # inside the repository it saves an S3 key and checks it against this bucket
git yunbox init && git lfs pullYou can also run yunbox login --provider s3 from any folder first (there is no bucket to check against then, so check with yunbox doctor after connecting), and then git yunbox clone <repository-url>.
- The Secret Access Key is hidden as you type and can't be passed as a command-line argument.
- On macOS it's stored in your login keychain under "yunbox / s3"; on Linux and Windows in
~/.config/yunbox/credentials-s3.json(%APPDATA%\yunboxon Windows), readable only by you. COS keys are stored separately, so neither overwrites the other. - For CI and similar setups, use the environment variables
YUNBOX_S3_ACCESS_KEY_IDandYUNBOX_S3_SECRET_ACCESS_KEY(plusYUNBOX_S3_SESSION_TOKENfor temporary credentials). YunBox does not read general-purpose variables such asAWS_ACCESS_KEY_ID, so your AWS identity is never sent to another service such as R2. - A computer holds one set of S3 keys at a time. If you work on several R2 projects, ask your admin for one token scoped to all of their buckets.
yunbox logout --provider s3deletes the S3 key; without--provider, both the COS and S3 keys are deleted.
Safety and reliability
- Uploads send
If-None-Match: *, so an existing object is never overwritten. Each object is also looked up before uploading, and ones that already exist are skipped, so pushing again doesn't upload again. If the service doesn't support that header (it answers 501), YunBox falls back to looking up first and then uploading. - The content hash signed with each upload is the object ID (SHA-256), so the storage service rejects an upload whose content doesn't match. Downloads are hashed with SHA-256 as they're written, and a file whose size or hash doesn't match is discarded instead of being handed to git-lfs.
- Logs and error messages never include keys, signatures or signed URLs.
- Without a server there are no file locks, so make sure only one person edits a given asset at a time.
FAQ
Can I add other storage through a plugin?
No. YunBox only has built-in storage, Tencent Cloud COS and S3-compatible storage, and never loads third-party plugins. A storage implementation needs your key to sign requests, and it runs on every push and pull. A plugin would run in the same process as YunBox and could read every key in your keychain, and a tampered plugin would end up in every push by everyone on the team. Guarantees such as "never overwrite an existing object", "verify SHA-256 on download" and "keep keys out of logs" also only hold in the shared built-in code.
My storage isn't in the table above
Try it as S3-compatible storage first:
bash
git yunbox init --provider s3 --endpoint <service-url> --region <region> --bucket <bucket>
yunbox doctorinit tests reading and writing before it changes the repository, so if the service isn't compatible it fails without touching any files. Services outside the table that claim S3 compatibility haven't been tested by us; if one works for you, please let us know in an issue. If your storage really isn't S3-compatible and you need it, please open an issue, or contribute a built-in implementation following the storage provider guide (in Chinese).
When something goes wrong
bash
yunbox doctorIn an S3 repository the checks are 「S3 位置」 (S3 location), 「S3 密钥」 (S3 key) and 「S3 权限」 (S3 permissions); every failed check comes with the command that fixes it. Common cases:
- SignatureDoesNotMatch: the Secret Access Key is wrong, or
s3.regionis wrong (it'sautofor R2). - InvalidAccessKeyId: the Access Key ID doesn't exist, or the token has been deleted.
- Can pull but not push: the token is read-only. If you only need to pull, use
yunbox doctor --read-only. - NoSuchBucket:
s3.bucketors3.endpointis wrong.