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


---

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