Get Started

This section covers Zbox CLI concepts, repository configuration, and installation. Check out these videos for reference.


A wallet is required to hold the tokens. It comes with private and public keys including a secret mnemonic key.
An allocation is storage space on 0chain dStorage. It's a contract between the client and multiple blobbers for agreed read/write prices for the agreed duration.
It's distributed storage where all the data files are stored.

System requirements

To properly build components, you must have a Machine setup with the following requirements:
  • Windows, Linux, Mac OS (Linux with ubuntu 18.04 preferred)
  • 4 vCPU, 8 Gb Memory at minimum
  • 5 GB of space minimum for zbox build components and storage allocation
We will be building and describing Zbox CLI capabilities on Ubuntu Linux.
So If you want to build Zbox CLI on other platforms.
Follow this guide for Windows and other Platforms and move straight to the Creating a Storage Allocation


Installing and running the Zbox requires deployment-specific dependencies to be preinstalled‌

GoLang Binaries

Installation instructions for Go can be found here.


The build**-**essential package is required to build and make the Zbox application. It includes the necessary GCC/g++ compilers and other essential critical libraries and utilities.
Run apt update command to update the packages
sudo apt update
Get Build-essential package
sudo apt-get install build-essential


Git is required to retrieve and clone the Zbox repository. Install Git by using the command
sudo apt install git

Building Zbox

1.Clone the Zbox Repository using the command
git clone https://github.com/0chain/zboxcli.git
2.Navigate into zboxcli directory using
cd zboxcli
3.Use the make install command to compile the source code .
make install
This might take a minute. Here is a sample response of successful make install command:

Configure Zbox network

Configuration for the 0Chain network by default is stored in network/one.yaml file of the zbox github repo which we will copy to a new config.yaml file in our local system . The config.yaml file and all the other Zbox component information will be stored in a .zcn folder located in the home directory of the file system.
1.Make a new .zcn folder in the home Linux directory using
mkdir $HOME/.zcn
2. Copy the content from one.yaml to a new config.yaml file using
cp network/one.yaml $HOME/.zcn/config.yaml
3. To verify whether the config.yaml exists and network configuration is stored properly. Check the config.yaml details using the command
nano config.yaml
4. Open the config.yaml file located at $HOME/.zcn path of your system.
Zbox connects to the 0Chain network using the block_worker field. These network details are automatically fetched from the blockWorker's network API. Preferred Blobbers are also present which you can uncomment for using specified storage providers for handling your files.
5. Change the block_worker field for the desired network of the organization. In this case we will change it to 0chain beta network i.e beta.0chain.net. After changes it should look similar to the file below:

Starting Zbox

Start the Zbox by navigating back to the zboxcli directory using
cd zboxcli
and type
On a successful run you will see a help section:

Creating a Storage Allocation

The section assumes you have successfully build zbox. zbox provides a long list of components to use. Let's begin with the allocation of storage space on the 0Chain decentralized network.
For creating a storage allocation using Zbox. You need to have a wallet with tokens available for performing allocations.
1. Register a wallet on Zbox to be used both by the blockchain and blobbers. Use the following Zbox command
./zbox register
Successful Response:
By default, the wallet information will be stored in wallet.json located in the .zcn folder of the linux home directory.
2.Get the test tokens into your wallet using the zwallet CLI tool. If you have not installed zwallet CLI clone the repository and install using these commands
git clone https://github.com/0chain/zwalletcli.git
cd zwalletcli
make install
After a successful build, running the ./zwalletcommand will output a help section.
3.Now get the tokens into your wallet by using
./zwallet faucet --methodName pour --input "{Pay day}"
On Successful response:
4.Check Token balance in zwallet using the
./zwallet getbalance
6.Once the wallet has an available balance, you can create a storage allocation by using the Zbox newallocationcommand. To understand the syntax type
./zbox newallocation --help
This will output the mandatory and optional flags that need to be added with the newallocationcommand.Here are the parameters :
Valid Values
local file to store allocation information
file path
returns the cost of the allocation, no allocation created
number of data shards, effects upload and download speeds
duration to allocation expiration
free storage marker file.
file path
owner's id, use for funding an allocation for another
public key, use for funding an allocation for another
lock write pool with given number of tokens
max challenge completion time
number of parity shards, effects availability
filter blobbers by read price range
size of space reserved on blobbers
give token value in USD
filter blobbers by write price range
7. For getting started we can create a basic allocation with default types. This will only require essential specifiers such as lock float. We will add a float value of 0.5 which will lock 0.5 tokens with the allocation. The complete command for creating an allocation would be:
./zbox newallocation --lock 0.5
​ Successful Response will create an allocation with allocation ID:
If you are not able to create allocation and getting errors, check error **** causes in TIps and Troubleshooting Section.
8. Verify the allocation by using the command.
./zbox listallocations