cowboy-actor-sdk, imported as cowboy_sdk, and every project from cowboy init already depends on it. The guides cover version 0.2.0.
Don’t confuse it with cowboy-sdk (import cowboy), a different library: the Python client an app uses to call deployed actors.
The shape of an actor
The main parts of an actor all show up in this small counter:Actor, and its handlers are the methods others can call. Each handler takes one payload, decoded for you, and its return value goes back to the caller. @public and @callable_by(OWNER) say who may call it: anyone, or only the actor’s owner. A method without one of these can’t be called from outside.
init runs once, when the actor is deployed, and gets the raw bytes the deploy passes. From then on, self.storage holds the actor’s state, which persists between calls. A read gives you a copy, so assign a changed list or dict back.
Inside a handler, self.sender tells you who sent the current call, as an Address. runtime gives you more of what Cowboy offers, such as events, time, timers and payments. And a handler that raises changes nothing, which is how increment refuses a bad number.
Guides
Each guide covers one thing an actor does.Handle money
Its balance, getting paid, and paying others
Schedule work
Run a handler later, or every hour
Keep files
Where an actor’s files live, and how its runner jobs and off-chain functions use them
Call models, the web and tools
await runner.llm, runner.http and runner.mcp, with secretsCall other actors
Calls, messages and events between actors
Keep an actor safe
Permissions, limits, pausing and bounded work
Follow the sandbox rules
Imports, time, randomness and numbers
Look up runtime functions
Every
runtime function in one line each