API quickstart

Create a workspace, run an agent, and print the result. This example works with Macrofold Cloud or your own deployment.

Building with a coding agent? Copy the setup prompt and describe the feature you want.

Before you begin

1. Get access to Macrofold Cloud, use a self-hosted deployment, or start the free local simulator.
2. In API keys, create a key with workspace and run read/write access. Store it as MACROFOLD_API_KEY in your server environment.
3. Install the Python SDK. Prefer another language? Use TypeScript, Go, Rust, Java, or HTTP.

1. Create a workspace

Save this as example.py. Set MACROFOLD_BASE_URL to your deployment's origin for local or self-hosted use; leaving it unset selects Cloud. This example reads that variable explicitly.

import os
from macrofold import Macrofold

macrofold = Macrofold(
    base_url=os.environ.get("MACROFOLD_BASE_URL", "https://app.macrofold.ai"),
)
workspace = macrofold.workspaces.create(name="Research")

A workspace keeps its files between tasks. Save workspace.id and reuse it in your application.

2. Start a run

Append the following. Set MACROFOLD_MODEL to a model enabled for Codex in your dashboard. For free local simulation, use fixture-model. Real execution requires credits or a configured BYOK connection and can incur charges.

run = macrofold.runs.create(
    workspace_id=workspace.id,
    harness="codex",
    model=os.environ["MACROFOLD_MODEL"],
    billing_mode="managed",
    prompt="Create hello.txt containing Hello world.",
    limits={"timeout_seconds": 300, "max_cost_micro_usd": "1000000"},
)

This caps the run budget at $1; it is not a price estimate. To choose another agent, see harnesses and models. A saved agent preset can supply the harness, model, and billing settings instead.

3. Get the result

result = macrofold.runs.wait(run.run_id)
print(result.output_text)
macrofold.close()

Run python example.py. You'll see the agent's response after execution and file persistence finish. A failed run raises an exception with its run ID. Simulation produces scripted output rather than interpreting the prompt.

For a real-model run, read hello.txt using run.worktree_id to verify the saved result. Reuse that worktree for the next task instead of creating a new workspace. The saved file is independent of the earlier compute; keeping the same native conversation additionally requires a compatible session. See from one task to ongoing work.

Next steps

• Make one immediate model call, without creating a workspace, worktree or native agent. Its finalized result includes usage and billing; an explicit recovery receipt identifies unfinished completion.

• Stream direct model calls or agent output, with complete REST and SDK examples.

• Approve connector access and choose inherited, specific, or no tools.

• Stream text as the agent works.

• Read the saved file using run.worktree_id.

• Let another agent use those files.

• Handle retries and errors before connecting the flow to real customer actions.