Quickstart

Overview

This guide walks through the fastest path from a working cowboy CLI to a deployed Python actor on the hosted Cowboy devnet. You will create a normal project directory, initialize a devnet wallet, scaffold a starter actor, deploy it, call it, and inspect the result. What you’ll learn:

How to scaffold a project and manage a wallet
How to deploy and execute a Python actor
Where to go next when you want to customize actor behavior

Prerequisites

The cowboy CLI is installed and available on your PATH
Optional: lasso is installed if you prefer the interactive console

Verify the CLI:

cowboy version

If you use Lasso, verify it separately:

lasso --version

1. Create a Project Directory

Start from any directory where you keep projects:

mkdir my-cowboy-app
cd my-cowboy-app

2. Initialize Devnet Config

cowboy init dev

This creates .cowboy/ with a fresh secp256k1 keypair and a config pointing at the hosted Mesa devnet. The devnet faucet funds the generated wallet when available.

my-cowboy-app/
├── .cowboy/
│   ├── keys/dev       # PEM-encoded secp256k1 private key
│   └── config.json    # active network, RPC URL
└── ...

Verify the network and wallet:

cowboy status
cowboy wallet address
cowboy wallet balance

3. Scaffold the Hello Actor

cowboy actor new hello

This creates actors/hello/main.py, a tiny SDK counter actor. The generated file includes durable actor storage, an init handler, public handlers, and module-level dispatch functions:

# actors/hello/main.py
from cowboy_sdk import actor, public


@actor
class CounterActor:
    def init(self, payload=None):
        self.storage["__name__"] = "Counter"
        self.storage["counter"] = 0

    @public
    def increment(self, payload=None):
        count = (self.storage.get("counter") or 0) + 1
        self.storage["counter"] = count
        return str(count).encode()

    @public
    def get_count(self, payload=None):
        count = self.storage.get("counter") or 0
        return str(count).encode()

The generated file also includes the wrapper functions the PVM calls by handler name. Keep those wrappers in place when you edit the actor.

4. Deploy the Hello Actor

Deploy it:

cowboy actor deploy --code actors/hello/main.py --salt 0x01

The CLI prints a transaction hash and a deterministic CREATE2-style actor address:

Deploying actor...
  Code file: actors/hello/main.py
  Salt: 0x01
  Nonce: 0
  Atomic init: init (payload: 2 bytes)
  Transaction hash: 0xabc123...
  Actor address: 0xdef456...

✓ Actor deployment transaction submitted successfully
  Actor address: 0xdef456...
  Waiting for block confirmation...
✓ Actor deployed successfully!
  Code hash: 0x789abc...
  Balance: 0
  Nonce: 0

Use the printed Actor address in the commands below. Compute that address ahead of time if you want:

cowboy wallet address
cowboy actor address --code actors/hello/main.py --creator <YOUR_ADDR> --salt 0x01

5. Call the Actor

Execute a handler:

cowboy actor execute --actor <ACTOR_ADDR> --handler increment --payload 0x
cowboy actor execute --actor <ACTOR_ADDR> --handler get_count --payload 0x

Inspect state and logs:

cowboy actor get --address <ACTOR_ADDR>
cowboy actor logs --address <ACTOR_ADDR>

6. Next Steps

Minimal Actor Walkthrough

Understand the actor programming model

CLI Reference

Every cowboy subcommand, flags, and semantics

End-to-End Example

Study source-checkout examples when you want larger actor patterns

Fee Model

Learn how Cycles and Cells are metered and priced

Where to Find Things

Your project config: .cowboy/config.json
Your devnet key: .cowboy/keys/dev
Your starter actor: actors/hello/main.py
CLI reference: CLI Developer Experience
SDK tutorial: Your First Actor

Troubleshooting

'cowboy: command not found'

Install the cowboy CLI using the distribution method provided by the Cowboy team, then open a new terminal and run cowboy version.

'connection refused' on RPC

Run cowboy status to see which RPC URL the CLI is using. If you intended to use the hosted devnet, re-run cowboy init dev or pass --rpc-url explicitly. If you are intentionally using a local validator, make sure that validator is running before using cowboy init local.

Actor deploy fails with 'insufficient gas'

The default cycle/cell limits are conservative. For larger actors, pass --cycles-limit and --cells-limit — see cowboy actor.

Start Here

Build

How Cowboy Works

Reference

Overview

Prerequisites

1. Create a Project Directory

2. Initialize Devnet Config

3. Scaffold the Hello Actor

4. Deploy the Hello Actor

5. Call the Actor

6. Next Steps

Minimal Actor Walkthrough

CLI Reference

End-to-End Example

Fee Model

Where to Find Things

Troubleshooting

​Overview

​Prerequisites

​1. Create a Project Directory

​2. Initialize Devnet Config

​3. Scaffold the Hello Actor

​4. Deploy the Hello Actor

​5. Call the Actor

​6. Next Steps

Minimal Actor Walkthrough

CLI Reference

End-to-End Example

Fee Model

​Where to Find Things

​Troubleshooting

Overview

Prerequisites

1. Create a Project Directory

2. Initialize Devnet Config

3. Scaffold the Hello Actor

4. Deploy the Hello Actor

5. Call the Actor

6. Next Steps

Where to Find Things

Troubleshooting