> 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/creating-and-managing-allocations.md).

# Creating & Managing Allocations

An **allocation** is reserved storage space on blobbers. The `zbox` CLI provides commands to create, update, transfer, forbid, cancel, finalize allocations, and manage blobber/validator settings.

{% hint style="warning" %}
You may see commands written as `./zbox` or `zbox`.

* Use `./zbox` if you are running the binary directly from the folder where it was built (e.g., after `make install` inside the repo).
* Use `zbox` if the binary has been installed into your system’s `$PATH` (e.g., `/usr/local/bin`), which lets you call it from anywhere.

Functionally, both are the same — the difference is whether your system can find the `zbox` command globally or only in the current directory.
{% endhint %}

***

### 1. Create New Allocation

The `newallocation` command reserves hard disk space on blobbers. Later, `upload` can be used to save files to the allocation.

`newallocation` has three modes:

* **Cost mode** (`--cost`) → Returns only the estimated cost.
* **Free storage mode** (`--free_storage`) → Uses a free storage marker JSON.
* **Standard mode** (default) → Creates an allocation with user-specified parameters.

#### Command

```bash
zbox newallocation [flags]
```

#### Parameters

| Parameter                  | Description                                                    | Default        | Values           |
| -------------------------- | -------------------------------------------------------------- | -------------- | ---------------- |
| `--allocationFileName`     | Local file to store allocation info                            | allocation.txt | file path        |
| `--cost`                   | Estimate cost only                                             | –              | flag             |
| `--data`                   | Number of data shards (affects speed)                          | 2              | int              |
| `--parity`                 | Number of parity shards (affects durability)                   | 2              | int (1 < p < 30) |
| `--size`                   | Reserved space (bytes)                                         | 2147483648     | int              |
| `--lock*`                  | Tokens locked in write pool                                    | required       | float            |
| `--free_storage`           | Free storage marker file                                       | –              | path             |
| `--owner`                  | Owner’s ID (create for another user)                           | client         | string           |
| `--owner_public_key`       | Owner’s public key                                             | –              | string           |
| `--read_price`             | Max read price                                                 | 0–inf          | range            |
| `--write_price`            | Max write price                                                | 0–inf          | range            |
| `--usd`                    | Show value in USD                                              | –              | flag             |
| `--third_party_extendable` | Allow extensions by others                                     | false          | bool             |
| `--forbid_*`               | Forbid operations (upload, delete, update, move, copy, rename) | false          | bool             |
| `--blobber_auth_tickets`   | Comma-separated auth tickets                                   | –              | strings          |
| `--preferred_blobbers`     | Comma-separated blobber IDs                                    | auto           | strings          |
| `--force`                  | Force allocation even if insufficient blobbers                 | false          | bool             |
| `--name`                   | Allocation name                                                | –              | string           |

> * `--lock` is required unless `--free_storage` is used.

#### Free Storage Marker Format

```json
{
  "assigner": "my_corporation",
  "recipient": "f174cdda7e24aeac0288afc2e8d8b20eda06b18333efd447725581dc80552977",
  "free_tokens": 2.1,
  "timestamp": 2000000,
  "signature": "9edb86c8710d5e3ee4fde247c638fd6b81af67e7bb3f9d60700aec8e310c1f06"
}
```

#### Examples

**Standard Allocation**

```bash
./zbox newallocation --lock 0.5
```

**Free Storage Allocation**

```bash
./zbox newallocation --lock 0.5 --free_storage markers/my_marker.json
```

**Response**

```
Allocation created : d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac
```

***

### 2. Update Allocation

`updateallocation` modifies allocation settings.

Modes:

* **Free storage update** → Uses `--free_storage` marker.
* **Standard update** → Extends expiry, size, or adds/removes blobbers.

#### Command

```bash
zbox updateallocation --allocation <id> [flags]
```

#### Key Parameters

