Recurse docs / 01
What is Recurse?
Recurse gives your external agent eligible APIs and a place to run private Python tools. Your agent writes the code, combines APIs and revises the tool when you ask for a change. One Recurse wallet pays for API requests and execution. You do not procure separate provider keys or wallets for eligible operations.
Start at Setup, or choose an example. Sign in with Google and continue the work in your own agent. New accounts include $1 starting credit. Setup and discovery do not execute a paid task.
Your agent builds it; Recurse runs it
| Part | Responsibility |
|---|---|
| You | Choose a task, supply missing inputs and approve a total spending allowance. |
| Your external agent | Inspect live APIs, write Python and revise it using results and evidence. |
| Private Tools service | Prepare and execute the registered function in isolation, broker approved API access and retain its receipt. |
| Wallet and Activity | Show authoritative available/reserved funds, preparation and execution charges, and retained results. |
The current verified setup is Codex. Generic setup has three steps: agent key, setup, initiate. An example has two: agent key, setup and start. Its task follows you through sign-in and funding. Private tools remain yours; running one does not publish it for everyone.
Two execution paths
| Path | Files and use |
|---|---|
| Private Python tools | tools.yaml, Python, pyproject.toml, uv.lock; direct function execution with no hosted prompt or model loop. |
| Hosted Recurse agents | agent.yaml, prompt, Python tools and verifiers; the existing hosted agent run/deploy workflow. |
Keep the manifests separate. Begin with Installation and access and Run private Python. The full existing Hosted Recurse agents guide remains available, including prompts, harness behavior, SDK and MCP deployment.
Live contracts and evidence
Inspect schemas, provider units, price ceilings and eligibility before execution. Some catalog operations require a customer's own connected account or private-resource ownership; those remain unavailable where indicated. A listed API is not automatic permission for a side effect.
The gallery contains ten locally tested references and 240 specifications with build instructions. Artwork does not establish live execution. Your agent asks for missing inputs and a cap, then reads the actual receipt before claiming success. API costs pass through at 1× and compute uses 4×; source preparation is separately billable. See Tools costs and limits.