Skip to main content

​
Synopsis

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. 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

​
Raw-path flags (--code)

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

​
Example

Raw path:

​
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.