> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# cowboy container

> Register CIP-10 container images, resource classes, and persistent workloads

## Synopsis

```bash theme={null}
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](https://docs.cowboy.inc/cips/cip-10-runner-containers.md) 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](https://docs.cowboy.inc/cli-specs/key-auto-discovery.md) (`--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:**

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

A digest may carry up to four locators, one per publisher ([CIP-10 §5.5](https://docs.cowboy.inc/cips/cip-10-runner-containers.md) 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](https://docs.cowboy.inc/cips/cip-10-runner-containers.md) 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:**

```bash theme={null}
$ 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:**

1. 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).
2. 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`).
3. 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:**

```bash theme={null}
$ 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:**

```bash theme={null}
$ 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:**

1. 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).
2. 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.
3. 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](https://docs.cowboy.inc/cips/cip-10-runner-containers.md)).
* `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.