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

> Build and manage long-running services

A workload is a service that keeps running, owned by an actor. `cowboy init --workload` declares one and `cowboy deploy` ships it; `cowboy workload` builds, stops and starts it. See [Run a web app or service](https://docs.cowboy.inc/developers/ship-a-web-app.md).

```text theme={"system"}
cowboy workload [OPTIONS] <COMMAND>
```

| Command | Description |
| - | - |
| [`mount-policy`](#cowboy-workload-mount-policy) | Sign or revoke a volume owner's standing mount policy for a workload |
| [`build`](#cowboy-workload-build) | Build a native persistent workload using the shared base-plus-delta recipe |
| [`status`](#cowboy-workload-status) | Show a deployed workload's registry record in the selected environment |
| [`stop`](#cowboy-workload-stop) | Set a deployed workload's desired state to stopped |
| [`start`](#cowboy-workload-start) | Set a stopped workload's desired state back to running |

## cowboy workload mount-policy

Sign or revoke a volume owner's standing mount policy for a workload

```text theme={"system"}
cowboy workload mount-policy [OPTIONS] <COMMAND>
```

| Command | Description |
| - | - |
| [`sign`](#cowboy-workload-mount-policy-sign) | Sign and publish the policy letting the workload's host pool mount a volume you own |
| [`revoke`](#cowboy-workload-mount-policy-revoke) | Revoke the policy for a volume you own, withdrawing every host at once |

### cowboy workload mount-policy sign

Sign and publish the policy letting the workload's host pool mount a volume you own

```text theme={"system"}
cowboy workload mount-policy sign [OPTIONS] --volume <VOLUME> --checkpoint <CHECKPOINT> --proof-state-dir <PROOF_STATE_DIR> <WORKLOAD_ID>
```

| Argument | Description |
| - | - |
| `<WORKLOAD_ID>` | Registered workload ID (32-byte hex) |

| Option | Description |
| - | - |
| `--volume <VOLUME>` | Mounted volume ID (32-byte hex) |
| `--valid-until-epoch <VALID_UNTIL_EPOCH>` | Last storage epoch the policy authorizes; never expires when omitted |
| `--checkpoint <CHECKPOINT>` | Trusted finalized checkpoint file obtained independently of the RPC |
| `--proof-state-dir <PROOF_STATE_DIR>` | Private directory for the durable proof rollback floor |

### cowboy workload mount-policy revoke

Revoke the policy for a volume you own, withdrawing every host at once

```text theme={"system"}
cowboy workload mount-policy revoke [OPTIONS] --volume <VOLUME> <WORKLOAD_ID>
```

| Argument | Description |
| - | - |
| `<WORKLOAD_ID>` | Registered workload ID (32-byte hex) |

| Option | Description |
| - | - |
| `--volume <VOLUME>` | Mounted volume ID (32-byte hex) |
| `--up-to-revision <UP_TO_REVISION>` | Also void every policy you signed at or below this revision (below 2^64 - 1). The chain always voids your next one (floor + 1), the revision this tool signs. Default: `0`. |

## cowboy workload build

Build a native persistent workload using the shared base-plus-delta recipe

```text theme={"system"}
cowboy workload build [OPTIONS] <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | Named \[workloads.\<name>] declaration |

| Option | Description |
| - | - |
| `--project <PROJECT>` | |
| `--base-rootfs <BASE_ROOTFS>` | Unpacked rootfs for the declared cby-runner-python, cby-runner-node or cby-runner-rust base; avoids network acquisition |
| `--expected-base-digest <EXPECTED_BASE_DIGEST>` | Required base digest (32-byte hex); cannot change an existing pin |
| `--json` | Emit one JSON result |

## cowboy workload status

Show a deployed workload's registry record in the selected environment

```text theme={"system"}
cowboy workload status [OPTIONS] <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | Named \[workloads.\<name>] declaration |

| Option | Description |
| - | - |
| `--json` | Emit one JSON result |

## cowboy workload stop

Set a deployed workload's desired state to stopped

```text theme={"system"}
cowboy workload stop [OPTIONS] <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | Named \[workloads.\<name>] declaration |

| Option | Description |
| - | - |
| `--json` | Emit one JSON result |

## cowboy workload start

Set a stopped workload's desired state back to running

```text theme={"system"}
cowboy workload start [OPTIONS] <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | Named \[workloads.\<name>] declaration |

| Option | Description |
| - | - |
| `--json` | Emit one JSON result |


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