Agent harnesses

A harness is the agent software that plans work, calls tools, and edits files. A model supplies its reasoning. Macrofold runs the harness in an isolated environment and preserves the workspace's files between tasks.

The Unified Harness Interface (UHI) gives each harness the same Macrofold run operations while preserving its native behavior. Anyone can contribute another harness by implementing the interface and its integration tests.

Available harnesses

All six use the same workspace files, run budgets, cancellation endpoint, historical events, and granted connector tools. The model catalog lists the enabled combinations for your deployment. A harness name does not imply that every model or authentication method supported by its upstream workspace is available in Macrofold.

DeepSeek Harness is agent software, separate from DeepSeek's models. This integration uses its official minimal runtime profile and Macrofold's reviewed model routes. It does not enable a direct DeepSeek model provider or require a DeepSeek API key.

Start a run

In the dashboard, choose New run → Harness, then select an available model. Save an Agent preset to reuse that configuration with triggers, the API, or the CLI.

For Python, set MACROFOLD_API_KEY and use your workspace ID:

from macrofold import Macrofold

macrofold = Macrofold()
run = macrofold.runs.create(
    workspace_id="YOUR_WORKSPACE_ID",
    harness="hermes",  # Or "deepseek" or "pi"
    model="gpt-5.4-mini",
    billing_mode="managed",
    prompt="Create hello.txt containing Hello world.",
)
for text in macrofold.runs.stream_text(run.run_id):
    print(text, end="", flush=True)

All five SDKs expose these harness values through their generated request types. The request, result, file-reading, and streaming methods are identical across harnesses. Use an enabled model returned by models.list(); managed inference consumes credits. See BYOK to select your own model connection.

From a linked terminal workspace:

macrofold run "Create hello.txt containing Hello world." --harness pi --model gpt-5.4-mini

Continue and observe

Continue the returned session to reuse both its conversation and the latest verified worktree files. Native state stays with its session: Hermes retains its session database, skills, and memory; DeepSeek retains its session logs; Pi retains its conversation files. Starting another harness creates a new conversation over the same worktree rather than translating another harness's history.

Hermes and Pi stream assistant text as it arrives. The DeepSeek adapter publishes text when each assistant message commits; tool events appear as work progresses. stream_text() handles the same normalized stream for every harness and excludes tool payloads and all reasoning. Use runs.events() for structured activity or runs.wait() for the final result. Codex, Claude Code, OpenCode, Hermes and Pi also expose provider-supplied thinking through separate reasoning events. Check reasoning_output in the harness catalog; readable text and its timing depend on the selected model and native SDK.

Cancelling a run stops its native process and saves recoverable files. It does not undo completed tools. Closing a stream only detaches. DeepSeek cancellation stops its supervised native process.

If an OpenCode Run ends with harness_error, inspect its runtime.failed event. model_request_payment_required identifies an HTTP 402 rejection for credits or spending limits; check the selected BYOK connection's provider account as well as the Run budget. Authentication, access, rate-limit and service failures have separate model_request_* categories. A generic terminal error does not mean the harness failed to start. See execution diagnostics.

Tools and isolation

Select authorized connection IDs and tool grants on your preset or run. Macrofold's broker rechecks authorization and spending before external calls. Native browser/search services and additional model routes are not implicitly enabled; configure web search or other connectors through Macrofold.

Vendor API keys remain in the application gateway. Harnesses receive a short-lived run capability. Native authentication and temporary launch configuration are excluded from workspace checkpoints. Skills and local shell commands still run as agent code inside the sandbox; file permissions are not a separate security boundary between tools using the same account.

Try locally

The local simulation guide works with every harness selection using fixture-model and makes no inference calls. Simulation tests the Macrofold workflow; it does not execute the native harness.

Use local Docker to execute the real harnesses without Vercel. The shared runtime image includes all six, so no separate installation is needed on your host. Free deterministic native tests use scripted model responses and disabled networking:

pnpm test:native hermes deepseek pi

Real model reasoning requires an enabled provider route, a key, and an explicitly chosen budget. See cloud staging for hosted acceptance.

Upstream workspaces

• Hermes Agent and its programmatic interfaces.
• DeepSeek Harness and its agent embedding API. Its developer-preview interface is pinned in the runtime image.
• Pi and its SDK.