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
Replaceactors/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_HANDLESandMAX_SNAPSHOTSbound how much it stores, because the actor pays rent on its state.refreshchecks 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.
await waits for a runner.
4. Test it
The tests answer the Bluesky request themselves, so they need no network. Replacetests/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
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 thehttp.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:
Output
--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)
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:--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.
Then read back the volume’s full id and its root, a hash of everything in it. The next steps use both:
Output
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: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 is1:
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 completesubmission.json from Package and submit in the project and fill in your own ids. Package and submit explains each field.
Output
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 withrunner.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:
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.