# 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

<figure><img src="/files/raaUS1uGhnjGmBWQ7Btz" alt="" width="563"><figcaption></figcaption></figure>

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` uploads
* Server-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](https://blimp.network) 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

{% embed url="<https://youtu.be/AJ-zgmhSgGE>" %}

## **Prerequisites**

* **Blimp account**: If you do not have one, navigate to [blimp.software](https://blimp.software). Click **Sign Up for Free** and you'll receive a free 2GB allocation.&#x20;
* **Operating Systems**: Linux, macOS, Windows (recent versions supported) &#x20;
* **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

1. Go to the [releases page](https://github.com/0chain/rclone_zus/releases/tag/v1.0.4) and download the pre-built binary for your OS.
2. Place rclone.exe in your desired directory
3. 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&#x20;

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.

1. Visit [**Blimp**](https://blimp.zus.network)
2. Navigate to **Manage Allocation**
3. Select your allocation
4. Click the **ellipsis (⋯)** button
5. Choose **“Download Wallet”**
6. Enter your **mnemonic** or **wallet password**
7. You’ll receive a `.zip` file containing:
   * `wallet.json` – Your Züs wallet credentials
   * `allocation.txt` – The Allocation ID
   * `config.yaml` – Züs network configuration (block worker, signature scheme, etc.)

{% hint style="info" %}
Make sure your `wallet.json` file contains `"is_split": false`. This is required for compatibility with `rclone_zus`.
{% endhint %}

8. 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/macOS
* `C:\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 credentials
* `allocation.txt` — your allocation ID
* `config.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&#x20;

Alternatively, you can create your wallet and allocation using the CLI.

1. Create a wallet and allocation via [Züs CLI tools](https://docs.zus.network/zus-docs/clis?utm_source=chatgpt.com)
2. Place the following files in your `~/.zcn` (or Windows equivalent):

* `wallet.json`

```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
}
```

{% hint style="info" %}
Make sure your `wallet.json` file contains `"is_split": false`. This is required for compatibility with `rclone_zus`.
{% endhint %}

* `config.yaml`

```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>
```

{% hint style="warning" %}
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.
{% endhint %}

## 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:

```bash
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 command `rclone config file`

Example rclone.conf :

```ini
[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](https://rclone.org/commands/).&#x20;

### 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

<pre><code><strong>rclone sync --interactive &#x3C;source_remote>:&#x3C;source_path> &#x3C;target_remote>:&#x3C;target_path> 
</strong></code></pre>

{% hint style="warning" %}
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).
{% endhint %}

**Local to Züs Examples:**

```bash
# 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:**

```bash
# 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.

```bash
# Copying within the same Züs remote (source: myZus, target: myZus)
rclone copy myZus:/sourcefilesDir/ myZus:/destinationDir/
```

{% hint style="warning" %}
**Cross-Remote Limitation**: only works within the same remote/allocations. Does not work across different Züs allocations
{% endhint %}

## **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.

```bash
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:

{% embed url="<https://www.youtube.com/watch?feature=youtu.be&v=aBw3_-Bwiqw>" %}

1. Go to **Profile & Wallet** via the user icon in the top right corner.
2. Scroll down and click **Download Wallet**.
3. This will download a `.zip` file with:
   * `wallet.json`
   * `allocation.txt`
   * `config.yaml`
4. Move these files to your `.zcn` directory (e.g. `~/.zcn` on Linux/macOS or `C:\Users\<YourName>\.zcn` on Windows).

{% hint style="info" %}
Make sure your `wallet.json` file contains `"is_split": false`. This is required for compatibility with `rclone_zus`.
{% endhint %}

🔄 You may switch between Vult and Blimp wallets by replacing these files.

{% hint style="info" %}
If using multiple wallets, consider using `rclone config` to point to a **custom config directory** instead of overwriting `.zcn`.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zus.network/zus-docs/clis/guides-and-workflows/rclone-zus-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.