Skip to main content

​
Overview

This guide walks through the fastest path from zero to a deployed Python actor on a local Cowboy devnet. You’ll bring up a validator + runner with Docker, point the cowboy CLI at it, and deploy the reference hello actor. What you’ll learn:
  • How to run a local Cowboy network
  • How to scaffold a project and manage a wallet
  • How to deploy and execute a Python actor
  • Where the real examples and SDK live

​
Prerequisites

  • Rust 1.89+ — install via rustup
  • Docker (for the local multi-node devnet)
  • Node.js 18+ (optional, for the Lasso console)
Everything below assumes you’re at the root of the monorepo (cowboy/). If you need to orient yourself first, see Repository Layout.

​
1. Start a Local Devnet

The docker/ directory has a Compose stack that runs one validator and one runner: 
cd docker
cp .env.example .env
docker compose up --build
When the stack is up, the validator exposes JSON-RPC at http://localhost:4000 and Prometheus metrics at http://localhost:3001. For a larger network: 
./cowboy.sh up --validators 4 --runners 2 --build
./cowboy.sh logs
./cowboy.sh down

​
2. Build the CLI

In another terminal, build the cowboy binary from the node/ workspace: 
cd node
cargo build --release --bin cowboy
# Binary is at: node/target/release/cowboy
Optionally add it to your PATH: 
export PATH="$PWD/target/release:$PATH"

​
3. Scaffold a Project

From wherever you’d like your project to live: 
cowboy init local
This creates a .cowboy/ directory with a fresh secp256k1 keypair and a config pointing at http://localhost:4000, plus an actors/ directory with starter templates: 
my-project/
├── .cowboy/
│   ├── keys/local          # PEM-encoded secp256k1 private key
│   └── config.json         # active network, RPC URL
├── actors/
│   ├── hello/main.py
│   └── feed-subscriber/main.py
└── cowboy.toml
The local faucet auto-funds the generated wallet. Verify: 
cowboy wallet balance
cowboy account info

​
4. Deploy the Hello Actor

The starter hello actor is a tiny counter: 
# actors/hello/main.py
class Actor:
    """A Cowboy actor deployed on-chain."""

    def __init__(self):
        self.counter = 0

    def increment(self):
        self.counter += 1
        return self.counter

    def get_count(self):
        return self.counter
Deploy it: 
cowboy actor deploy --code actors/hello/main.py --salt my-hello
You’ll get a transaction hash and a deterministic CREATE2-style actor address. Compute that address ahead of time if you want: 
cowboy actor address --code actors/hello/main.py --creator <YOUR_ADDR> --salt my-hello

​
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 node/examples/llm_chat/ — an SDK-based actor that calls a runner

Fee Model

Learn how Cycles and Cells are metered and priced

​
Where to Find Things

  • Starter actors: actors/hello/, actors/feed-subscriber/
  • Worked examples: node/examples/llm_chat/, node/examples/ring-demo/, node/examples/token/
  • Python SDK: node/pvm/Lib/cowboy_sdk/ (CIP-6 — @actor, runner.continuation, CowboyModel, …)
  • Lasso console: lasso/ — an interactive React/Ink wrapper over the CLI

​
Troubleshooting

Add node/target/release/ to your PATH, or invoke the binary directly: ./node/target/release/cowboy ….
Verify the Docker stack is up (docker ps) and that port 4000 is mapped. Check docker logs for validator errors. Re-run cowboy init local if your .cowboy/config.json points somewhere else.
The default cycle/cell limits are conservative. For larger actors, pass --cycles-limit and --cells-limit — see cowboy actor.