> For the complete documentation index, see [llms.txt](https://docs.zus.network/zus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zus.network/zus-docs/clis/zboxcli/installation.md).

# Installation

The **zbox CLI** can be built and installed on Linux, macOS, and other supported platforms.\
This guide covers prerequisites, system requirements, installation steps, and how to run your first `zbox` command.

### Prerequisites

* **Go**\
  Install Go for [Mac, Linux, or Windows](https://golang.org/doc/install). Then, Verify installation:

  ```bash
  go version
  ```
* **Git**\
  Required to clone the repository (not needed on macOS by default).

  ```bash
  sudo apt install git
  ```
* **Build Tools**

  * Linux/macOS: `make`, `gcc`, or `clang`
  * Recommended: `gcc 11` for compatibility (Ubuntu 22 ships with gcc-11 by default; Ubuntu 20 requires upgrade).

  Upgrade gcc on Ubuntu 20:

  ```bash
  sudo add-apt-repository ppa:ubuntu-toolchain-r/test
  sudo apt update
  sudo apt install build-essential
  sudo apt install gcc-11 g++-11
  ```

### System Requirements

Minimum recommended machine specifications for building and running `zbox`:

* **Linux (Ubuntu preferred):** Version 20.04+
* **macOS:** Big Sur+ (Intel or Apple Silicon)
* **CPU:** 4 vCPU
* **Memory:** 4 GB RAM
* **Storage:** 2 GB free space (build + storage allocation)

### Installation

#### 1. Clone the Repository

```bash
git clone https://github.com/0chain/zboxcli.git
cd zboxcli
```

#### 2. Build and Install

```bash
make install
```

This compiles the binary and installs it into your `$GOPATH/bin` or system path.

### Configuration

zbox requires a config file located at:

```
$HOME/.zcn/config.yaml
```

Create it using the following script:

```bash
mkdir -p ~/.zcn
cat > ~/.zcn/config.yaml << EOF
block_worker: https://mainnet.zus.network/dns
signature_scheme: bls0chain
min_submit: 50 # in percentage
min_confirmation: 50 # in percentage
confirmation_chain_length: 3
EOF
```

This sets the **Züs mainnet** as your default network.

### Running zbox

Navigate to the `zboxcli` directory and run:

```bash
./zbox
```

Running without arguments displays the full list of supported commands and global flags.

Example usage output:

```
Usage:
  zbox [command]

Available Commands:
  add                Adds free storage assigner
  alloc-cancel       Cancel an allocation
  alloc-fini         Finalize an expired allocation
  bl-info            Get blobber info
  bl-update          Update blobber settings by its delegate_wallet owner
  collect-reward     Collect accrued rewards for a stake pool.
  completion         Generate the autocompletion script for the specified shell
  copy               Copy an object(file/folder) to another folder on blobbers
  ...
  wp-unlock          Unlock some expired tokens in a write pool.
```

### Alternative Builds

For non-standard platforms (e.g., **ARM64 Linux, Raspberry Pi 3B+**):

1. Download the build script:

   ```bash
   wget https://raw.githubusercontent.com/0chain/zboxcli/master/pibuild.sh
   ```
2. Run the script:

   ```bash
   bash pibuild.sh
   ```

This builds the MCL/BLS libraries with the required `MCL_USE_GMP=0` flag and installs `zbox`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.zus.network/zus-docs/clis/zboxcli/installation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.