# Macrofold Java SDK

Typed resource methods and resumable run streams using the JDK HTTP client and Jackson. Supports Java 11 or later; contributor builds use JDK 21 and Maven.

Works with [Macrofold Cloud](https://staging.macrofold.ai/docs/raw/cloud.md) and [self-hosted deployments](https://staging.macrofold.ai/docs/raw/self-hosting.md). Use the same resource methods with the origin and API key for your deployment. For help integrating an existing application, use the [coding-agent setup prompt](https://staging.macrofold.ai/docs/raw/agents.md).

## Install from source

Install into your local Maven repository:

```sh
mvn -B -f sdk/java/pom.xml install
```

Add this dependency to your application's `pom.xml`:

```xml
<dependency>
  <groupId>dev.macrofold</groupId>
  <artifactId>macrofold</artifactId>
  <version>0.1.0</version>
</dependency>
```

## Start a run

Set `MACROFOLD_API_KEY` to a scoped dashboard key and copy a project ID. Select a harness and model directly; no saved agent or session is required. This example uses Codex and OpenAI’s GPT-5.4 mini. The model catalog determines the provider. Managed execution uses your credits; use `fixture-model` with the local simulator for free development.

```java
import dev.macrofold.Macrofold;
import java.util.UUID;
import dev.macrofold.model.RunCreate;

public class Example {
    public static void main(String[] args) throws Exception {
        Macrofold client = new Macrofold();
        var run = client.runs().create(new RunCreate()
            .projectId(UUID.fromString("YOUR_PROJECT_ID"))
            .harness(RunCreate.HarnessEnum.CODEX)
            .model("gpt-5.4-mini")
            .billingMode(RunCreate.BillingModeEnum.MANAGED)
            .prompt("Create hello.txt containing Hello world."));
        client.runs().streamText(run.getRunId(), text -> {
            System.out.print(text);
            return true;
        });
    }
}
```

The default origin is `https://app.macrofold.ai`. Pass an explicit key with `new Macrofold(apiKey)`, or use the builder for custom origins. Empty or missing credentials fail before a request:

```java
var client = Macrofold.builder()
    .baseURL("http://localhost:3210")
    .apiKey("YOUR_LOCAL_API_KEY")
    .build();
```

## Resource methods

`client.runs().get(id)` fetches a run; `client.runs().cancel(id)` cancels it. Query/header options use named parameter classes: `client.projects().list(new Resources.ListProjectsParams().limit(20))`. `client.projects().list()` uses defaults. Import `dev.macrofold.Resources` for parameter classes.

[Every public operation](https://staging.macrofold.ai/docs/raw/sdk/reference.md) has a typed resource method. Models expose fluent setters and typed getters. The API validates required fields, selector combinations, ownership, and model/BYOK configuration. Money remains decimal strings. Pages expose `getData()` and `getNextCursor()`.

## Recovery and streaming

Mutations generate idempotency keys automatically. REST requests make one attempt. For a saved identity, use `resource.withOptions(new RequestOptions(key, organizationId))`, importing `dev.macrofold.RequestOptions`; pass `null` for the default organization. `RequestException` extends `ApiException`, preserving status, headers, body, cause, and `getIdempotencyKey()`. Inspect remote state and retry the same body and key after an uncertain outcome.

`runs().streamText(id, after, callback)` delivers assistant text fragments only, reconnecting and suppressing duplicate events. `events()` exposes structured events; `stream()` remains available. The overload without `after` starts at sequence zero. Return `false` to detach; interruption is observed during reads and retries, while idle reads are bounded by the connection timeout. Detachment leaves the agent running. Use `runs().cancel(id)` explicitly, and save event sequences to resume after a process restart.

The resource's organization option applies to stream connections, reconnects, and history checks without changing other resources.

File writes accept a `File` and `Resources.WriteFileParams(path, revision)`. Reads return a temporary file; delete it after use.

## Wait for the complete response

```java
var result = client.runs().wait(run.getRunId(), java.time.Duration.ofMinutes(5));
System.out.println(result.getOutputText());
System.out.println(result.getCheckpointId());
```

`wait(id)` has no overall timeout. It polls until execution and persistence finish and returns the typed result; optional Git synchronization is separate. A timeout raises `WaitTimeoutException` with `getRunId()`, closes the in-flight response, and stops local waiting. Interruption detaches without cancelling the agent.

Both text streaming and waiting raise `RunFailedException` for failed, cancelled, timed-out, or unsuccessfully persisted runs. Inspect `getRunId()`, `getStatus()`, `getFailureCode()`, and `getResult()`. Partial text may precede failure; transport/authentication exceptions retain their existing types. `Macrofold` is a branded entrypoint extending the existing `Client`.

## Read persisted files

```java
client.runs().wait(run.getRunId());
var file = client.workspaces().readFile(
    run.getWorkspaceId(), new Resources.ReadFileParams("hello.txt"));
try {
    System.out.println(java.nio.file.Files.readString(file.toPath()));
} finally {
    java.nio.file.Files.delete(file.toPath());
}
```

Import `dev.macrofold.Resources`. For binary content, use `Files.readAllBytes`. Delete the returned temporary file after use.

Direct reads return the complete file up to 4 MiB. During execution they use the last published revision. See [reading files](https://staging.macrofold.ai/docs/raw/workspaces/read-files.md) for HTTP usage, larger downloads, permissions, and errors.

## Advanced access

Generated classes such as `new ProjectsApi(client)` remain available, including `WithHttpInfo` variants for response headers and status. Low-level mutations still require explicit idempotency keys. Constructors require HTTPS except on loopback hosts and refuse redirects. For refreshed OAuth tokens, construct a new client with the renewed token.

See [API conventions](https://staging.macrofold.ai/docs/raw/api/conventions.md) for permissions, errors, and asynchronous work.

## Choose a harness

The same run methods support `codex`, `claude-code`, `opencode`, `hermes`, `deepseek`, and `pi`. Select a compatible model from the catalog. See [harness capabilities and examples](https://staging.macrofold.ai/docs/raw/harnesses.md).