> ## 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 rooms

> Owner-side room setup, create rooms, add seats, and install native actor routes

## Synopsis

```bash theme={null}
cowboy rooms create --request <path> --provider <address>
cowboy rooms create-control-lane --room-id <hex32> --admin-key <path> --policy-epoch <n> [broker flags]
cowboy rooms seat-id --room-id <hex32> --actor <address>
cowboy rooms prepare-template --room-id <hex32> --request <path> --output-dir <dir> [--wake-on-all]
cowboy rooms sign-template --projected-seat <path> --session-descriptor <path>
                           --agent-job-template <path> --record-key <path> --output <path>
cowboy rooms add-seat --room-id <hex32> --seat <path> --envelope-commitment <hex32>
                      --template <path> --control-lane <n> --admin-key <path> --policy-epoch <n>
                      [--wake-on-all] [--template-sequence <n>] [broker flags]
cowboy rooms update-template --room-id <hex32> --seat-id <hex32> --template <path>
                             --control-lane <n> --admin-key <path> --policy-epoch <n>
                             [--template-sequence <n>] [broker flags]
cowboy rooms create-inbox-group --room-id <hex32> --seat-id <hex32> --admin-key <path>
                                --policy-epoch <n> [broker flags]
cowboy rooms bind-consumer --room-id <hex32> --seat-id <hex32> --group-id <n>
cowboy rooms deploy-actor --code <path> --salt <hex> --manifest-json <path> --route <path>
                          [--init-handler <name> [--init-payload <hex>]] [--cells-limit <n>]
cowboy rooms provision-gateway --room-id <hex32> --gateway-ref <ref> --allow-current-room-read
                               --room-key <path> --admin-key <path> --policy-epoch <n>
                               --output <path> [--role-label <label>] [--expires-in <secs>]
                               [broker flags]
cowboy rooms close-session --session-id <hex32>
cowboy rooms trace [--room-id <hex32>] [--actor <address> | --seat-id <hex32>]
                   [--tx <hash>] [--job <id>] [--statusz <url>]...
```

`[broker flags]` are `[--broker-url <url>] [--broker-address <host:port> --broker-ca-der <path>]`. `--rpc-url` and `--private-key` are global flags; the private key is the room owner's.

````

Every subcommand parses its local artifacts before discovering a key or touching the network. Each on-chain step is submitted and then awaited: the CLI prints `submit <label> (nonce <n>)` and the transaction hash, waits up to 120 seconds for a committed receipt, and prints `committed <label>: block <height>`. A receipt that reports a failed execution is an error. Every submission is signed with limits from the node's estimate at the node's current fee quote; if the estimate fails, nothing is submitted.

The design is read-then-reconcile: the CLI reads committed rows first, submits only the missing ones, and refuses when an existing row differs from what the request describes. Rerunning a partially completed command therefore continues it instead of duplicating it.

## Subcommands

### `cowboy rooms create`

Create one v2 stream, then its RoomAuthority (`0x19`) record.

**Behavior:**

1. Read `--request` as a protocol `CreateRoomV1` JSON document; zero stream and operation ids in it are derived.
2. Read the committed stream and room records. If the stream exists and matches the request (ignoring `authorization_generation`, which advances in normal use), print `skip matching stream 0x...`; otherwise submit `CBQS CreateStream` and verify the committed record. A room that exists without its stream is refused.
3. If the room exists, print `skip matching room 0x...`; otherwise submit `RoomAuthority CreateRoom`, verify the committed record, and print `room 0x<room_id>; stream 0x<stream_id>`.

**Flags:**

| Flag | Default | Description |
|------|---------|-------------|
| `--request` | Required | Existing protocol `CreateRoomV1` JSON |
| `--provider` | Required | Provider address (20-byte hex) |

---

### `cowboy rooms add-seat`

Publish a signed control template, then add the seat referencing its sequence.

**Flags:**

| Flag | Default | Description |
|------|---------|-------------|
| `--room-id` | Required | Room id (32-byte hex) |
| `--seat` | Required | Existing protocol `RoomSeatConfigV1` JSON; `service_ref` is filled from the template |
| `--envelope-commitment` | Required | 32-byte hex; must be nonzero |
| `--template` | Required | Canonical signed `RoomWakeTemplateV1` bytes |
| `--control-lane` | Required | Existing ordinary control lane on the room's stream |
| `--admin-key` | Required | Stream admin Ed25519 seed: 32 bytes encoded as hex in a file |
| `--policy-epoch` | Required | Authoritative owner policy epoch (`0` for a newly provisioned stream) |
| `--wake-on-all` | `false` | Add the wake-on-all scope; must match the scopes `prepare-template` signed |
| `--broker-url` | Provider's first registered endpoint | Registered provider endpoint |
| `--broker-address` | None | Explicit broker socket for local/private deployments; requires `--broker-ca-der` |
| `--broker-ca-der` | None | DER CA certificate for `--broker-address` |
| `--template-sequence` | None | Resume after an append: read and compare this sequence instead of appending |

