cowboy container

Synopsis

cowboy container register-image --digest <hex> --volume-id <hex> --object-path <path> --object-hash <hex> --delta-bytes <n> --rootfs-bytes <n> [--base-digest <hex>] [--name <str>]
cowboy container deregister-image --digest <hex>
cowboy container images [--digest <hex>]... [--json]
cowboy container register-class --name <str> --cpu-millicores <n> --memory-mib <n> --scratch-disk-mib <n> --max-duration-sec <n> [flags]
cowboy container deregister-class --name <str>
cowboy container register-workload --name <str> --owning-actor <address> --image-digest <hex> --resource-class <str> [flags]
cowboy container update-workload --workload-id <hex> --expected-generation <n> [flags]
cowboy container deregister-workload --workload-id <hex>
cowboy container begin-workload-attempt --workload-id <hex> --generation <n> --attempt <n> --reporter <address> --prepared-until-block <n> [--recipient <spec>]...
cowboy container report-workload-status --workload-id <hex> --generation <n> [--attempt <n>] --status <status>
cowboy container dispute --job-id <hex>

cowboy container submits instructions to the CIP-10 Container Registry system actor (0x13) and reads back what is registered. Image registration is permissionless: any account may register a digest whose bytes it hosts in a public CIP-9 volume it owns. Binding a reserved (cby-) image name and defining resource classes require a genesis.system_deployers key. Every write subcommand accepts the global --private-key and --rpc-url, resolved with key auto-discovery (--private-key file, then COWBOY_PRIVATE_KEY_FILE, COWBOY_PRIVATE_KEY, then the keystore key the selected environment names).

Subcommands

`cowboy container register-image`

Register a container image: its composed-rootfs digest plus the CBFS locator a runner fetches its bytes from. Behavior:

Parse the 32-byte digests and build a RegisterImage instruction. An omitted --name encodes as the empty name (an ordinary, unprivileged registration).
Sign with the discovered key (resource limits from the node’s estimate), print the transaction hash, and POST /submit.
Print the node response.

A digest may carry up to four locators, one per publisher (CIP-10 §5.5 check 1, §5.6). Each publisher’s locator is create-only: the registry refuses a digest for which the signer already holds a locator, live or tombstoned. Registering a digest another publisher already registered adds a mirror of the same bytes, and a job resolves through the first locator that is serving. A fifth publisher is refused while four locators, tombstoned ones included, remain unreaped. Flags:

Flag	Default	Description
`--digest`	Required	Composed-rootfs BLAKE3 digest, hex (32 B); must not be zero
`--base-digest`	None	Registered digest of the base this delta composes onto; omit for a whole-rootfs image. One level deep only
`--volume-id`	Required	CIP-9 volume holding the delta object, hex (32 B)
`--object-path`	Required	CBFS manifest path of the delta object; max 256 bytes
`--object-hash`	Required	BLAKE3 plaintext content hash of the delta object, hex (32 B)
`--delta-bytes`	Required	Compressed size of the delta object; non-zero, max 256 MiB
`--rootfs-bytes`	Required	Unpacked size of the composed rootfs; non-zero, max 2 GiB
`--name`	None	Bind a CIP-10 §5.11 registry name (3-63 bytes of `a-z`, `0-9`, `-`; starts and ends alphanumeric; no `--`). An unreserved name is first-come and its first registrant is its controller; a `cby-` name needs a `genesis.system_deployers` key and a whole-rootfs image; `cby-example-` names are refused. Only the controller (or, for a `cby-` name, a `system_deployers` key) may point an already-bound name at a new digest
`--private-key`	Auto-discovered	Private key file path
`--rpc-url`	Auto-discovered	Validator RPC URL

Example:

$ cowboy container register-image \
    --digest 0x1f2e... --volume-id 0xa1b2... \
    --object-path /images/app.tar.zst --object-hash 0xc3d4... \
    --delta-bytes 52428800 --rootfs-bytes 314572800
  Transaction hash: 0xabc123...
RegisterImage submitted: <node response>

`cowboy container deregister-image`

Retire your own locator for a registered digest. Two-phase under this one command: the first call tombstones the locator (admission stops immediately; in-flight jobs can still resolve it); a second call at least 600 blocks later reaps it and frees the volume’s registration slot. Tombstoning the digest’s last live locator is refused while a persistent workload still references the digest. Flags:

Flag	Default	Description
`--digest`	Required	Registered image digest, hex (32 B)
`--private-key`	Auto-discovered	Private key file path
`--rpc-url`	Auto-discovered	Validator RPC URL

