HTTP quickstart

Create a project and run using cURL, with explicit request identities and streaming.

Create a project, start a run, and read its result with cURL. Use a local simulator for a free first request or an authorized deployment for real agent execution.

Prefer an SDK?

The TypeScript and Python guides start with Macrofold(), a scoped MACROFOLD_API_KEY, a project, and explicit harness/model configuration. Use runs.create followed by plain-text streaming or runs.wait for the complete response. The SDK index includes Go, Rust, and Java. Clients default to the hosted origin and accept local or self-hosted overrides; streams reconnect automatically.

Before you begin

You need cURL, jq, uuidgen, and an API key created in the dashboard's API keys page. Grant project and run read/write scopes for this example. Store the key as AGENT_API_KEY using your shell or secret manager.

Set the service origin and check access. Use your deployment's HTTPS origin instead of localhost for hosted work.

export AGENT_HOST=http://localhost:3210
curl --fail-with-body "$AGENT_HOST/v1/me" \
  -H "Authorization: Bearer $AGENT_API_KEY"

1. Create a project

export PROJECT_REQUEST_KEY="$(uuidgen)"
PROJECT_ID=$(curl --fail-with-body "$AGENT_HOST/v1/projects" \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "Idempotency-Key: $PROJECT_REQUEST_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Research","persistence":"persistent"}' | jq -er '.id')

The returned ID identifies the project. Reuse this request key and body if the response is lost; keep the same terminal environment for the steps below.

2. Choose a model

curl --fail-with-body "$AGENT_HOST/v1/models" \
  -H "Authorization: Bearer $AGENT_API_KEY"

Select a model compatible with Codex. To use Hermes, DeepSeek Harness, Pi, Claude Code, or OpenCode, choose a compatible catalog model and change the harness field in the request below. The harness guide compares their tools and model routes. Each catalog entry identifies its provider; use the returned model ID without adding a separate provider field. The local simulator uses fixture-model:

export AGENT_MODEL=fixture-model

For a hosted run, replace that value with an enabled model ID and add prepaid credits. Real execution can incur charges. This example sets a maximum budget of $1; it is not a prediction of the task's cost.

3. Start a run

export RUN_REQUEST_KEY="$(uuidgen)"
RUN_ID=$(jq -n --arg project "$PROJECT_ID" --arg model "$AGENT_MODEL" \
  '{project_id:$project,harness:"codex",model:$model,billing_mode:"managed",
    prompt:"Read the project and save a short progress note.",
    limits:{timeout_seconds:300,max_cost_micro_usd:"1000000"}}' | \
  curl --fail-with-body "$AGENT_HOST/v1/runs" \
    -H "Authorization: Bearer $AGENT_API_KEY" \
    -H "Idempotency-Key: $RUN_REQUEST_KEY" \
    -H 'Content-Type: application/json' --data-binary @- | jq -er '.run_id')

The server accepts the task and returns a run ID. This is an asynchronous acceptance, not the final result.

4. Follow progress and retrieve the result

curl -N --fail-with-body "$AGENT_HOST/v1/runs/$RUN_ID/stream" \
  -H "Authorization: Bearer $AGENT_API_KEY"

curl --fail-with-body "$AGENT_HOST/v1/runs/$RUN_ID/result" \
  -H "Authorization: Bearer $AGENT_API_KEY"

A cURL stream can end at the server's connection rotation before the run finishes. Reconnect with Last-Event-ID using the last event ID, or use an SDK to handle reconnection. Check the result's final flag before treating it as complete.

Continue building

Use a workspace or session selector for work over existing files and conversations. Learn authentication and retries, event delivery, and CLI workflows. The OpenAPI contract lists every operation and schema.