ashayas/icloud-s3

icloud-s3 is a Rust server that implements enough of the S3 XML REST API for tools like the AWS CLI, boto3, rclone and s5cmd to read and write buckets and objects. Instead of storing bytes in a normal object store, it packs each object into the RGB pixels of lossless PNG images inside iCloud Shared Albums, exploiting Apple's policy that shared-album media does not count against iCloud storage. The author labels the project a joke, not affiliated with Apple or AWS, and not for production or sensitive data.

How the mapping works

An S3 bucket maps to a Shared Album, an object to a 24-bit RGB PNG no larger than 2048×2048 px, and a large object to a burst of numbered frames reassembled by chunk_index. Metadata and a 64-pixel HUD banner are burned into the top of each carrier image so the file remains identifiable in Photos.app. Integrity uses per-frame CRC32 over the pixel stream plus whole-object SHA-256 and MD5. On cold start the server rebuilds state by scanning and decoding the PNG files.

Ways to run it

• Local only: icloud-s3 serve --dry-run uses an in-memory album with no iCloud connection; pairing it with --album-dir persists each bucket as a folder of PNG frames on disk.
• Into Photos.app: --sync-photos-app additionally imports each written frame into macOS Photos.app via AppleScript, so this path requires macOS.
• No server at all: icloud-s3 encode and decode convert a single file to and from a carrier PNG from the CLI.
• Inspection: any object can be fetched as a raw carrier PNG with ?format=png, and icloud-s3 bench shows a live terminal benchmark.

Supported operations cover bucket create/delete/head/list, object put/get/head/delete and batch delete, and list v2 with prefix, delimiter and max-keys. The author's 10-case evaluation reports all passing, including zero-byte objects, metadata preservation, out-of-order frame reassembly, single-bit corruption detection, overwrite compaction, and cold-boot reconstruction; an unmodified aws s3 roundtrip is included.

Limits that matter

Apple's published Shared Album limits cap an owner at 200 albums, 5,000 items per album, 1,000 uploads per hour and 10,000 per day, with a 2048-pixel long-edge limit. The author's headline capacity estimate of roughly 1,000,000 objects and 12 TB depends on those limits and on every carrier staying a lossless PNG. More importantly, the author warns that if Apple's server-side pipeline transcodes an asset to lossy JPEG/HEIC downstream, pixel bits change and decoding fails closed with ChecksumMismatch, so bit-exact local PNGs are the safe case. Throughput and latency figures are local album-dir measurements on Apple Silicon; the Cloudflare R2 comparison uses local files against a remote bucket, so the speedup mostly reflects local versus network access, not a durability claim. No license is declared in the supplied repository metadata, so check licensing terms before redistributing or building on the code.

HotRepo's take

On the 2026-10-31 new-repository board for Rust, the project had 113 total stars (rank #7); that is a single snapshot, not a daily growth measurement, and the samples do not establish any trend. Given the author's satire warning, treat this as an unusual demo or teaching tool for S3 protocol and pixel-encoding tricks rather than storage infrastructure.

Project source and documentation