`cowboy container images`

Show registered images with every locator per digest and each locator’s live volume status. Read-only; no signing key. Behavior:

Collect the digests named with --digest. With none, scan the registry’s il: image listing index in bounded pages (up to 20 pages of 500 digests; a warning is printed if more remain).
For each digest, read its ordered locator list from the registry via the exact-key storage RPC, then read each locator’s volume status from the Storage Manager (0x0A).
Print one line per digest (name=, admissible= and locators=) followed by one indented line per locator. A digest with no locators prints NOT REGISTERED. With --json, print a JSON array with one entry per digest instead.

Flags:

Flag	Default	Description
`--digest`	None	Show only this registered image digest, hex (32 B), instead of every listed one; repeatable
`--json`	`false`	Print a JSON array with one entry per digest
`--rpc-url`	Auto-discovered	Validator RPC URL

Example:

$ cowboy container images --digest 0x1f2e...
  1f2e...  name=(unnamed) admissible=true locators=1
    [0] publisher=0x7a3B...F92E volume=a1b2... volume_status=Active tombstoned=false serving=true base=none delta_bytes=52428800 rootfs_bytes=314572800 registered_at=1200

`cowboy container register-class`

Operator: define a resource class. Its name is the resource_tier a container job selects. Flags:

Flag	Default	Description
`--name`	Required	Class name (e.g. `small`)
`--cpu-millicores`	Required	CPU allocation in millicores
`--memory-mib`	Required	Memory in MiB
`--scratch-disk-mib`	Required	Scratch disk in MiB; at least 128
`--max-duration-sec`	Required	Wall-clock ceiling per job in seconds; `4294967295` sets no limit, `0` is invalid
`--gpu-count`	`0`	GPUs required
`--gpu-min-vram-mib`	`0`	Minimum GPU VRAM in MiB
`--private-key`	Auto-discovered	Private key file path
`--rpc-url`	Auto-discovered	Validator RPC URL

Example:

$ cowboy container register-class --name small --cpu-millicores 500 --memory-mib 512 --scratch-disk-mib 128 --max-duration-sec 300
  Transaction hash: 0xdef789...
RegisterResourceClass submitted: <node response>

`cowboy container deregister-class`

Operator: remove a resource class. Flags:

Flag	Default	Description
`--name`	Required	Class name
`--private-key`	Auto-discovered	Private key file path
`--rpc-url`	Auto-discovered	Validator RPC URL

`cowboy container register-workload`

Register a persistent workload — a container whose lifetime is governed by its registry record — signed by the owning actor’s controller. An unreserved workload escrows a refundable 10 CBY deposit. It registers unclaimed: a runner in its host pool claims it and names its serving endpoint. Behavior:

Derive the workload id from the owning actor and --name, and build a WorkloadRecord with observed status provisioning, no serving endpoint, and the given fields (the chain assigns the generation).
Validate each --mount (<volume_id_hex>:<mount_path>:<ro|rw>:<principal_address>; the path must be canonical and absolute, at most 256 bytes; no volume twice and no overlapping paths) and the host pool.
Sign and submit RegisterWorkload, then wait for a committed successful receipt.

Flags:

Flag	Default	Description
`--name`	Required	Workload name, a CIP-10 registry name unique within the owning actor
`--owning-actor`	Required	Actor that owns the workload (must be deployed)
`--image-digest`	Required	Registered image rootfs digest, hex (32 B)
`--resource-class`	Required	Registered resource class name
`--host-pool`	`cby-workload-hosts`	Runner pool whose members may claim the workload: a reserved `cby-` pool name, or `0x<owner address>/<pool name>`
`--mount`	None	CBFS mount spec; repeatable
`--restart-policy`	`always`	`never`, `on-failure`, or `always`
`--desired-state`	`running`	`running` or `stopped`
`--private-key`	Auto-discovered	Private key file path
`--rpc-url`	Auto-discovered	Validator RPC URL

`cowboy container update-workload`

Change a workload record, signed by the owning actor’s controller (a system_deployers key may stop any workload). Only --desired-state stopped alone applies to a live workload; every other change needs the record already stopped and its last attempt no longer live. Waits for a committed successful receipt. Flags:

