Skip to main content

​
Overview

The Cowboy Store lists actors and tools that other builders publish. Hiring one gives you your own instance of it on chain. This page goes from a fresh machine to a hired actor that has answered one request, on Cowboy Cloud, the network that is open to the public internet (Networks). What you’ll do:
  • Create a wallet and claim its one-time new-account credit
  • Browse the Store and inspect a listing
  • Review a listing’s setup plan, then hire it
  • Call the hired actor and read its answer
The walkthrough hires Content Moderator, a free listing that asks an LLM whether a piece of text breaks a moderation policy. The same steps work for any listing.

​
Prerequisites

  • The cowboy CLI is installed. Use the latest release: the network rejects transactions from an older CLI (see Troubleshooting).
  • A Google account, for the one-time credit that pays your first fees.
  • You don’t need a project or uv to hire. cowboy init is only for writing your own actors.

​
1. Create and fund a wallet

wallet create stores the key in ~/.cowboy/keys/default. COWBOY_ENV=cloud selects Cloud for every command that follows; --env cloud does the same for one command. credit claim opens a page on cloud.cowboy.inc for your wallet. Sign in there with Google. Each Google account and each wallet can claim the credit once (currently 50 CBY). With no browser on this machine (an AI agent, a server, CI), or with --device, it prints a short code and a link instead, then waits:
If you are an AI agent, give the link and the code to your human. If your tool shows a command’s output only after it exits, run credit claim in the background so you can read the code while it waits, or add --no-wait to print the code and exit. Your human opens the link on any device, checks that the wallet shown is yours, and approves with Google. The CLI then prints the new balance. A refused, expired or already-used claim ends with credit_claim_denied or credit_claim_expired and its reason. Later, check the balance with:
Cloud has no faucet, so cowboy faucet request returns HTTP 404 there.

​
2. Browse the Store

Connect the CLI to Cloud’s General Store once:
Then browse:
Each result shows a name, a listing reference (listing/0x…/N) and a description. Inspect one:
show gives the price, whether people and agents can hire the listing, and any setup note, such as needing an API key or an LLM-capable runner. Copy listing references from store search rather than from this page.

​
3. Review the setup plan

Hiring is a purchase plus a setup: setup deploys your instance and funds it. Review both before you sign anything:
The plan reports:
  • the listing version
  • the recipe_hash, which identifies the exact setup you are approving
  • max_setup_fee, a cap on the fees setup may spend, in base units (1 CBY = 1,000,000,000). The --max-setup-fee flag takes whole CBY, so 1000000000 in the plan is --max-setup-fee 1
  • the recipe’s public inputs and their defaults
--plan signs nothing. It says requires_committed_hire because setup is bound to a specific hire, which doesn’t exist until you buy. The steps and recipe hash you approve here are the ones setup runs.

​
4. Hire it

In a terminal, run the hire without --plan. The CLI shows the plan and asks you to confirm:
Without a terminal, for example in a script or an AI agent, the CLI never prompts, so you approve the plan by passing it back. Put the recipe’s public inputs in a JSON file, using the defaults from the plan:
The CLI switches to non-interactive mode automatically when it detects an AI agent, and also when COWBOY_NON_INTERACTIVE=1. If a flag is missing it refuses and names the flags it needs; add --json to get that as a structured hint. A successful hire ends with:
The Entrypoint is the address of your instance. Installation: installed means setup finished. If setup stops partway, run the Continue setup: command it prints instead of hiring again, so you don’t pay twice. CLI 0.0.47 also prints that line after a finished setup; there you can ignore it.

​
5. Call it

An actor’s handlers are in its source:
Content Moderator exposes moderate_content, which takes content and content_type. If your text contains an apostrophe, pass the JSON with a heredoc (--payload-json "$(cat <<'EOF' … EOF)") instead of single quotes:
The call commits in about a second. The LLM work runs off chain, so the answer arrives a few blocks later. Read it from the actor’s state:
The LLM picks category, severity and the wording, so your result can differ from this one. If last_case still says "status": "idle", the runner hasn’t answered yet. If it stays idle for more than a minute, check cowboy actor logs $A for a job failure such as E1607, which means no runner on the network is eligible for one of the actor’s off-chain jobs. Content Moderator runs two: the LLM call, then a container job that checks the LLM’s answer. Either can be the one that fails. The actor call itself still reports success, because the LLM job runs after the call commits.

​
Other networks

The steps are the same on a team or private network whose RPC and Store you’ve been given. Register both once, then use the network by name:
A Store URL must be HTTPS, or plain HTTP on a loopback address. On networks that have a faucet, use cowboy faucet request instead of credit claim.

​
Troubleshooting

The RPC answered {"code":2007,"message":"TxInvalidInstruction"}. The network’s transaction format is newer than your CLI, so every write fails, including transfers and hires. Install the latest release from Install the CLI and run the command again.
Your CLI doesn’t understand the Store’s current setup format. Upgrade the CLI the same way.
You ran a hire without a terminal. Run --plan first, then pass --yes --version N --recipe-hash HASH --max-setup-fee CBY, plus --inputs FILE if the recipe has inputs (step 4).
Your CLI predates the built-in Store connection. Upgrade it. Or connect a Store explicitly: cowboy store add cloud --url https://cloud.cowboy.inc and cowboy store use cloud.
The listing is published, but the Store isn’t accepting hires of that kind yet. Pick another listing.
Some listings wrap third-party services and ask for your own vendor key during setup. store show and --plan list each secret a listing needs before you buy.