Mirage S3 is S3-compatible object storage in a single static Go binary. Append-only volumes, erasure coding and strong consistency — on hardware you already own.
$ docker run -d -p 9000:9000 -v data:/data \ mirages3/server:latest a3f9c1e07b4d… $ aws --endpoint-url http://localhost:9000 \ s3 mb s3://photos make_bucket: photos $ aws --endpoint-url http://localhost:9000 \ s3 cp ./trip.tar s3://photos/ upload: ./trip.tar to s3://photos/trip.tar 4.2 GiB · 1.31 GiB/s · RS 8+2 ✓ $
Most self-hosted stores write one file per object. At a few hundred million objects your inode tables, directory scans and fsck times explode. Mirage packs objects into large append-only volumes and keeps a compact index in memory.
Every PUT creates a file, a directory entry and metadata. Small objects waste whole blocks; listing a bucket walks the tree.
Objects stream into 32 GiB sealed volumes. Sequential writes, zero fragmentation, background compaction reclaims deleted space.
No sidecars, no metadata database to babysit. Start a single node on a laptop and grow it into a multi-rack cluster without changing a line of client code.
Multipart upload, presigned URLs, SigV4, CORS, lifecycle rules. Works with aws-cli, boto3, rclone, restic and the Go/JS/Java SDKs.
Reed–Solomon and LRC profiles per bucket. Lose whole disks or nodes and keep serving reads at full speed.
FastCDC chunking with BLAKE3 fingerprints. Backups and container layers shrink 3–10× without client changes.
Query CSV, JSON and Parquet in place. Push filters down to the storage node instead of pulling terabytes over the wire.
Metadata replicated with Raft, data placed by consistent hashing. Add nodes online; rebalancing is throttled and resumable.
Continuous background scrubbing verifies every shard checksum and rebuilds bit-rot or missing data automatically.
Full object versioning with delete markers and noncurrent-version expiry. Roll back an overwritten file in one call.
Governance and compliance retention, legal holds. Ransomware-proof backups that even root cannot delete early.
Users, groups, access keys and AWS-style JSON bucket policies. OIDC and LDAP single sign-on for the console.
Prometheus metrics, OpenTelemetry traces and structured audit logs out of the box. Grafana dashboards included.
Write-ahead journal with fsync batching. Kill -9 the process mid-upload — no torn objects, no recovery scripts.
Automatic ACME certificates, TLS 1.3, HTTP/2 multiplexing and SSE-S3 / SSE-KMS encryption at rest.
Replication stores every byte three times. Erasure coding splits objects into data and parity shards so you survive the same failures for a fraction of the raw capacity.
Writes land in the journal on a quorum of nodes and are acknowledged immediately — p99 PUT latency stays flat under load.
Sealed volumes are striped into k data + m parity shards with SIMD-accelerated Reed–Solomon (AVX2, AVX-512, NEON).
Every shard carries a checksum. Scrubbers re-read and repair silently, and placement respects disk, node and rack failure domains.
Each layer does one job and can be reasoned about on its own. Cluster mode is optional — a single node runs the exact same code path.
SigV4 signature checked, bucket policy evaluated — no disk I/O yet.
Body streamed in 1 MiB chunks while computing BLAKE3 and Content-MD5.
Chunks appended to the active volume journal on ⌈n/2⌉+1 nodes with batched fsync.
Key → (volume, offset, length, etag) committed via Raft. The object is now readable everywhere.
When the volume fills, it is sealed and erasure-coded across failure domains in the background.
Everything a single team needs is free and stays free. Enterprise adds what you need when storage becomes someone's full-time job.
Pick your path. Every option starts the same binary with the same defaults.
# S3 API on :9000, web console on :9001 docker run -d --name mirage \ -p 9000:9000 -p 9001:9001 \ -e MIRAGE_ROOT_USER=admin \ -e MIRAGE_ROOT_PASSWORD=change-me-please \ -v mirage-data:/data \ mirages3/server:latest server /data --console :9001 # create a bucket with any S3 client aws --endpoint-url http://localhost:9000 s3 mb s3://backups
# run on each node — peers discover each other via the seed list mirage server /mnt/disk{1...4} \ --cluster \ --node-id "$(hostname)" \ --peers node1:9100,node2:9100,node3:9100 \ --ec-profile rs:4+2 # check health from any node mirage admin cluster status
helm repo add mirage https://charts.mirage-s3.dev helm install storage mirage/mirage-s3 \ --set replicas=4 \ --set persistence.size=2Ti \ --set erasure.profile=rs:4+2 \ --set console.ingress.enabled=true
# requires Go 1.23+
git clone https://github.com/mirage-s3/mirage.git
cd mirage && make build
./bin/mirage server ./dataDefault credentials are printed on first start if MIRAGE_ROOT_PASSWORD is not set. Change them before exposing the port.
Yes. The storage engine has been running in production since 2023, is covered by Jepsen-style fault-injection tests on every release, and follows semantic versioning — on-disk formats never change in a minor release.
Point mirage mirror (or rclone) at the source bucket. Objects, metadata, tags and versions are copied in parallel and the job can be resumed at any time. Clients only need a new endpoint URL.
Glacier storage classes, S3 Object Lambda and bucket analytics. Everything else your SDK calls in day-to-day use is implemented and tested against the official AWS SDK test suites.
Anything — run it commercially, embed it in a product, fork it. Enterprise features live in a separate module under a commercial license and are never removed from Community after release.
aws-cli, s3cmd, rclone, restic, Velero, Terraform, Loki, Thanos, ClickHouse, Spark, Trino and any library built on the AWS SDKs.
A Raspberry Pi will run a single node. For production we recommend 4+ nodes with 8 cores, 32 GB RAM and JBOD disks each — no RAID controller needed, erasure coding handles redundancy.
One binary, one command, and every S3 tool you already use just works.