rclone Züs Integration
Overview
rclone_zus is a custom integration of the rclone command-line tool with the Züs decentralized cloud. It enables users to interact with Züs storage using familiar rclone commands like copy, move, sync, and ls
.
This backend implementation allows developers, DevOps teams, and cloud users to:
Use rclone’s powerful CLI and scripting capabilities with Züs
Perform efficient, server-side batch operations (copy, delete, move)
Use Züs as an S3-compatible remote via rclone without vendor lock-in

The Züs backend is now available via -type züs in your rclone.conf file and supports advanced Züs features including:
Sync & batch mode
uploadsServer-side copy & move
Native delete, purge, and stat support
Directory listings and recursive operations
Why Use rclone_zus?
Scripting Ready: Automate uploads/downloads via shell scripts
Dev & CI Friendly: Plug into CI/CD pipelines with secure Züs backend
Zero Lock-in: Maintain open architecture with CLI-driven usage
Use Blimp UI to manage and render files in a carousel view
Share both public and encrypted files or folders with anyone instantly
Seamlessly scale by managing multiple allocations via Blimp and organizing data into multiple data rooms
Fast Sync: Avoid redundant uploads with batch commit
Prerequisites
Blimp account: If you do not have one, navigate to blimp.software. Click Sign Up for Free and you'll receive a free 2GB allocation.
Operating Systems: Linux, macOS, Windows (recent versions supported)
Go Toolchain [Optional] : Go ≥1.20; only required if building from source
Install rclone_zus
This section guides you through cloning, building, and configuring rclone_zus with the Züs backend. There are two ways of installing the rclone_zus plugin: download a pre-built binary or build the binary.
Download Pre-Built Binary
Go to the releases page and download the pre-built binary for your OS.
Place rclone.exe in your desired directory
Run ./rclone in that directory. If it shows the help description, you're ready to start using rclone with Züs storage
💡 This is the preferred method for Windows users
Build the Binary
1. Clone the Repository
git clone https://github.com/0chain/rclone_zus.git
cd rclone_zus
2. Build the Rclone Binary
Use the provided Makefile to build the project:
make
This will compile the rclone binary into the project root (./rclone), including the Züs backend.
💡 Troubleshooting: If make fails (e.g., missing make command or incompatible system), you can build manually:
go build -o rclone ./rclone.go
Ensure you have Go ≥1.20 installed (suggested go 1.23.4)and your GOPATH properly configured.
This will build a local ./rclone binary with the Züs backend integrated.
Note: If you're modifying backend code (e.g. backend/zus/zus.go), you can recompile by running the go build command again.
3. (Optional) Install as Global Command rclone_zus
To use your custom Rclone binary without the ./ prefix, install it globally by copying it to a directory in your system's $PATH, such as /usr/local/bin:
sudo cp ./rclone /usr/local/bin/rclone_zus
After this, you can run it from anywhere as a normal command:
rclone_zus move TestZus:/source TestZus:/dest
Renaming it to rclone_zus helps avoid conflicts with the system-installed rclone, if present.
Retrieve Wallet Files for Config Directory
Before using rclone_zus
, you must have a wallet, allocation, and configuration files in place. There are two methods to retrieving these files: download wallet files via Blimp or CLI
Download Wallet via Blimp
The standard way to retrieve your Züs wallet is by downloading it through the Blimp user interface. This requires no command-line setup and ensures all required files are prepared for you.
Visit Blimp
Navigate to Manage Allocation
Select your allocation
Click the ellipsis (⋯) button
Choose “Download Wallet”
Enter your mnemonic or wallet password
You’ll receive a
.zip
file containing:wallet.json
– Your Züs wallet credentialsallocation.txt
– The Allocation IDconfig.yaml
– Züs network configuration (block worker, signature scheme, etc.)
Extract the ZIP and move all three files to your system’s default config directory:
Windows:
C:\Users\<your-username>\.zcn
Linux/macOS:
~/.zcn/
📝 If the
.zcn
folder does not exist, create it manually.
By default, rclone_zus
looks for your configuration files (wallet.json
, allocation.txt
, and optionally config.yaml
) in the .zcn
folder located at:
~/.zcn/
on Linux/macOSC:\Users\<YourName>\.zcn\
on Windows
However, if you want to avoid overwriting your default wallet files — for example, if you're working with multiple wallets, different environments (testnet vs mainnet), or shared systems — you can specify a custom configuration directory.
When running rclone config
, you will be prompted with:
Config Directory - directory to read config files (defaults to ~/.zcn)
(config_dir)
Here, you can enter the full path to a custom folder that contains:
wallet.json
— your wallet credentialsallocation.txt
— your allocation IDconfig.yaml
— your network settings (optional, but recommended)
This allows you to isolate configs per project, user, or use case.
For example:
(config_dir)> /home/yourname/zcn-wallets/clientA
Once saved, this remote will always use that folder to locate its wallet and allocation files, regardless of what’s in your global .zcn
directory.
Allocation Performance
For reliable performance:
Züs blobbers provide better stability and performance
CLI Method
Alternatively, you can create your wallet and allocation using the CLI.
Create a wallet and allocation via Züs CLI tools
Place the following files in your
~/.zcn
(or Windows equivalent):
wallet.json
{
"client_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"client_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"keys": [
{
"public_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"private_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
],
"mnemonics": "xxxx xxxx xxxx xxxx xxxx xxxx",
"version": "1.0",
"date_created": "2023-05-03T12:44:46+05:30",
"nonce": 0,
"is_split": false
}
config.yaml
block_worker: https://mainnet.zus.network/dns
signature_scheme: bls0chain
min_submit: 50
min_confirmation: 50
confirmation_chain_length: 3
allocation.txt
<your allocation ID>
Ensure the CLI-generated wallet matches the allocation you're trying to access. This method is more error-prone for beginners and should only be used if you're familiar with the Züs CLI ecosystem.
Setup Remote
Remote Configuration
Here is an example of how to make a zus
remote called myZus
.
First run
rclone config
This will guide you through an interactive setup process:
No remotes found, make a new one?
n) New remote
s) Set configuration password
q) Quit config
n/s/q> n
name> myZus
Type of storage to configure.
Enter a string value. Press Enter for the default ("").
Choose a number from below, or type in your own value
...
59 / Zus Decentralized Storage
\ "zus"
...
Storage> zus
Zus Allocation ID - allocation ID.
allocation_id>
Config Directory - directory to read config files (defaults to ~/.zcn; make sure to use the correct windows path for `C:\Users\Username\.zcn`).
config_dir>
Work Directory - directory to read/write files.
work_dir>
Encrypt - encrypt the data before uploading.
y) Yes
n) No (default)
y/n> n
Edit advanced config?
y) Yes
n) No (default)
y/n> n
Configuration complete.
Options:
- type: zus
- allocation_id: allocation_id
Keep this "myZus" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d> y
Make sure your rclone.conf file is created. Finding rclone.conf:
To locate your rclone configuration file (
rclone.conf
) via command line, use the commandrclone config file
Example rclone.conf :
[myZus]
type = zus
allocation_id = <allocation_id>
Once configured, you can start using the remote myZus
.
Run Key Commands for File Operations
This section will cover basic commands to manage your files and folders. For more options, check out the other rclone commands here.
List All Directories in Path
rclone lsd <remote name>:<absolute path>
Example to list all the files and directories inside the root directory of the remote "myZus"
rclone lsd myZus:/
Output example:
-1 2025-05-14 15:27:59 -1 Encrypted
-1 2025-07-12 17:25:15 -1 10MbFiles100
-1 2025-07-12 17:44:35 -1 10MbFiles100M
-1 2025-07-12 17:46:51 -1 project-zus
-1 2025-07-14 22:45:57 -1 10MbFiles50
Make a New Directory
rclone mkdir myZus:<path>/<new_directory_name>
Example: create new directory in the root (This example shows new directory name as "newDirectory")
rclone mkdir myZus:/newDirectory
List the contents of a directory
rclone ls myZus:/<directory_path>
File Operations
Copy from source to destination (Local to Remote, Remote to Remote, Remote to Local)
rclone copy <source_remote>:<source_path> <target_remote>:<target_path>
Move from source to destination (Local to Remote, Remote to Remote, Remote to Local)
rclone move <source_remote>:<source_path> <target_remote>:<target_path>
Sync from source to destination (Local to Remote, Remote to Remote, Remote to Local)
Makes source and destination identical, modifying destination only.
--interactive flag is optional. Allows users to review each change before committing
rclone sync --interactive <source_remote>:<source_path> <target_remote>:<target_path>
Copy/move/sync commands only work within the same remote (same allocation). You cannot copy/move/sync across two different allocations (even if they have different remotes).
Local to Züs Examples:
# Windows example - copying from local Windows path to Züs remote
rclone copy "C:\Users\<username>\OneDrive\Desktop\New folder" myZus:/testDirectory
# Linux/macOS example - copying from local Unix path to Züs remote
rclone copy /home/user/documents myZus:/backup
Züs to Local Examples:
# Windows example - copying from Züs remote to local Windows path
rclone copy myZus:/testDirectory "C:\Users\<username>\OneDrive\Desktop\New folder"
# Linux/macOS example - Copying from Züs remote to local directory
rclone copy myZus:/documents /home/user/downloads
Same Remote Operations (within the same allocation):
Using the same remote, you can copy/move files from one directory to another within the same allocation.
# Copying within the same Züs remote (source: myZus, target: myZus)
rclone copy myZus:/sourcefilesDir/ myZus:/destinationDir/
Cross-Remote Limitation: only works within the same remote/allocations. Does not work across different Züs allocations
Cross-Cloud Backup Examples (Google Drive ↔ Züs):
You can use rclone_zus
to copy or sync files between your Züs storage allocation and other cloud providers such as Google Drive, Dropbox, S3, etc.
Step 1: Create a Remote for the Other Cloud Provider
To connect to another cloud provider, you must first create a remote for that service using the rclone config
wizard.
Run:
rclone config
Follow the interactive prompts:
Choose n for a new remote
Name your remote (e.g., gdrive)
Select the desired provider from the list (e.g., Google Drive, Dropbox, S3, etc.)
Follow the provider-specific instructions, such as:
Logging in via OAuth (for Google Drive)
Providing access tokens or keys (for Dropbox, S3, etc.)
Save your remote
Once created, you can use that remote name in any command.
Refer to rclone's official documentation for full setup guides for each provider: https://rclone.org/docs/
Step 2: Run Copy/Move Commands
You can now run standard rclone commands to transfer data between Züs (myZus) and the cloud remote you just created (gdrive, for example).
Google Drive to Züs
# Google Drive to Züs backup (source: gdrive, target: myZus)
rclone copy gdrive:important-files myZus:/backup
Züs to Google Drive
# Züs to Google Drive backup (source: myZus, target: gdrive)
rclone copy myZus:/documents gdrive:zus-backup
You can also use rclone move
or rclone sync
for the same remotes:
rclone move gdrive:/myFiles myZus:/archive
rclone sync myZus:/photos gdrive:/mirror/photos
Sync Mode Configuration
Use sync mode in rclone_zus for bulk operations
use --transfers=number of operations | --transfers=50
with the commands.
Edit advanced config?
y) Yes
n) No (default)
y/n> y
Option sdk_log_level.
Log level for the SDK
Enter a signed integer. Press Enter for the default (0).
sdk_log_level> leave empty
Option batch_mode.
Upload file batching sync|async|off.
This sets the batch mode used by rclone.
This has 3 possible values
- off - no batching
- sync - batch uploads and check completion (default)
- async - batch upload and don't check completion
Rclone will close any outstanding batches when it exits which may make
a delay on quit.
Enter a value of type string. Press Enter for the default (sync).
batch_mode> leave empty
Option batch_size.
Max number of files in upload batch.
This sets the batch size of files to upload. It has to be less than 50.
By default this is 0 which means rclone will calculate the batch size
depending on the setting of batch_mode.
- batch_mode: async - default batch_size is 100
- batch_mode: sync - default batch_size is the same as --transfers
- batch_mode: off - not in use
Rclone will close any outstanding batches when it exits which may make
a delay on quit.
Setting this is a great idea if you are uploading lots of small files
as it will make them a lot quicker. You can use --transfers 32 to
maximise throughput.
Enter a signed integer. Press Enter for the default (0).
batch_size> 50
Option batch_timeout.
Max time to allow an idle upload batch before uploading.
If an upload batch is idle for more than this long then it will be
uploaded.
The default for this is 0 which means rclone will choose a sensible
default based on the batch_mode in use.
- batch_mode: async - default batch_timeout is 5s
- batch_mode: sync - default batch_timeout is 500ms
- batch_mode: off - not in use
Enter a duration s,m,h,d,w,M,y. Press Enter for the default (0s).
batch_timeout> leave empty
Option batch_commit_timeout.
Max time to wait for a batch to finish committing
Enter a duration s,m,h,d,w,M,y. Press Enter for the default (10m0s).
batch_commit_timeout> leave empty
Option description.
Description of the remote.
Enter a value. Press Enter to leave empty.
description> leave empty
Edit advanced config?
y) Yes
n) No (default)
y/n> n
Configuration complete.
Bulk Copy from source to destination (Local to Remote, Remote to Remote, Remote to Local)
rclone copy <remote name>:<source path> <remote name>:<destination path> --transfers=50
Bulk Move from source to destination (Local to Remote, Remote to Remote, Remote to Local)
rclone move <remote name>:<source path> <remote name>:<destination path> --transfers=50
Using rclone_zus with Vult (Optional)
If you're a Vult user, you can also use rclone_zus to interact with your Züs allocation by following similar steps:
Go to Profile & Wallet via the user icon in the top right corner.
Scroll down and click Download Wallet.
This will download a
.zip
file with:wallet.json
allocation.txt
config.yaml
Move these files to your
.zcn
directory (e.g.~/.zcn
on Linux/macOS orC:\Users\<YourName>\.zcn
on Windows).
🔄 You may switch between Vult and Blimp wallets by replacing these files.
Last updated