Skip to main content
This tutorial builds a price watcher. Every hour it fetches the price of Bitcoin, asks a model whether the move matters, and keeps the answer. At the end, it messages you the answer, here on Telegram. You need the cowboy CLI and uv. Everything up to the deploy runs on your machine and is free.

1. Create the project

Output

2. Write the actor

Replace actors/pricewatch/main.py with:
Here is what makes it an actor:
  • self.storage is the actor’s state. It’s still there on the next run, and anyone can read it.
  • Handlers are the methods the outside world can reach. @public lets anyone call one. @callable_by(OWNER) lets only you, the account that deployed the actor. question and record have no decorator, so only the actor’s own code can call them.
  • @every(HOUR) makes tick run every hour once start starts it. Nobody can call tick directly.
  • await runner.http(...) and await runner.llm(...) ask a runner, one of the machines that does work for actors, to fetch the page and ask the model. The handler pauses and continues when the answer arrives. The actor pays for each job from its own balance. page.data is the parsed JSON. This API refuses requests without a User-Agent.
  • runtime.emit_event adds an entry to the actor’s public log.
tick and check_now repeat the same three lines because an await has to sit in the handler itself. A helper method can’t await a job. A model’s answer is normally text. If its provider fails, the answer is an object with an error key instead of a failed job, so record checks for that. Actor code can’t open a connection, because every handler must give the same result wherever it runs. That’s why the fetch goes through a runner (Determinism).

3. Test it

Replace tests/test_pricewatch.py with:
Output
SimulatedChain runs the actor in memory. advance_block moves time forward in seconds and runs whatever comes due, and reply answers the job the actor is waiting on, so you can test both jobs without a network or a model. Testing actors covers the rest.

4. Deploy it

An actor can call a model by default, but it needs permission to reach the web, and the permission names the hosts it may reach. Put that in manifest.json. Step 6 needs the Telegram host, so it’s listed now:
If you haven’t created a wallet and claimed the credit, do that first (Quickstart). Then deploy:
Output
The deploy runs init and makes you the owner. It asks how much to move from your wallet to the actor’s balance, 1 CBY by default.
Money you send an actor stays with it unless its code can send it out. This one can’t, so send only what you want it to spend.

5. Watch it work

Ask it to check now, then read what it kept:
Output
Output
The call returns quickly, and the jobs run after it. Within a minute or so, actor state shows last_price and verdict. The model picks the wording, so your result can differ. If verdict stays null, the model provider failed, and actor logs shows price.no_verdict. Now start the schedule:
Output
Output
actor timers shows the next run, one hour away. From now on your laptop plays no part. Each hour adds a price.checked entry to actor logs. The actor runs for as long as its balance can pay. If it can’t pay for a run, the schedule ends. To keep it going, add money with cowboy actor fund pricewatch --amount 5 and call start again (Keep it funded). To stop it, call stop.

6. Have it message you

This step uses Telegram, but any service with a web API works the same way. Create a Telegram bot with BotFather and note your chat id. An actor’s state is public, so the bot’s token goes in the secret store, where the runner fills it into the request and the actor never sees it. Replace actors/pricewatch/main.py with this version. It adds the json import, the TELEGRAM_API constant and set_chat, and tick now ends with one more job:
Check it, and run the tests again:
Output
An actor’s code can’t change after deploy, so this is a new actor at a new address. Stop the old one, deploy this one, and give it the token and your chat id:
Output
Add the token, using the address the deploy printed. secrets add prints a link where you type it in your browser:
Output
Then set your chat and start the schedule:
Output
An hour after start, the first message arrives.

Next