Flag	Default	Description
`--workload-id`	Required	Workload id, hex (32 B)
`--expected-generation`	Required	Generation the change is made against
`--image-digest`	None	New image digest
`--resource-class`	None	New resource class
`--host-pool`	None	Move the workload to another runner pool
`--mount`	None	Replace the mount list; repeatable
`--clear-mounts`	`false`	Replace the mount list with none. Conflicts with `--mount`
`--restart-policy`	None	`never`, `on-failure`, or `always`
`--desired-state`	None	`running` or `stopped`
`--private-key`	Auto-discovered	Private key file path
`--rpc-url`	Auto-discovered	Validator RPC URL

`cowboy container deregister-workload`

Remove a stopped, not-live workload record: by the owning actor’s controller, refunding its deposit, or by any system_deployers key. Flags:

Flag	Default	Description
`--workload-id`	Required	Workload id, hex (32 B)
`--private-key`	Auto-discovered	Private key file path
`--rpc-url`	Auto-discovered	Validator RPC URL

`cowboy container begin-workload-attempt`

Reporter: commit the next attempt and its volume recipients before key release. Flags:

Flag	Default	Description
`--workload-id`	Required	Workload id, hex (32 B)
`--generation`	Required	Record generation
`--attempt`	Required	Attempt number being begun
`--reporter`	Required	Reporter address
`--prepared-until-block`	Required	Block height the prepared attempt is valid until
`--recipient`	None	`VOLUME_ID:RECIPIENT_ID:RELEASE_PUBKEY:COMMIT_PUBKEY` (32-byte hex values; the two keys must be distinct, valid, non-weak Ed25519 keys; one recipient per volume); repeatable
`--private-key`	Auto-discovered	Private key file path
`--rpc-url`	Auto-discovered	Validator RPC URL

`cowboy container report-workload-status`

Reporter: publish the workload’s observed status for a generation. Flags:

Flag	Default	Description
`--workload-id`	Required	Workload id, hex (32 B)
`--generation`	Required	Generation being reported
`--attempt`	`0`	Service attempt number; `0` reports before any attempt has begun
`--status`	Required	`provisioning`, `running`, `degraded`, or `stopped`
`--private-key`	Auto-discovered	Private key file path
`--rpc-url`	Auto-discovered	Validator RPC URL

`cowboy container dispute`

Submitter: dispute a container job’s billing attestation inside the dispute window. A dispute forfeits the refund (the full pre-locked maximum is charged) and lowers the runner’s reputation; it does not adjudicate the true usage. Flags:

Flag	Default	Description
`--job-id`	Required	Job id, hex (32 B)
`--private-key`	Auto-discovered	Private key file path
`--rpc-url`	Auto-discovered	Validator RPC URL

Edge Cases

--delta-bytes and --rootfs-bytes must be non-zero; a zero value describes an image a runner can never stream.
--name on register-image with a cby- name requires a genesis.system_deployers key. A name already bound to another controller is refused; when its controller (or, for a cby- name, a system_deployers key) names it again under a new digest, the name entry points at the new digest and the superseded digest stays registered (CIP-10 §5.11).
deregister-image acts only on your own locator; other publishers’ mirrors of the same digest are untouched. A locator registered under a cby- name also requires a system_deployers key to retire. Deregistration never deletes a name entry.
--clear-mounts and --mount together are rejected before submission.
Every write signs with resource limits from the node’s estimate.
The settlement split (UpdateContainerSettlementConfig) is governance-gated and is intentionally not exposed here.

Start Here

Build

How Cowboy Works

Reference

Synopsis

Subcommands

`cowboy container register-image`

`cowboy container deregister-image`

`cowboy container images`

`cowboy container register-class`

`cowboy container deregister-class`

`cowboy container register-workload`

`cowboy container update-workload`

`cowboy container deregister-workload`

`cowboy container begin-workload-attempt`

`cowboy container report-workload-status`

`cowboy container dispute`

Edge Cases

​Synopsis

​Subcommands

​cowboy container register-image

​cowboy container deregister-image

​cowboy container images

​cowboy container register-class

​cowboy container deregister-class

​cowboy container register-workload

​cowboy container update-workload

​cowboy container deregister-workload

​cowboy container begin-workload-attempt

​cowboy container report-workload-status

​cowboy container dispute

​Edge Cases

Synopsis

Subcommands

`cowboy container register-image`

`cowboy container deregister-image`

`cowboy container images`

`cowboy container register-class`

`cowboy container deregister-class`

`cowboy container register-workload`

`cowboy container update-workload`

`cowboy container deregister-workload`

`cowboy container begin-workload-attempt`

`cowboy container report-workload-status`

`cowboy container dispute`

Edge Cases