---

### `cowboy rooms create-control-lane`

Create an ordinary CBQS lane on the room's stream for signed wake templates. Takes `--room-id`, `--admin-key`, `--policy-epoch`, and the broker flags.

---

### `cowboy rooms seat-id`

Print the native actor seat id derived from `--room-id` and `--actor`. No network access.

---

### `cowboy rooms prepare-template`

Write canonical `session-open.bin`, `agent-job.bin` and `projected-seat.json` for a fresh actor seat into a new `--output-dir`. `--request` is the seat, group, session limits and Agent JobSpec JSON; `--wake-on-all` wakes the actor on every Human or door message instead of on mentions only.

---

### `cowboy rooms sign-template`

Sign the session descriptor and Agent job template for the seat in `--projected-seat` with the actor's record-signing Ed25519 seed (`--record-key`, 32 bytes as hex in a file), writing canonical signed `RoomWakeTemplateV1` bytes to a new `--output` file. Local only.

---

### `cowboy rooms update-template`

Replace the signed wake template referenced by an existing actor seat. Flags as `add-seat`, with `--seat-id` in place of `--seat`, `--envelope-commitment` and `--wake-on-all`.

---

### `cowboy rooms create-inbox-group`

Materialize an actor seat's inbox lane and create its CBQS consumer group. Takes `--room-id`, `--seat-id`, `--admin-key`, `--policy-epoch`, and the broker flags.

---

### `cowboy rooms bind-consumer`

Bind an existing CBQS inbox group (`--group-id`, nonzero) to an actor seat after its template is published. Prints `bound actor seat 0x... to group <n>`, or `skip matching actor consumer group <n>` when already bound.

---

### `cowboy rooms deploy-actor`

Deploy a room actor; the chain installs its native route with the code.

| Flag | Default | Description |
|------|---------|-------------|
| `--code` | Required | Actor source; must define the route handler `__cowboy_room_reply` |
| `--salt` | Required | Deploy salt, hex |
| `--manifest-json` | Required | ActorManifest JSON granting the route's `secrets.read` and `secrets.sign` keys |
| `--route` | Required | Route request JSON: `owner`, `room_key_name`, `seat_key_name`, `metering_public_key`, `bundle_hash` (SHA-256 of `--code`) and `runtime_hash` |
| `--init-handler` | None | Init handler name |
| `--init-payload` | None | Init payload, hex; requires `--init-handler` |
| `--cells-limit` | Node estimate | Cells limit |

---

### `cowboy rooms provision-gateway`

Enroll an independent Gateway seat and write its exact-lane access file.

| Flag | Default | Description |
|------|---------|-------------|
| `--room-id` | Required | Room id (32-byte hex) |
| `--gateway-ref` | Required | Native channel identifier, for example `telegram:-100123456` |
| `--role-label` | `telegram` | Seat role label |
| `--allow-current-room-read` | Required | Explicitly allow reading retained messages encrypted with the current room key |
| `--room-key` | Required | Room generation key: 32 hex bytes in a private file |
| `--admin-key` | Required | Stream admin seed; used only during provisioning, never saved in the access file |
| `--policy-epoch` | Required | Authoritative owner policy epoch |
| `--expires-in` | `86400` | Grant lifetime in seconds (60 to 604800); rerun with the same `--output` to renew |
| `--output` | Required | Private access file; existing identity and keys must match on renewal |

Also accepts the broker flags.

---

### `cowboy rooms close-session`

Close a native room session (`--session-id`, 32-byte hex) using its admitted relayer's signing key.

---

### `cowboy rooms trace`

Read-only: walk one room wake hop by hop and name the first broken hop. `--room-id` needs `--actor` or `--seat-id` unless `--tx` (a RouteInvocation wake transaction hash) or `--job` (its parent job id) names the wake. `--statusz` adds a daemon `/statusz` base URL and is repeatable. No key is needed.

## Example

```bash
$ cowboy rooms create --request room.json --provider 0x2222...
submit CBQS CreateStream (nonce 3)
Transaction hash: 0xabc...
committed CBQS CreateStream: block 1042
submit RoomAuthority CreateRoom (nonce 4)
Transaction hash: 0xdef...
committed RoomAuthority CreateRoom: block 1043
room 0x9c0d...; stream 0x7f1e...
````

## Edge Cases

* A committed row that differs from the request is refused rather than overwritten; fix the request to match or use a new owner nonce.
* If a submission does not commit within the wait window the command fails with `receipt_pending`, naming the transaction hash; check it with `cowboy transaction status --hash <hash>` before rerunning, since a rerun signs a new transaction.
* The request, seat, and template formats are the protocol's own JSON and byte encodings; see the CIP-39 v2 and RoomAuthority specifications and `--help` for details not covered here.


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