How Recurse
works.

Your agent builds the tool.
Recurse gives it a place to run.

Bring your coding agent. Give it a task. It writes Python, combines eligible APIs, and runs the work privately through your Recurse account.

Follow the journey

Looking for hosted Agents? Jump to the advanced guide

Your agentUnderstands the task
Writes & revises Pythonyour computer

Code + inputsResults + receipts

Recurse

Private Python runtimeTrusted API accessOne wallet

Exa

Firecrawl

DataForSEOEligible APIs

Your agent plans. Recurse executes. APIs supply the data.

Connect the agent
you already use.

Sign in with Google, open your wallet, and create an access key for your agent. New accounts start with $1 credit; add funds when needed.

Copy the setup message into your coding agent. It loads the Recurse skill, imports the key into your operating-system keychain, and connects the Recurse Tools MCP bridge.

The agent needs local file creation and scoped HTTP upload. Setup and API discovery do not run a paid task.

Set up your agent

Your Recurse account

WalletAgent access key

Setup message

Your coding agentMCP

Recurse skill loaded

Key saved in OS keychain

API discovery connected

What would you like to build?

Connect once. Continue the task in your own agent.

Find the APIs.
Read the fine print.

Tell your agent what you want to accomplish, or choose an example. It searches the live API catalog and inspects the endpoints it needs before writing the tool.

Each endpoint has its own inputs, response schema, execution eligibility and price ceiling. Your agent works from those contracts, then chooses how to combine the results.

Eligible calls use Recurse’s provider access and your wallet. Operations requiring customer-owned connections remain unavailable where indicated. Actions that change something need your explicit authorization.

Explore example tasks

Find recent company newsapis_search

ExaInspect endpoint

apis_get → exa.web.search

Inputs: Native request schema
Response: Data your Python can use
Access: Execution eligibility
Price: Current rate + cost ceiling

The live catalog supplies the contract for each API.

A task becomes
a Python tool.

Your agent writes a small project: Python for the work, tools.yaml for function inputs, outputs and allowed API IDs, plus a package definition and locked dependencies.

Python can call the declared APIs, transform their data and return JSON. A compute-only tool can run without calling any API.

Your external agent supplies the reasoning and revisions. A private Tools run executes the function directly, with no added prompt, hosted model or agent loop.

Read the Tools manifest

company-news/

tools.yamlFunctions, schemas, allowed API IDs

tools.pyYour Python logic

pyproject.tomlPackage + dependencies

uv.lockExact dependency versions

tools.py · illustrative helper call

from recurse_apis import call

def research(query: str) -> dict:
    result = call(
        "exa.web.search",
        {"query": query},
    )
    return {"evidence": result}

One small Python project. API arguments follow the inspected schema.

Approve the budget.
Run it privately.

Before chargeable work, agree a total allowance with your agent. The cap covers source preparation, API requests and execution. Your wallet balance alone is not permission to spend it.

The SDK packages and uploads the source. Recurse prepares the private environment, freezes its API contracts and pricing, then runs the registered function with your inputs.

Preparation is a separately charged phase and can cost money even if it fails. Private execution does not publish your tool in the public catalog.

See the complete run flow

Your approved allowancePreparation + APIs + execution

PrepareBuild private source

ExecuteRun your function

recurse tools run ./company-news 
  --function research 
  --inputs inputs.json 
  --idempotency-key REQUEST_KEY 
  --max-cost-micro-usd APPROVED_CAP

A cap authorizes spending up to that amount; it is not a price quote.

API access, without
keys in your code.

Your Python runs in an isolated sandbox. The recurse_apis helper sends its declared API requests to the trusted service, which handles provider credentials, transport and metering.

The source receives no provider keys and no unrestricted network access. API calls are available inside the registered function during execution, after preparation has completed.

One execution supports up to 20 sequential API requests. An unresolved request must be resolved before another paid request can start.

Check access and execution limits

Private sandbox

Your Pythonrecurse_apis.call(...)

No provider keys or unrestricted network access

Declared API requests

Trusted serviceCredentials · transport · metering

Exa

Firecrawl

Provider credentials stay outside the executing source.

Keep the result.
Improve the tool.

Your agent receives a call receipt and follows it to the result. Open Activity to inspect preparation and execution, including errors, reservations and settled charges.

If a response is lost, your agent recovers the original request with the same source, function, inputs, request key and cap. A new request key starts new work. Failed or cancelled Python may still have incurred API costs.

Ask your agent to revise the code or reuse it with new inputs. Reusing the same prepared version avoids its original preparation charge. Results normally remain available for 24 hours; prepared images for seven days.

What if a run is interrupted?

Cancellation is a request. Follow the receipt to confirm that execution stopped and billing settled. Pending or uncertain provider costs remain reserved until reconciliation.

Replaying an expired result recovers its receipt, not its content. Agree another allowance before starting a new paid execution.

Understand results and recovery

Stored call receipt

call_idyour request identity

Execution: Status, result or error
Billing: Reserved or settled cost
Preparation: Its own receipt

Read → revise → reuse

Your agentAccount activity

Follow the original receipt to recover a request without duplicating it.

One wallet.
A visible cost for each run.

Settled provider cost passes through at 1×. Preparation and execution compute are charged at 4× their cost basis.

Current API rates and ceilings come from the catalog. Your approved cap is an allowance; receipts record what was actually charged.

Tools pricing and limits

Each private execution is bounded.

Input: 64 KiB JSON
Result: 256 KiB JSON
Execution time: 5 minutes
API requests: 20 sequential

