Create a workspace, 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 workspace, 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; durable agent streams reconnect automatically. Direct inference streams use one POST and recover by Run identity after interruption.
Before you begin
You need cURL, jq, uuidgen, and an API key created in the dashboard's API keys page. Grant workspace 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 workspace
export WORKSPACE_REQUEST_KEY="$(uuidgen)"
WORKSPACE_ID=$(curl --fail-with-body "$AGENT_HOST/v1/workspaces" \
-H "Authorization: Bearer $AGENT_API_KEY" \
-H "Idempotency-Key: $WORKSPACE_REQUEST_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"Research","persistence":"persistent"}' | jq -er '.id')
The returned ID identifies the workspace. 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 workspace "$WORKSPACE_ID" --arg model "$AGENT_MODEL" \
'{workspace_id:$workspace,harness:"codex",model:$model,billing_mode:"managed",
prompt:"Read the workspace 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
For one model call, immediate inference returns its finalized JSON result directly from POST /v1/inferences; it does not use the agent queue. Its exceptional HTTP 202 response identifies existing work awaiting completion/recovery.
- Stream model responses or agent output, including a complete direct-inference cURL example.
Use a worktree 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.