| Parameter                  | Description                                        |
| -------------------------- | -------------------------------------------------- |
| `--allocation`             | Allocation ID (required)                           |
| `--extend`                 | Extend expiry (duration, e.g. `48h`)               |
| `--size`                   | Increase allocation size (bytes)                   |
| `--lock`                   | Add tokens to write pool                           |
| `--add_blobber`            | Add blobber (requires `--remove_blobber` for swap) |
| `--remove_blobber`         | Remove blobber                                     |
| `--third_party_extendable` | Allow others to extend                             |
| `--forbid_*`               | Forbid operations (upload, delete, etc.)           |

#### Examples

```bash
./zbox updateallocation --allocation <id> --expiry 48h --size 4096
./zbox updateallocation --allocation <id> --free_storage markers/my_marker.json
```

**Response**

```
Allocation updated with txId : fb84185dae620bbba8386286726f1efcd20d2516bcf1a448215434d87be3b30d
```

***

### 3. Transfer Allocation Ownership

Transfer allocation from current owner to another user.

#### Command

```bash
zbox transferallocation --allocation <id> --new_owner <id> --new_owner_key <pubkey>
```

**Response**

```
Transferred ownership of allocation : <id> to <new_owner>
```

### 4. Forbid Allocation Operations

Restrict operations using forbid flags with `updateallocation`.

| Flag              | Effect               |
| ----------------- | -------------------- |
| `--forbid_upload` | Prevent file uploads |
| `--forbid_delete` | Prevent deletions    |
| `--forbid_update` | Prevent updates      |
| `--forbid_move`   | Prevent moves        |
| `--forbid_copy`   | Prevent copies       |
| `--forbid_rename` | Prevent renames      |

**Example**

```bash
./zbox updateallocation --allocation <id> --forbid_upload
```

***

### 5. Cancel Allocation

Immediately cancels allocation and returns tokens (except already distributed to blobbers).

#### Command

```bash
zbox alloc-cancel --allocation <id>
```

**Response**

```
Allocation canceled with txId : 501df5a8e2a6b8ebced1d1e7dc4ed17f653012dd49834801b4413786ec031cd2
```

***

### 6. Finalise Allocation

Finalises an expired allocation. Can be run by owner or blobber.

#### Command

```bash
zbox alloc-fini --allocation <id>
```

**Response**

```
Allocation finalized with txId : 2a6c031ced1d1e7dc4ed17801b4413786ecd2501df5ab8ebf653012dd498348e
```

***

### 7. Listing Allocations & Blobbers

#### List Allocations

```bash
zbox listallocations
```

#### List All Files in Allocation

```bash
zbox list-all --allocation <id>
```

#### List Blobbers

```bash
zbox ls-blobbers
```

#### Blobber Info

```bash
zbox bl-info --blobber_id <id>
```

***

### 8. Blobber & Validator Settings

#### Update Blobber Settings

```bash
zbox bl-update --blobber_id <id> --read_price 0.1
```

#### Update Validator Settings

```bash
zbox validator-update --validator_id <id> --service_charge 0.1
```

#### List Validators

```bash
zbox ls-validators
```

#### Validator Info

```bash
zbox validator-info --validator_id <id>
```

***

### 9. Shutdown / Kill Blobbers & Validators

#### Shutdown Blobber

```bash
zbox shutdown-blobber --id <id> --wallet <chain_owner_wallet>
```

#### Kill Blobber

```bash
zbox kill-blobber --id <id> --wallet <chain_owner_wallet>
```

#### Shutdown Validator

```bash
zbox shutdown-validator --id <id> --wallet <chain_owner_wallet>
```

#### Kill Validator

```bash
zbox kill-validator --id <id> --wallet <chain_owner_wallet>
```

***

### 10. Version

Get CLI & SDK version:

```bash
zbox version
```

**Response**

```
zbox....: v1.4.3
gosdk...: v1.8.14
```