Large media and asynchronous jobs must fit these limits. Follow the original job’s receipt before submitting new work.

Start with a task you care about.

Your agent can take it from there.

Connect your agent

Advanced: build a hosted Agent.

Some tasks benefit from an agent that explores alternatives, measures them and tries again. With Recurse Agents, your coding agent authors an agent.yaml project with a prompt, Python tools and verifiers. Recurse hosts the model and the tool loop for each run.

The hosted agent uses tool results and verifier feedback to revise candidates within a run. Your coding agent improves the project between runs. Use recurse run to test it, then deploy a reusable agent through MCP. Existing deployments continue to work.

The SDK walkthrough, manifest, runtime secrets and pricing below describe this separate workflow. Private Tools use tools.yaml, your external agent’s model and the limits explained above; the Tools API helper is not automatically supplied to hosted Agents.

Read the hosted Agents guide Get the Agents skill Explore the manifest

Hosted Agents: from a request to an app.

This retained example shows the separate Recurse Agents deployment workflow. Private Tools runs do not require an agent prompt or published app.

Build the project
The coding agent reads the Recurse skill, writes instructions and Python tools, and tests the app on sample inputs.
Deploy to Recurse
It uses the CLI to package and deploy the project. Recurse provides the runtime for the agent and its tools.
Connect through MCP
The agent connects the deployment to your MCP client. You can then ask the client to use your app.

Read the deployment guide

codex - ./image-optimizer

Build an agent app that makes product images smaller while preserving visual quality.

I’ll use

Recurse. I’ll build the agent, deploy it there, and connect it through MCP.

Write(prompt.md)Writing…

Write(agent.yaml)3 files written

The app is ready. Deploying it now.

Bash(recurse deploy ./image-optimizer --as mcp)Running…

Bash(recurse deploy ./image-optimizer --as mcp)deployment: mcp_demo

I’ll add it to Codex through MCP.

Bash(codex mcp add image-optimizer -- recurse mcp serve mcp_demo)Running…

Bash(codex mcp add image-optimizer -- recurse mcp serve mcp_demo)Added global MCP server 'image-optimizer'.

Deployed on

Recurse and connected to Codex.

Inside a hosted agent project.

Your coding agent handles the setup. Here’s a look at the config file that brings the project together.

agent.yaml · representative excerpt01 / 05

apiVersion: recurse.run/v1alpha1
kind: Agent
agent:
  prompt: prompt.md
inputs:
  type: object
  properties:
    query: {type: string}
    speedup:
      type: number
      default: 2
    task:
      type: string
      default: Optimize {{ input.query }}.
outputs:
  type: object
  required: [result]
  properties:
    result: {type: string}
tools:
  source: tools.py
  built_in: true
  register:
    search: ~
    verify: ~

01File format

The first two lines identify the config format and version.

02Define the job

The prompt file contains the agent’s instructions.

03What you send in

Describe the information the agent needs, with defaults for optional values.

04What comes back

Set the result format. Recurse checks that successful runs return values in that format.

05Tools it can use

List the Python functions the agent can call, alongside Recurse’s built-in tools.

Get started

Legacy Agents setup: deploy your own agent with the CLI. For private Tools, use the Setup page.

Use the CLI

01 Install

pip install recurse-sdk
02 Deploy

recurse deploy . --as mcp
03 Run

recurse run . --inputs sample.json

Run from your agent project. Read the docs

Try the image optimizer

Find the smallest image file that still meets your quality target.

Download agent project

Or build it with your coding agent

Read https://recurse.run/agents/SKILL.md. Build an image optimizer with encoding and quality tools. Test it, deploy it as an MCP, and help me connect it to my coding agent.

Integrate your agents

Save your API key. Use it in your app.

Save your key
Paste and confirm it in the hidden prompt.
Shell
```
recurse secret set github
```
Connect it to your app
Deploy with the secret attached.
Shell
```
recurse deploy . --as mcp \
  --secret GITHUB_TOKEN=github
```

Recurse loads the key when your tools run.

Read the secrets guide

From an idea to a working app.

Write the instructions and tools, test them on a sample task, and deploy the app as an MCP.

1. Build it

Tell your coding agent what you want to build. It writes the instructions, Python tools and project files.

image-optimizer/
├── agent.yaml
├── prompt.md
├── tools.py
├── pyproject.toml
└── uv.lock

2. Try it out

Run the agent on a sample task and check the result. For the image optimizer, check that the smaller image still looks good.

recurse run . --inputs sample.json

3. Deploy it

Recurse hosts the agent and makes it available through MCP. Choose more CPU or memory if your app needs it.

recurse deploy ./image-optimizer \
  --as mcp \
  --cpu 2 \
  --memory-mib 2048

Read the documentation

Pay for what you use.

Legacy Agents pricing. Private Tools use 1× provider cost and 4× compute; see the Tools setup guide.

Model calls

0% token markup

We don’t charge any markup on input or output tokens.

Supported models: GPT-5.6 (Luna, Terra, Sol) and GPT-6 (Astra, Luna, Sol).

Secure execution

$0.013 / minute

Approximate compute rate at default resources for your agent and its tools. Only active requests are billed.

Non-preemptible direct runs have 3× CPU and memory charges. Model calls and other charges stay at their normal rates. Costs and limits

How Recurse works.

Connect the agent you already use.

Find the APIs. Read the fine print.

A task becomes a Python tool.

Approve the budget. Run it privately.

API access, without keys in your code.

Keep the result. Improve the tool.

One wallet. A visible cost for each run.