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.
You may see commands written as ./zbox or zbox.
Use
./zboxif you are running the binary directly from the folder where it was built (e.g., aftermake installinside the repo).Use
zboxif 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.
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
zbox newallocation [flags]Parameters
--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
--lockis required unless--free_storageis used.
Free Storage Marker Format
Examples
Standard Allocation
Free Storage Allocation
Response
2. Update Allocation
updateallocation modifies allocation settings.
Modes:
Free storage update → Uses
--free_storagemarker.Standard update → Extends expiry, size, or adds/removes blobbers.
Command
Key Parameters
--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
Response
3. Transfer Allocation Ownership
Transfer allocation from current owner to another user.
Command
Response
4. Forbid Allocation Operations
Restrict operations using forbid flags with updateallocation.
--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
5. Cancel Allocation
Immediately cancels allocation and returns tokens (except already distributed to blobbers).
Command
Response
6. Finalise Allocation
Finalises an expired allocation. Can be run by owner or blobber.
Command
Response
7. Listing Allocations & Blobbers
List Allocations
List All Files in Allocation
List Blobbers
Blobber Info
8. Blobber & Validator Settings
Update Blobber Settings
Update Validator Settings
List Validators
Validator Info
9. Shutdown / Kill Blobbers & Validators
Shutdown Blobber
Kill Blobber
Shutdown Validator
Kill Validator
10. Version
Get CLI & SDK version:
Response
Last updated