Skip to main content
A volume is a named set of encrypted files that an actor can use. cowboy volume finds and reads them, and manages who may mount them and how they’re funded. To create volumes and write files, use cowboy cbfs. For how actors use files, see Files.

cowboy volume list

List volumes owned by the authenticated wallet

cowboy volume ls

List objects in one volume, including an actor’s registered image volume

cowboy volume mount

Mount a CBFS volume created by a runner job

cowboy volume cat

Read a file from a public CBFS volume without mounting it. Derives the volume’s id from owner and name, then reads the object in-process through the embedded CBFS client’s public read (cowboy cbfs cat --id) and writes the bytes to stdout (or --output). With --trusted-checkpoint the volume record and manifest root are proven against finalized chain state; without one the RPC supplies them. Private volumes are read through runner CBSS key delivery.

cowboy volume info

Show volume info from chain

cowboy volume allow-actor

Add (or remove) a principal on the volume’s mount allowlist. CIP-9 cross-owner private mounts: the dispatcher only honors a job’s volumes=[(name, mode, owner_hex)] attachment when the submitting principal is on the volume’s mount_allowed_actors list. Only the volume owner (the EOA that created the volume) may modify the list — this is a signed UpdateMountAllowlist transaction, sent under a full signed request envelope; the node’s execution checks the transaction’s own sender against the volume’s owner, not a bare delegation header. The dispatcher classifies the job submitter as an Actor principal when the actor was deployed WITH a manifest, and as an Account principal otherwise (manifest-less actors and plain EOAs). A grant only authorizes a mount when its principal *type* matches, so use --actor for manifest-bearing actors and --account for manifest-less actors / EOAs. Pass either flag, or both.

cowboy volume auto-top-up

Control how rent settlement refills your volumes’ escrow from your wallet. Auto top-up is on by default for every wallet: at each epoch boundary, settlement tops a volume’s escrow up to the governed default number of epochs of rent at its current size, first from your account storage reserve, then from your spendable balance, with no cap. --cap with --target-epochs sets your own target and a total cap (the setting turns off once the cap is spent); --off stops all wallet draws; --default returns to the default. Signed by your wallet (--private-key); no delegated key can change it. Writes are never funded from the wallet: a growing commit needs escrow at its rent floor.

cowboy volume withdraw

Move unused storage money back to your wallet’s balance. Without --name, withdraws from your account storage reserve, which holds escrow returned by garbage-collected volumes. With --name, withdraws from that volume’s escrow, after its rent is settled, down to no lower than its rent floor. Escrow anyone deposited to your volume is yours to withdraw.

cowboy volume delete

Delete one of your volumes and return its escrow to your storage reserve. Marks the volume deleted. It stays stored, and billed, through the undelete window; once that ends, settlement garbage-collects it and moves all of its remaining escrow, deposit included, into your account storage reserve. cowboy volume withdraw --amount <CBY> without --name then moves it to your balance. Use this to recover the money in a volume you no longer need: withdraw --name keeps the rent floor and deposit in a live volume. Signed by the owner’s wallet (--private-key).