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

> Build, publish, and fund a fresh project actor in one command

## Synopsis

```bash theme={null}
cowboy deploy [<target>] [--new] [--env <name> [--rpc-url <url>]] [--private-key <path>]
              [--shard <0..65535>] [--manifest-json <path>] [--max-spend <cby>] [--fund <cby>] [--initial-escrow <cby>]
              [--init-handler <name> [--init-payload <json|@file>]]
              [--no-owner-funding | --owner-funding-cap <CBY>]
              [--receipt-timeout <secs>] [--json] [--verbose]

# Advanced: deploy raw Python bytes, skipping the project pipeline
cowboy deploy --code <path> [--salt <hex>] [--shard <0..65535>] [--manifest-json <path>] [--nonce <n>]
              [--routes <file> [--route-sponsorship <file>]] [--fund <cby>]
              [--init-handler <name> [--init-payload <json|@file>] | --no-init]
              [--cycles-limit <n>] [--cells-limit <n>] [--access-limit <n>]
              [--max-fee-per-cycle <n>] [--max-fee-per-cell <n>] [--max-fee-per-access <n>]
              [--max-priority-fee-per-access <wei>] [--no-wait] [--private-key <path>]

# Republish the project's [web] assets without deploying an actor
cowboy deploy --web-only
```

`cowboy deploy` has two paths. The **project path** (no `--code`) is the composed pipeline: it builds the target, publishes an off-chain image if the target uses one, deploys the actor, funds it, and records the deployment under `.cowboy/deploy/` so later `cowboy actor` commands can name the target instead of an address. The **raw path** (`--code <file>`) signs one `DeployActor` over exactly the bytes in the file with no project, no environment binding, no image, and no recovery record.

## Behavior (project path)

