SDKs

Use Macrofold from your application to manage workspaces, start cloud agents, and stream their progress. Every SDK uses the same API contract, permissions, and resource model on Macrofold Cloud and self-hosted deployments. Start with the API quickstart or coding-agent setup prompt.

Choose your language

Each guide starts with installation from source. Set MACROFOLD_API_KEY to a scoped dashboard key; all clients default to https://app.macrofold.ai. Explicit keys and custom origins support local development, staging, and self-hosting. Missing credentials fail before a request. The local simulator lets you develop without paid model calls.

Requests and streaming

Use resource methods such as client.workspaces.create and client.runs.get. TypeScript accepts typed options, Python accepts keyword arguments and returns Pydantic models, and Go/Rust/Java use typed models and idiomatic resource groups. The method reference maps every public operation across languages. Low-level transports remain optional escape hatches.

Start with a workspace ID, harness, model, billing mode, and prompt. All five SDKs accept Codex, Claude Code, OpenCode, Hermes, DeepSeek Harness and Pi through generated types. The catalog maps each model ID to its provider; the run API does not accept a separate provider field. No existing session or saved preset is required. Use a saved agent preset when you want to reuse configuration, or the returned session ID to continue a conversation.

Use runs.stream_text (with language-appropriate casing/accessors) for assistant text strings, or runs.wait for a complete typed result without streaming. Both report failed execution or persistence through a typed exception/error carrying the run ID. Waiting includes checkpoint persistence, but not optional Git synchronization. A wait timeout stops local waiting without cancelling the agent.

Waits default to a finite 30-hour deadline; set a shorter application deadline for interactive work. run_recovery_required raises the typed run error promptly with the current receipt, which may still be unfinalized. Keep that Run ID and investigate recovery; do not automatically resubmit an agent that may already have acted. See recovery events.

Advanced integrations use runs.events for structured events and durable sequence cursors; runs.stream remains available. Streaming resumes after interruptions and suppresses duplicate sequences. Save a sequence to resume after a process restart. One attachment permits eight consecutive connection failures and 2,048 total connections; reattach explicitly from the saved sequence after exhaustion. Detaching leaves the remote run running; use runs.cancel explicitly.

Direct model calls use inferences.stream(request) (language-appropriate casing) for typed incremental events and the saved terminal result. This is a single POST, with no token replay or reconnect after output begins. Use inferences.create for a finalized JSON result returned directly, including terminal failures as typed results. Exceptional running receipts carry recovery_reason; retrieve that same Run rather than submitting a replacement. New terminal inference receipts include their own usage and billing without organization-wide billing access. Every inference helper makes one attempt by default; optional retries are limited to confirmed pre-admission refusals and share one finite total deadline. See the streaming guide for copyable examples, capability errors, idempotency recovery and detachment.

Optional customer-agent path

All five clients expose the customerAgents resource group (idiomatic casing in each language) for customer-specific setup and ownership. These methods use /v1/integration-paths/customer-agents, compose the same core resources, and retain their retry/streaming behavior. TypeScript offers streamText and waitRun helpers and the optional macrofold/react connection controls. Account connection setup explains the authenticated backend callbacks; no platform key belongs in a browser component.

Read the files an agent saved

Use the run's worktree ID and a relative path with worktrees.read_file (or the language-equivalent method). The file-read guide explains complete byte responses, waiting for persistence, and downloads.

Reliable mutations

All five clients expose typed named connections and saved agent authentication through the generated contract. Select provider_connection_id for model authentication and exact connection_grants for app tools. See named accounts and presets, including the explicit availability gate for Claude subscription configurations.

All resource methods create idempotency keys for mutations. TypeScript and Python preserve them across bounded retries; Go, Rust, and Java make one REST attempt and retain the key in an error when a mutation cannot be confirmed. For recovery across process restarts, provide and store your own key per intended action, then reuse that exact key and body if the response is lost. Low-level Go/Rust/Java operations still require an explicit identity. Do not retry an uncertain mutation with a new key.

All clients preserve monetary values as decimal strings. Constructors require HTTPS except on loopback development hosts and refuse redirects. Keep API keys in server-side code. For expiring OAuth credentials, TypeScript and Python accept token suppliers; recreate the Go, Rust, or Java client with a renewed token before new requests.

See API conventions for errors, pagination, asynchronous operations, and organization selection. Contributors can read SDK architecture and verification.