Recurse SDK

Author, package, and deploy Recurse applications.

Installation

Python 3.14 or newer is required. Install Recurse from PyPI:

pip install recurse-sdk

This installs both the recurse command and the Python API. Check the installation:

recurse --help

Version 0.2.1 is required for account-funded runs on the current Engine. Version 0.2.0 submits a 900-second duration that the service no longer accepts. Upgrade the SDK before starting new runs. Version 0.2.3 restores the 512 MiB minimum. SDK 0.2.2 rejected requests below 768 MiB locally.

If you prefer uv, install the CLI as an isolated tool:

uv tool install recurse-sdk

Add the Python API to an application:

uv add recurse-sdk

Running or deploying an application also requires uv on your PATH to build its package.

The distribution ships two things:

• The recurse Python package: manifest validation, standards-based application packaging (recurse.build_bundle), and the runtime context tools use during a run (recurse.context).
• The recurse command: browser login, encrypted runtime-secret management, direct runs, MCP deployment, artifact retrieval, and billing.

Quickstart

An application is a directory with an agent.yaml manifest, a system prompt, a tool module, and a uv lockfile. See the runnable examples and authoring and deployment guide:

• examples/tiny-tuner — tune a classifier against held-out validation F1.
• examples/predictive-modeler — train classification, regression, and forecasting pipelines against task-specific quality constraints.
• examples/rna-fold-lab — design RNA sequences against an independent forward-fold oracle.
• examples/backpack-3d — write, render, visually critique, and revise a 3D backpack using Astra and complete Python modeling programs.
• examples/level-design — design puzzle-game levels against an independent solver: two runnable agents and one prompt-only example.

recurse login
recurse secret set github-token
recurse secret list
recurse run examples/tiny-tuner --inputs inputs.json --secret GITHUB_TOKEN=github-token
recurse deploy examples/tiny-tuner --as mcp --cpu 1 --memory-mib 1024 \
  --secret GITHUB_TOKEN=github-token
codex mcp add recurse -- recurse mcp serve <deployment-id>
claude mcp add recurse -- recurse mcp serve <deployment-id>

For Codex, apply the startup and tool timeout settings shown in the guide after adding the server.

To connect all published gallery apps through one server, use recurse mcp serve without a deployment ID. The shared connection exposes apps.<gallery-slug> tools; private deployments still use their individual IDs. Runs use the caller's wallet.

Tools API

Recurse SDK 0.2.5 adds catalog access, direct tool calls, publisher-only publication, and a separate local MCP bridge. Install or upgrade recurse-sdk to use these commands.

recurse login
recurse tools search
recurse tools inspect <tool-id>
recurse tools mcp serve

Python callers use recurse.ToolsClient.from_login() locally or supply an audience-scoped bearer to recurse.ToolsClient(access_token=...) on a server. Calls require the inspected tool and price versions, an idempotency key, and a maximum charge. See the Tools guide for invocation, publication, and authentication.

SDK 0.2.7 also accepts an individual Recurse Tools key from the account setup page. recurse tools login --key-stdin reads it from a pipe, verifies it and saves it in the operating-system keychain without opening a browser. Never pass a key as a command argument, environment variable or MCP configuration value. ToolsClient.from_login() and the Tools MCP bridge use the imported key and automatically refresh its one-hour Tools bearer.

After importing the key, connect Codex with:

codex mcp add recurse-tools -- recurse tools mcp serve

Give your agent the Tools instructions. It can discover APIs, build a private Python project and execute it through Recurse. The key setup guide shows a hidden-input import and TEST origins. recurse tools logout revokes only that imported key; ordinary recurse login and agent execution keep their existing behavior.

Recurse SDK 0.2.6 also prepares and executes customer-owned tools.yaml projects privately. Install or upgrade from PyPI as described above. These runs use compute billing and never publish a catalog entry:

recurse tools run path/to/app-tools --function calculate --inputs inputs.json \
  --idempotency-key <stable-request-key> --max-cost-micro-usd 200000

The cap includes preparation and execution. The CLI waits for a receipt; Python's client.run(...) returns after admission so callers can poll get_call themselves. See Private Tools runs for retry and cancellation details.

SDK 0.2.6 adds approved API discovery (recurse tools apis search / apis inspect) and per-function apis declarations for paid reads through treg. Its MCP bridge forwards all thirteen generic catalog, API discovery and private source operations. Remote source authoring requires standard bundle construction and the returned scoped HTTP upload capability. The company-updates example searches official company pages and fetches bounded excerpts using one Recurse wallet.

Documentation

• docs/guide.md — installation, authoring, runtime, login, deployment, local MCP access, and billing.
• docs/reference/api.md — generated API reference.
• docs/reference/manifest.md — generated agent.yaml reference.

Contributing

Run ./check.sh for formatting, lint, types, tests, generated-reference checks, and package builds. The SDK and examples must reach 100% statement and branch coverage. The RNA and backpack examples' tests and dependencies live under their own tests directories and use separate locked environments.

Install the same gate before committing:

uv tool install pre-commit
pre-commit install

Publishing

pyproject.toml sets readme = "README.md", so package builds embed this README as the PyPI description. Editing it on GitHub does not update an existing release: PyPI retains the metadata from that release's first upload. To publish a corrected description with the next SDK release:

1. Choose an unpublished version, update project.version in pyproject.toml, and run uv lock. Update the SDK version reported in src/_recurse_cli.py and its matching CLI tests. Also run uv lock --directory examples/rna-fold-lab/tests, uv lock --directory examples/backpack-3d/tests, and uv lock --directory examples/predictive-modeler/tests to refresh their local SDK dependency.
2. Run ./check.sh to validate the release and build its wheel and source distribution in dist/.
3. Inspect the wheel's .dist-info/METADATA and the source distribution's PKG-INFO. Their description must match the current README, with pip install recurse-sdk first and uv tool install recurse-sdk as an optional alternative.
4. With PyPI publishing access, upload only the two files for that version using uv publish dist/recurse_sdk-<version>-py3-none-any.whl dist/recurse_sdk-<version>.tar.gz, replacing <version> with the selected version.
5. Check the new release's description on PyPI and the default project page. In a fresh Python 3.14 environment outside this checkout, run pip install recurse-sdk, pip check, and recurse --help. Confirm pip show recurse-sdk reports the published version.

Version 0.1.0 retains its original description. Publish a new version to refresh the default project page; PyPI does not allow replacing previously uploaded files.

License

Licensed under the Apache License 2.0.