# SDKs

Use Macrofold from your application to manage projects, start cloud agents, and stream their progress. Every SDK uses the same [API contract](https://staging.macrofold.ai/openapi.json), permissions, and resource model on **Macrofold Cloud and self-hosted deployments**. Start with the [API quickstart](https://staging.macrofold.ai/docs/raw/api/quickstart.md) or [coding-agent setup prompt](https://staging.macrofold.ai/docs/raw/agents.md).

## Choose your language

| Language   | Import                                              | Guide                                              |
| ---------- | --------------------------------------------------- | -------------------------------------------------- |
| TypeScript | `import { Macrofold } from 'macrofold'`             | [TypeScript](https://staging.macrofold.ai/docs/raw/sdk/typescript.md) |
| Python     | `from macrofold import Macrofold`                   | [Python](https://staging.macrofold.ai/docs/raw/sdk/python.md)         |
| Go         | `macrofold "github.com/Macrofold/Macrofold/sdk/go"` | [Go](https://staging.macrofold.ai/docs/raw/sdk/go.md)                 |
| Rust       | `use macrofold::Macrofold`                          | [Rust](https://staging.macrofold.ai/docs/raw/sdk/rust.md)             |
| Java       | `import dev.macrofold.Macrofold`                    | [Java](https://staging.macrofold.ai/docs/raw/sdk/java.md)             |

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](https://staging.macrofold.ai/docs/raw/local-development.md) lets you develop without paid model calls.

## Requests and streaming

Use resource methods such as `client.projects.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](https://staging.macrofold.ai/docs/raw/sdk/reference.md) maps every public operation across languages. Low-level transports remain optional escape hatches.

Start with a project ID, [harness](https://staging.macrofold.ai/docs/raw/harnesses.md), 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.

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. Detaching leaves the remote run running; use `runs.cancel` explicitly.

## Optional customer-agent path

All five clients expose the `customerAgents` resource group (idiomatic casing in each language) for [customer-specific setup and ownership](https://staging.macrofold.ai/docs/raw/customer-agents/quickstart.md). 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](https://staging.macrofold.ai/docs/raw/customer-agents/connections.md) explains the authenticated backend callbacks; no platform key belongs in a browser component.

## Read the files an agent saved

Use the run's workspace ID and a relative path with `workspaces.read_file` (or the language-equivalent method). The [file-read guide](https://staging.macrofold.ai/docs/raw/workspaces/read-files.md) 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](https://staging.macrofold.ai/docs/raw/connections/named-accounts.md), 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](https://staging.macrofold.ai/docs/raw/api/conventions.md) for errors, pagination, asynchronous operations, and organization selection. Contributors can read [SDK architecture and verification](https://github.com/Macrofold/Macrofold/blob/main/docs/features/api/sdks/implementation.md).