{"id":41256648,"url":"https://github.com/0chain/zs3server","last_synced_at":"2026-01-23T01:52:00.891Z","repository":{"id":42437499,"uuid":"434079960","full_name":"0chain/zs3server","owner":"0chain","description":"High Performance S3-compatible Object Storage","archived":false,"fork":false,"pushed_at":"2025-12-27T09:14:41.000Z","size":120871,"stargazers_count":6,"open_issues_count":37,"forks_count":6,"subscribers_count":3,"default_branch":"staging","last_synced_at":"2025-12-28T12:54:58.700Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://min.io/download","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"minio/minio","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0chain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"code_of_conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-12-02T04:22:05.000Z","updated_at":"2025-09-15T10:10:35.000Z","dependencies_parsed_at":"2025-07-01T19:39:41.314Z","dependency_job_id":null,"html_url":"https://github.com/0chain/zs3server","commit_stats":null,"previous_names":[],"tags_count":305,"template":false,"template_full_name":null,"purl":"pkg:github/0chain/zs3server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0chain%2Fzs3server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0chain%2Fzs3server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0chain%2Fzs3server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0chain%2Fzs3server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0chain","download_url":"https://codeload.github.com/0chain/zs3server/tar.gz/refs/heads/staging","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0chain%2Fzs3server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28677714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T01:00:35.747Z","status":"ssl_error","status_checked_at":"2026-01-23T01:00:19.529Z","response_time":144,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-23T01:52:00.699Z","updated_at":"2026-01-23T01:52:00.869Z","avatar_url":"https://github.com/0chain.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zs3server - a no-code decentralized storage server\n\nzs3server provides a no-code s3-compatible decentralized storage server on Züs allocation using a minio-gateway interface.\n\n- [Züs Overview](#züs-overview)\n- [Architecture](#architecture)\n- [Building zs3 server](#building-zs3-server)\n- [Running zs3 server](#running-zs3-server)\n- [Test MiniO client](#test-minio-client)\n- [Configure Minio client](#configure-minio-client)\n\n## Züs Overview\n\n[Züs](https://zus.network/) is a leading privacy and secure AI data platform that provides users full ownership and control of their data, with powerful AI chat and agents on Vult.network to accelerate productivity. It is also ideal for on-prem, high speed S3 storage as well as backup and disaster recovery to prevent outage, breach, and ransomware issues. \n\nIt has an unparalleled data integrity layer on the blockchain and a zero knowledge network, with data and key distributed so that its almost impossible to breach. Another standout feature is that it allows users to share encrypted data easily, even on a public link.\n\nUsers can also add their own servers to the network to operate in a hybrid cloud architecture. Such flexibility allows the user to improve their regulatory, content distribution, and security requirements with a true multi-cloud architecture. Users can also construct a private cloud with all of their own servers rented across the globe to have a better content distribution, highly available network, higher performance, and lower cost.\n\n[The QoS protocol](https://medium.com/0chain/qos-protocol-weekly-debrief-april-12-2023-44524924381f) is time-based where the blockchain challenges a provider on a file that the provider must respond within a certain time based on its size to pass. This forces the provider to have a good server and data center performance to earn rewards and income.\n\nThe [privacy protocol](https://zus.network/build) from Züs is unique where a user can easily share their encrypted data with their business partners, friends, and family through a proxy key sharing protocol, where the key is given to the providers, and they re-encrypt the data using the proxy key so that only the recipient can decrypt it with their private key.\n\nZüs has ecosystem apps to encourage traditional storage consumption such as [Blimp](https://blimp.software/), a S3 server and cloud migration platform, and [Vult](https://vult.network/), a personal cloud app to store encrypted data and share privately with friends and family.\n\nOther apps are [Bolt](https://bolt.holdings/), a wallet that is very secure with air-gapped 2FA split-key protocol to prevent hacks from compromising your digital assets, and it enables you to stake and earn from the storage providers; [Atlus](https://atlus.cloud/), a blockchain explorer and [Chimney](https://demo.chimney.software/), which allows anyone to join the network and earn using their server or by just renting one, with no prior knowledge required.\n\nWe’ve built the first **S3-compatible storage platform** that is both **ACID-compliant** and runs on a **zero-knowledge network** — eliminating the need for additional services like AWS Athena or GuardDuty to secure or query your data.\n  - **5x better performance** – Real-world tests (see benchmark from s3compare.io) showed up to 5x gains versus AWS.\n  - **2x lower costs** – Thanks to zero egress and zero API fees, you save more as your usage scales.\n  - **2x lower carbon footprint** – Our erasure-coded architecture minimizes redundancy-related overhead (see below for architectural breakdown).\n  - **Bulletproof security** – Split-key security, zero-knowledge design, and erasure coding ensure unmatched internal breach resistance.\n  - **No vendor lock-in** – Easily add, remove, or swap providers with no disruption or central dependency.\n\n  One of our enterprise customers benchmarked Züs against AWS using [s3compare.io](https://s3compare.io) and saw **5x performance improvements** across common S3 operations — validating our edge in real-time workloads and data transfer scenarios.\n  \n  We also fill security and vendor neutrality gaps that MinIO and AWS have in their solution. Check the table below for comparison.\n  \n  Beyond backup and datalake storage, our platform is ideal for storing AI data, where integrity and verifiability matter such as for MCP workflows.\n\n  ### Core Features – Züs vs AWS S3 vs MinIO\n\n| **Feature**                             | **AWS S3**                                                                 | **MinIO**                                                               | **Züs**                                                                                   |\n|----------------------------------------|---------------------------------------------------------------------------|------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|\n| **Managed Infrastructure**             | Fully managed with strong global uptime                                  | Self-hosted; requires manual setup and scaling                        | Fully managed decentralized infrastructure with flexible scaling                          |\n| **Split-key Internal Breach Security** | Not available; single-party access control                                | Not available                                                          | Built-in split-key security prevents internal breaches by decentralizing key control      |\n| **Zero Egress Fees**                   | Charges apply for all outbound data                                      | No egress fees                                                         | No egress fees on outbound traffic across providers                                       |\n| **Zero API Fees**                      | Charges per API call                                                      | Free API access                                                        | Free unlimited API requests; ideal for high-frequency apps                                |\n| **Encrypted Data Sharing**             | Requires external tools or complex configuration                         | Not supported natively                                                 | Native proxy re-encryption enables secure, private sharing of encrypted files             |\n| **Zero Knowledge Network**            | Not supported                                                             | Not supported                                                          | Zero-knowledge architecture ensures providers can't access file contents or user identity |\n| **ACID Compliant (Data Integrity)**    | Eventual consistency; not ACID compliant                                 | No built-in ACID guarantees                                            | Fully ACID compliant to ensure consistent reads/writes and verifiable storage behavior    |\n| **Add/Swap Infrastructure (No Lock-in)**| Vendor lock-in with no real-time provider switching                      | Tied to fixed infrastructure                                           | Add, remove, or swap storage providers dynamically with no lock-in                        |\n\n\n## Architecture\n\n![Main-architecture](./assets/main-struture.png)\n\nThere are three main components that will be installed in the customer server.\n\n1. ZS3Server is the main component that will communicate directly with Züs storage.\n\n2. [LogSearch](/logsearchapi/README.md) API is the log component that will store the audit log from the S3 server and it will be consumed using ZS3 API\n\n3. [MinioClient](/client-api/README.md) is the component that will communicate directly to the zs3server and it is protected using access and secret key.\n\n## Building zs3-server\n\nPrerequisites to run MinIO ZCN gateway:\n\n- [A wallet.json created using zwalletcli](https://github.com/0chain/zwalletcli#creating-and-restoring-wallets)\n- [Config.yaml](https://github.com/0chain/zboxcli/blob/staging/network/config.yaml)\n- [An allocation.txt created using zboxcli](https://github.com/0chain/zboxcli/tree/staging#create-new-allocation).\n- [A zs3server.json option file to configure encryption and compress options](https://github.com/0chain/zs3server/tree/staging/zs3server.json)\n\n```\ngit clone git@github.com:0chain/zs3server.git\ncd zs3server\ngo mod tidy\ngo build .\nexport MINIO_ROOT_USER=someminiouser\nexport MINIO_ROOT_PASSWORD=someminiopassword\n./minio gateway zcn --configDir /path/to/config/dir\nNote: allocation and configDir both are optional. By default configDir takes ~/.zcn as configDir and if allocation is not provided in command then it will look for allocation.txt file in configDir directory.\n```\n\n\u003e If you want to debug on local you might want to build with `-gcflags=\"all=-N -l\"` flag to view all the objects during debugging.\n\n## Running zs3-server\n\n1. To build and run the minio server component you need to install [docker](https://www.docker.com/products/docker-desktop/).\n\n2. Run the docker-compose command inside the zs3server directory./\n\n```\ndocker-compose -f environment/docker-compose.yaml up -d\n```\n\n3. Make sure allocation.txt file exist in the default folder `~/.zcn`\n\n4. Now you can interact with the clint API follow this [doc](/client-api/README.md)\n\n5. You can also interact with the logsearch API by following this [doc](/logsearchapi/README.md)\n\n## Test using AWS Client `aws`\n\n### Installation\n\nInstall from here: https://aws.amazon.com/cli/\n\n### Configuration\n\nFetch the access key and secret from your deployed zs3server. To configure `aws cli`, type `aws configure` and\nspecify the zs3server key information like below:\n\n```\naws configure\nAWS Access Key ID [None]: miniouser\nAWS Secret Access Key [None]: miniopassword\nDefault region name [None]: us-east-1\nDefault output format [None]: ENTER\n```\n\nAdditionally enable AWS Signature Version ‘4’ for zs3server.\n\n`aws configure set default.s3.signature_version s3v4`\n\n### Examples\n\n#### To list your buckets\n\n```\naws --endpoint-url https://localhost:9000 s3 ls\n2016-03-27 02:06:30 deebucket\n2016-03-28 21:53:49 guestbucket\n2016-03-29 13:34:34 mbtest\n2016-03-26 22:01:36 mybucket\n2016-03-26 15:37:02 testbucket\n```\n\n#### To list contents inside bucket\n\n```\naws --endpoint-url https://localhost:9000 s3 ls s3://mybucket\n2016-03-30 00:26:53      69297 argparse-1.2.1.tar.gz\n2016-03-30 00:35:37      67250 simplejson-3.3.0.tar.gz\n```\n\n#### To make a bucket\n\n```\naws --endpoint-url https://localhost:9000 s3 mb s3://mybucket\nmake_bucket: s3://mybucket/\n```\n\n#### To add an object to a bucket\n\n```\naws --endpoint-url https://localhost:9000 s3 cp simplejson-3.3.0.tar.gz s3://mybucket\nupload: ./simplejson-3.3.0.tar.gz to s3://mybucket/simplejson-3.3.0.tar.gz\n```\n\n#### To delete an object from a bucket\n\n```\naws --endpoint-url https://localhost:9000 s3 rm s3://mybucket/argparse-1.2.1.tar.gz\ndelete: s3://mybucket/argparse-1.2.1.tar.gz\n```\n\n#### To remove a bucket\n\n```\naws --endpoint-url https://localhost:9000 s3 rb s3://mybucket\nremove_bucket: s3://mybucket/\n```\n\n## Test using MinIO Client `mc`\n\n`mc` provides a modern alternative to UNIX commands such as ls, cat, cp, mirror, diff etc. It supports filesystems\nand Amazon S3 compatible cloud storage services.\n\n### Installation\n\nInstall from here for your os: https://min.io/docs/minio/macos/index.html\n\n## Configure MinIO Client\n\n```\nmc alias set zcn http://localhost:9000 miniouser miniopassword --api S3v2\n```\n\n### Examples\n\n#### To list your buckets\n\n```\nmc ls zcn/\n2016-03-27 02:06:30 deebucket\n2016-03-28 21:53:49 guestbucket\n2016-03-29 13:34:34 mbtest\n2016-03-26 22:01:36 mybucket\n2016-03-26 15:37:02 testbucket\n```\n\n#### To list contents inside bucket\n\n```\nmc ls zcn/mybucket\n2016-03-30 00:26:53      69297 argparse-1.2.1.tar.gz\n2016-03-30 00:35:37      67250 simplejson-3.3.0.tar.gz\n```\n\n#### To make a bucket\n\n```\nmc mb zcn/mybucket\nmake_bucket: zcn/mybucket\n```\n\n#### To add an object to a bucket\n\n```\nmc cp simplejson-3.3.0.tar.gz zcn/mybucket\nupload: ./simplejson-3.3.0.tar.gz to zcn/mybucket/simplejson-3.3.0.tar.gz\n```\n\n#### To delete an object from a bucket\n\n```\nmc rm zcn/mybucket/argparse-1.2.1.tar.gz\ndelete: zcn/mybucket/argparse-1.2.1.tar.gz\n```\n\n#### To remove a bucket\n\n```\nmc rb zcn/mybucket\nremove_bucket: zcn/mybucket/\n```\n\nCheck `mc --help` for the exhaustive list of cmds available.\n\n## Test using Postman Using REST APIs\n\n- Add the following authorization settings\n  ![](./assets/postman-auth.png 'Authorization settings')\n- The `AccessKey` would be the MINIO_ROOT_USER which you set earlier during zs3server deployment and `SecretKey` would be the MINIO_ROOT_PASSWORD.\n- If you do not want to share the MINIO_ROOT_USER and MINIO_ROOT_PASSWORD, you can also create a user from minio console and share their access key and secret instead.\n- Use the REST APIs to interact with the server.\n- Postman collection for the same is provided below:\n  [Postman Collection](./assets/Zs3ServerCollection.postman_collection.json)\n\n## Replication\n\nTo setup replication, you need to have two zs3servers. For running two zs3servers on the same machine, you will need to copy the contents of .zcn folder to .zcn2 folder and change allocation.txt and zs3server.json accordingly. For changes in docker-compose.yaml, you can refer to the following example:\n[docker-compose.yaml](https://github.com/0chain/zs3server/tree/staging/environment/docker-compose-dev2.yaml)\n\n- Configure both the zs3servers using minio client.\n\n```\nmc alias set primary http://\u003cHOST_IP\u003e:9000 miniouser miniopassword --api S3v2\nmc alias set secondary http://\u003cHOST_IP\u003e:9002 miniouser miniopassword --api S3v2\n```\n\n- Set up replication using the following command, for more details refer to [mc mirror](https://min.io/docs/minio/linux/reference/minio-mc/mc-mirror.html) command.\n\n```\n./mc mirror primary/\u003cBUCKET_PREFIX\u003e/ secondary/\u003cBUCKET_PREFIX\u003e/ --remove --watch\n```\n\n## Disaster Recovery\n\nDisaster recovery is process of replicating data from secondary to primary in case of primary failure. To set up disaster recovery, you need to have replication setup between primary and secondary zs3servers. In case of primary failure, you can use the following command to sync data from secondary to primary.\n\n```\n./mc mirror secondary/\u003cBUCKET_NAME\u003e/ primary/\u003cBUCKET_NAME/ --summary\n```\n\n## Encryption and Compression\n\nTo enable encryption and compression, you need to provide the encryption and compression options in the zs3server.json file under .zcn folder. For example:\n\n```\n{\n  \"encrypt\": true,\n  \"compress\": true,\n}\n```\n\n## Batch Upload settings\n\nThe server will batch upload requests for objects which are uploaded using put api and has a defined content length. Max batch size refers to number of objects max objects to upload in one batch, this number should be similar to concurrency or thread set in client or expected number of requests per seconds, batch wait time will wait for this much amount of time before finalizing a batch and uploading it, number of batch workers will determine how many batches can we upload concurrently. For example:\n\n```\n{\n  \"max_batch_size\": 25, // set same as concurrency set via rclone or client\n  \"batch_wait_time\": 500, // batch wait time is set in milliseconds, its the time the processor will wait for more operations if the batch size is not reached\n  \"batch_workers\": 5, // number of workers, can be increased based on the number of requests, total operations which can be processed concurrently will be max_batch_size * batch_workers\n  \"max_concurrent_request\": 100 // max concurrent requests initiated by the server to blobbers\n}\n```\n\n## Upload and Download workers\n\nThe server will upload and download objects concurrently based on the number of workers set in the configuration file. The number of workers can be set in the zs3server.json file under .zcn folder,by default upload workers are set to 4 and download workers to 6. For example:\n\n```\n{\n  \"upload_workers\": 4,\n  \"download_workers\": 6\n}\n```\n\n## FUSE-based file system\n\nThe server can be mounted as a file system using [s3fuse](https://github.com/s3fs-fuse/s3fs-fuse). The server can be mounted using the following commands:\n\nUse the following command to create a password file:\n\n```\necho ACCESS_KEY_ID:SECRET_ACCESS_KEY \u003e ${HOME}/.passwd-s3fs\nchmod 600 ${HOME}/.passwd-s3fs\n```\n\nMount the server using the following command:\n\n```\ns3fs mybucket /path/to/mountpoint -o passwd_file=${HOME}/.passwd-s3fs -o url=https://url.to.s3/ -o use_path_request_style,allow_other,umask=000,complement_stat\n```\n\nIf you are using compression, we recommeng using our minio client\n[Minio Client](https://github.com/0chain/mc)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0chain%2Fzs3server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0chain%2Fzs3server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0chain%2Fzs3server/lists"}