Skip to main content
By the end of this page you’ll have Social Pulse running on Cloud and submitted to the General Store as a free listing. Social Pulse tracks public profiles on Bluesky: ask it to refresh a handle, and it records that account’s followers, follows and posts, keeping the last 10 snapshots so a hirer can see the trend. Every file you write is on this page, and the submission package is on Package and submit. To follow along, install the CLI. The steps from deploy onward need a funded wallet.

1. Shape it

Before writing code, split the product into the parts Cowboy runs: An actor can’t reach the network itself, so it hands each request to a runner, a machine that does work for actors, and waits for the answer. Bring existing code has more on making this split.

2. Create the project

Output
--env cloud makes Cloud this project’s network, so later commands don’t need it.

3. Write the actor

Replace actors/social_pulse/main.py with:
refresh does the work. It checks the handle, sends one request to Bluesky through a runner with await runner.http(...), and stores the snapshot when the answer comes back. The other three handlers only read what refresh stored. Three choices here matter once strangers can call it:
  • @limit(per_caller=20, every=HOUR, pending=2) caps how often one caller can refresh. The actor pays for every runner job, so without a limit one caller could spend its balance.
  • MAX_HANDLES and MAX_SNAPSHOTS bound how much it stores, because the actor pays rent on its state. refresh checks the handle count again when the answer comes back, since other refreshes can finish while it waits.
  • Errors come back as answers. A failed request, or a handle Bluesky doesn’t know, returns {"handle": ..., "error": ...} and stores nothing.
Call models, the web and tools explains how an await waits for a runner.

4. Test it

The tests answer the Bluesky request themselves, so they need no network. Replace tests/test_social_pulse.py with:
Output
chain.reply(...) answers the last runner job, and chain.fail(...) fails it, so each test can play Bluesky’s part.

5. Try it on your machine

cowboy run runs one handler on your machine. It can’t reach Bluesky, so fail the request and see what a caller gets back:
Output
The first line is what refresh returned. The run also prints the actor’s state, which still has an empty history.

6. Deploy it with web access

On Cloud, an actor’s web requests need the http.fetch permission, which you ask for at deploy in a manifest. Its allowlist_domains names the hosts the actor may reach. Social Pulse needs only Bluesky’s public API. Save this as manifest.json in the project:
You can’t change the list after the deploy, and a request to any other host is refused. Then deploy:
Output
The deploy moves a little money from your wallet to the actor, so it can pay for its runner jobs. --max-spend-usd is the most the deploy may take from your wallet, that money included, and if the deploy would cost more it stops before submitting anything. When the actor’s own balance runs short, your wallet backs it up. --owner-funding-cap-usd caps what the actor may draw from your wallet over its life. To have it pay only from its own balance, pass --no-owner-funding instead (Keep it funded). Both caps are ceilings, not money set aside. What your wallet holds is the real limit: nothing can spend more than its balance, whatever the caps say.

7. Take a snapshot

Ask for a refresh, then read the actor’s state:
Output
Output (abridged)
The request takes a moment. A call reports that it went through, not what the handler returned, so read the result from the state. Reading state is free. Social Pulse works. The rest of this page lists it.

8. Publish the source

Reviewers read the exact source you submit, and hirers can too, so it goes in a public storage volume. Storage commands sign with your wallet’s key file, keep working files that include a key able to write to your volumes, and record what each transaction may cost. Make a private folder for those files, outside the project:
Then create a volume for this version and upload the project’s files:
--wallet-key is your wallet’s key file, which cowboy wallet create keeps at ~/.cowboy/keys/default. --spend-limit-wei caps the fees these storage transactions may pay in total, here 1 CBY, and the ledger file records each one. volume create also moves a small storage deposit from your wallet into the volume. Publish the source explains each flag, and where else a key file can go.
Uploads to Cloud storage can fail from outside the Cowboy network. Cloud’s storage relays aren’t publicly reachable yet, so put can time out, or stop with an error that asks for a trusted checkpoint. If it does, stop here and report the error to Cowboy. Don’t go on to declare the actor: a declaration against a volume your files never reached lists empty source, and it can’t be pointed at other files later.
Then read back the volume’s full id and its root, a hash of everything in it. The next steps use both:
Output
A root of all zeros means nothing reached the volume, so stop as above. cowboy volume list --env cloud --private-key ~/.cowboy/keys/default lists every volume your wallet owns, with its id. Each version you list gets its own volume, so don’t change this one after you submit it. When the listing is submitted, delete ~/.cbfs-social-pulse: it holds a key that can write to your volumes.

9. Declare it in the Store

A declaration is the Store’s record of your actor: its address, the source behind it, and its terms. Pick a random salt, which makes the declaration’s id unique:
Then declare the actor with the salt, the actor address deploy printed, your wallet address, and the volume id and root from step 8. cowboy wallet address --private-key ~/.cowboy/keys/default prints your wallet address, which goes in --split:
Output
--term free sets the price. --split says who gets paid, in hundredths of a percent, so 10000 is all of it to you (Pricing). --human-hireable and --agent-hireable say that people and other agents can both hire it.

10. Let the General Store sell it

A grant lets a store sell your declaration. The General Store’s id on Cloud is 1:
Output
--lease-epoch-blocks is required, but it matters only for private code (CIP-33). Check that the grant landed, and note its id:
Output
Coming soon: store declare and store grant waiting for their transaction to commit and reporting the result. Until then, check with cowboy store get-declaration and cowboy store get-grant.

11. Submit it

The submission package ties it together: the declaration, the source, the grant, what the actor does, and its price. Save the complete submission.json from Package and submit in the project and fill in your own ids. Package and submit explains each field.
Output
Submitting needs no login: your wallet signs it. Follow its progress with:
Output
Queued means the automated checks passed and it’s waiting for a person to review it. Review states lists the rest. Approval lists it in the General Store as a free listing.

Use an API that needs a key

Most social networks want an API key. The actor stays the same apart from the request: mark where the key goes with runner.secret, and the runner fills it in when it makes the call. The key never appears in the actor’s code, state or calls, which are all public. Here is the YouTube version, which puts the key in the URL:
The X API takes its key in a header instead. Only the request changes:
To ship either one, add its host to allowlist_domains (www.googleapis.com or api.x.com), deploy, and add the key for the deployed actor. Call an API with a key covers those steps, and whose key a listed actor uses.

Next