1. Discover the project from the current directory and select the target: the one named, or the project's only actor.
2. Resolve the environment: `--env <name>` if given; otherwise the project's active environment; otherwise, on an interactive terminal, a prompt listing configured environments plus the built-ins `local`, `mesa`, and `canyon`. Non-interactive runs with no environment fail with `environment_required`. Passing `--rpc-url` together with `--env` adds a new named environment; it cannot repoint an existing one.
3. Fetch the chain id and open the deployment store for `<environment>/<target>` on that chain. If the target already has a recorded deployment, creating another actor requires `--new`: non-interactive runs are refused with `project_already_deployed`, and an interactive terminal asks first. (`cowboy actor update-offchain` updates the existing actor's off-chain image instead.)
4. Resolve the signing key: `--private-key`, `COWBOY_PRIVATE_KEY_FILE`, then `COWBOY_PRIVATE_KEY` win; otherwise the key file recorded by this target's previous deployment; otherwise normal [key auto-discovery](https://docs.cowboy.inc/cli-specs/key-auto-discovery.md). On an interactive terminal a missing key prompts for a path.
5. Resolve spending settings. `--fund` defaults to `1` CBY (or the amount remembered from this signer's previous deployment); on an interactive terminal with nothing remembered, a prompt asks. `--initial-escrow` defaults to 30 days of rent at the volume's size after its first upload (at least 0.01 CBY). `--max-spend` and `--initial-escrow` are never remembered and apply only to the run they are given on.
6. Print `Riding to <environment> · <target>`, then run the steps:
   * **Building application** — compile the actor artifact (and the off-chain image and proxy first, when the target uses off-chain functions).
   * **Checking public volumes and compute** (off-chain targets only) — verify declared volumes are public, the resource class exists, and the image's registration status. If the default funding is below one off-chain call's maximum escrow, the default is raised to that figure and reported; an explicit `--fund` below it is refused with `actor_funding_below_call_escrow`.
   * Print the wallet, its balance, the planned maximum outflow, and (for off-chain targets) the source files and packages that will be published publicly. Refuse if the outflow exceeds `--max-spend` or the wallet balance.
   * Record a new attempt (a random 128-bit id, used as the CREATE2 salt) and derive the actor address from the signer, the salt, and the artifact's code hash.
   * **Publishing image** (off-chain targets only) — upload the image to CBFS and register its digest.
   * **Deploying actor** — submit `DeployActor` and wait for a committed receipt.
   * **Funding actor** — submit `FundActor` for the funding amount, unless it is `0`.
7. Archive the attempt, record it as the target's latest deployment, and print `Yeehaw! <target> is live on <environment>` followed by the actor address, the previous address if the target was deployed before, and copyable `cowboy actor inspect <target>` and `cowboy actor call <target> --handler <name> ...` commands.

Every project-path transaction's cycles, cells, and access limits are estimated by the node; fee caps come from the node's current quote.

### Resuming an unfinished deployment

If a step fails after the attempt was recorded, the attempt is preserved and the CLI prints `Deployment incomplete. Attempt <id> is saved; retry cowboy deploy with unchanged source and settings.` Rerunning the same command reconciles the saved transactions instead of starting over (the step labels read `Reconciling image publication` / `Reconciling actor deployment`). A resume refuses if the source, image, signer, funding, escrow, or init parameters changed, or if `--max-spend` is lower than the cap the attempt was started with. If a deployment transaction committed *unsuccessfully*, the attempt is archived instead and the next `cowboy deploy` creates a fresh actor address.

## Flags

| Flag | Default | Description |
| - | - | - |
| `<target>` | Inferred when the project has one actor | Actor target to deploy |
| `--new` | `false` | Create another actor even when this target already has a deployment. The new actor gets a new address; the existing one remains active. Conflicts with `--code` |
| `--env` | Active project environment (prompt if none, interactive only) | Environment to select and remember for this project |
| `--rpc-url` | None | RPC for a *new* named environment; requires `--env`. Existing endpoints cannot be replaced |
| `--private-key` | Recorded deploy key, then auto-discovery | Existing wallet key file. Remembered locally, never copied into `cowboy.toml` |
| `--max-spend` | None (wallet balance is the bound) | Maximum wallet outflow in CBY including fees, image escrow, and funding |
| `--fund` | `1` CBY, raised to one call's escrow for off-chain actors; no default with `--code` | CBY to transfer to the new actor, within `--max-spend`. With `--code`, a `FundActor` follows the committed deploy. Conflicts with `--no-wait` |
| `--initial-escrow` | 30 days of rent at the volume's size, at least 0.01 CBY | CBY escrow (up to 9 decimals) for each volume the deploy must create |
| `--init-handler` | None (no atomic init) | Initialization handler to call in the deploy transaction |
| `--init-payload` | `{}` when `--init-handler` is set | JSON init payload or `@file`; requires `--init-handler`. An `@file` must resolve inside the current directory, is capped at 1 MiB, and is opened with `O_NOFOLLOW` on Unix |
| `--no-owner-funding` | absent (funded) | Either path. The deploy adds no owner-funding grant (see [`cowboy actor owner-funding`](https://docs.cowboy.inc/cli-specs/cowboy-actor#cowboy-actor-owner-funding)). A grant the signer made to the actor's address before deploying stays. Conflicts with `--owner-funding-cap` |
| `--owner-funding-cap` | none (no cap) | Either path. Cap, in CBY, on what the actor may draw from the signer's balance over the grant's life |
| `--manifest-json` | None | Either path. `ActorManifest` JSON file declaring the entitlements the actor holds |
| `--shard` | Deployer address prefix | Either path. Address group in 0..65535 (see below) |
| `--receipt-timeout` | `120` (range 1–900) | Seconds to wait for each committed transaction before preserving a retry |
| `--json` | `false` | Emit one versioned JSON result; never prompt. Progress goes to stderr |
| `--verbose` | `false` | Show image identity and every published source file |
| `--base-rootfs` | `COWBOY_OFFCHAIN_BASE_ROOTFS` | Advanced: unpacked base rootfs instead of automatic verified acquisition |
| `--expected-base-digest` | None | Advanced: require this base digest |
| `--cbfs-bin` | `cowboy cbfs` | Advanced: run this external CBFS helper instead of `cowboy cbfs` |
| `--web-only` | `false` | Republish the project's `[web]` assets to their volume without deploying an actor (a deploy publishes them too). Conflicts with `<target>`, `--code`, `--new`, `--fund`, `--init-handler`, and `--manifest-json` |

### Raw-path flags (`--code`)

These require `--code`; `--code` conflicts with `<target>`, `--max-spend`, and `--initial-escrow`.

| Flag | Default | Description |
| - | - | - |
| `--code` | — | Python source file to deploy as raw bytes |
| `--salt` / `-s` | empty | CREATE2 salt (hex, max 32 bytes) |
| `--routes` | None | Canonical CBOR CIP-15 routes table to install with the code (a project deploy installs the table its build lowers) |
| `--route-sponsorship` | None | CIP-11 sponsorship ceiling for the table's native runner routes; requires `--routes` |
| `--no-init` | `false` | Deploy without atomic init (already the default); conflicts with `--init-handler` |
| `--nonce` / `-n` | `0` (discover current nonce) | Account nonce |
| `--cycles-limit` | Maximum affordable | Cycles limit |
| `--cells-limit` | Maximum affordable | Cells limit |
| `--access-limit` | `512` | Access limit (store I/O operations) |
| `--max-fee-per-cycle` | Node suggestion | Max fee per cycle |
| `--max-fee-per-cell` | Node suggestion | Max fee per cell |
| `--max-fee-per-access` | Node suggestion | Max fee per access |
| `--max-priority-fee-per-access` | `0` | Max priority fee per access in wei |
| `--no-wait` | `false` | Submit without waiting for a committed receipt |

## Example

```bash theme={null}
$ cowboy deploy --env local

  Riding to local · demo

  ✓ Built application · actor runtime verified
    Wallet 0x7a3B...F92E · balance 100 CBY
    Spend up to 1.03 CBY · actor funding 1 CBY
  ✓ Actor deployment committed
  ✓ Actor funding committed

  🤠 Yeehaw! demo is live on local

  Actor    0xdef456...
  Inspect  cowboy actor inspect demo
  Call     cowboy actor call demo --handler main --payload-text '<text>'
```

Raw path:

```bash theme={null}
$ cowboy deploy --code actor.py --init-handler init
  Deployer address: 0x7a3B...F92E
  Current account nonce: 4
  Gas: ...
```

## Edge Cases

* Neither path runs an init handler unless `--init-handler` names one. On the raw path `--no-init` still refuses one explicitly and conflicts with `--init-handler`.
* `--max-spend` must be positive and at least `--fund`; the funding default counts toward it.
* `--initial-escrow`, `--fund`, and `--max-spend` accept up to 9 fractional digits.
* A different signer than the one recorded for the target does not inherit that record's funding or escrow settings.
* Under `--json`, an incomplete deployment reports `project_deploy_incomplete` with the attempt id and recorded transactions; an archived failure reports `project_deploy_failed` with the failing step and status.
* The raw path resolves the file, salt, manifest, and init arguments before any RPC client exists, so an unreadable file or an oversized salt is refused without a node.

The `--shard` option selects the actor address group (0..65535); omission inherits the deployer prefix and explicit zero selects group zero. Use the same selection with `cowboy actor address` to predict the address.


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