The Universal Harness API

The Universal Harness API is a managed agents API for every harness. One call describes an agent — any harness, any configuration — and starts it running in an isolated sandbox. No provisioning, no setup step: your first agent is running in a few seconds.

Every coding agent harness has its own installation, configuration format, authentication, and runtime quirks. Running one in production is real work; running several means maintaining several integrations. This API abstracts all of that behind one endpoint: the same payload, the same response shape, and the same thread endpoints for every harness.

curl https://api.brainbaselabs.com/v2/threads \
  -H "Authorization: Bearer $BRAINBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "harness": "claude_code",
      "instructions": "You are a concise research assistant. Answer briefly and precisely.",
      "model": "claude-sonnet-5"
    },
    "input": "In two sentences, what is the Model Context Protocol (MCP)?"
  }'

{
  "thread_id": "a4fe9c41-7fea-4b93-91e4-081329e35865",
  "agent_id": "54850f1a-e68f-46ac-a85c-01f977101f91",
  "status": "running"
}

Any harness

Change one line and the same request runs a different harness. Same payload, same response, same thread endpoints — the model, instructions, and tools carry over unchanged.

"agent": {
  "harness": "codex",
  "instructions": "You are a concise research assistant. Answer briefly and precisely.",
  "model": "claude-sonnet-5"
}

Eight harnesses are supported today. The harness values below come straight from the live runtime registry — the same source that generates the accepted values in the API reference.

The whole agent in one payload

If you've used a serverless inference API, the shape is familiar: pass a spec, get a handle. The difference is what the spec describes. Instead of a model, you pass an agent — a harness, instructions, and whatever tools it needs, all inline.

"agent": {
  "harness": "claude_code",
  "instructions": "You are a research assistant.",
  "model": "claude-opus-4-8",
  "mcp_servers": [{ "name": "search", "url": "https://mcp.example.com/sse" }],
  "skills": [{ "source": "registry:brainbase/deep-research" }],
  "secrets": { "TAVILY_API_KEY": "tvly-..." },
  "entrypoint": "pip install -r requirements.txt"
}

Same spec, same agent

Send the same agent spec twice and you get the same agent_id back, with a new thread each time. Brainbase hashes the spec and reuses the match, so you aren't minting a new agent on every call — describe the agent inline on every request and let the API dedupe. Change anything in the spec and you get a new agent.

// First call
{ "thread_id": "a4fe9c41-7fea-4b93-91e4-081329e35865",
  "agent_id":  "54850f1a-e68f-46ac-a85c-01f977101f91", "status": "running" }

// Identical spec, called again — same agent, new thread
{ "thread_id": "194c86d9-6b57-4128-83b8-a31fb8a7370e",
  "agent_id":  "54850f1a-e68f-46ac-a85c-01f977101f91", "status": "running" }

Already have an agent? Pass agent_id directly and skip the spec entirely.

{
  "agent_id": "54850f1a-e68f-46ac-a85c-01f977101f91",
  "input": "Same agent, new conversation."
}

Watch it run

A thread reports running while a turn is executing, then settles: success or fail for a finished turn, need_more_info when the agent is waiting on your answer, or idle when the turn ended without reporting an outcome. Watch it however you like.

{
  "id": "a4fe9c41-7fea-4b93-91e4-081329e35865",
  "agent_id": "54850f1a-e68f-46ac-a85c-01f977101f91",
  "title": "Explain Model Context Protocol",
  "status": "success",
  "created_at": "2026-07-15T19:07:43.910211"
}

{
  "items": [
    {
      "role": "user",
      "content": "In two sentences, what is the Model Context Protocol (MCP)?"
    },
    {
      "role": "assistant",
      "content": "The Model Context Protocol (MCP) is an open standard (introduced by Anthropic) that defines how AI applications connect to external data sources, tools, and systems through a uniform client-server interface. ...",
      "metadata": { "model": "claude-sonnet-5" }
    }
  ]
}

The stream carries the full activity of the thread as typed events — user.message, assistant.message.chunk (streaming text), assistant.message, tool_call.start, mcp.status, and idle (the turn's outcome and a summary) are the ones you'll see most, with comment keepalives in between. The connection stays open across turns, so follow-up messages and their replies arrive on the same stream.

curl -N "https://api.brainbaselabs.com/v2/threads/$THREAD_ID/events/stream" \
  -H "Authorization: Bearer $BRAINBASE_API_KEY"

event: assistant.message.chunk
data: {"type":"assistant.message.chunk","thread_id":"a4fe9c41-…","data":{"content":[{"type":"text","content":"The Model Context Protocol (MCP) is an open standard…"}]}}

event: idle
data: {"type":"idle","thread_id":"a4fe9c41-…","data":{"status":"success","summary":"Answered a factual question about MCP in two sentences; no tools needed."}}

# Replace input_id with a new UUID for this follow-up; keep it on retries.
# Use the generation from GET /v2/tasks/$THREAD_ID/inputs (0 here).
curl "https://api.brainbaselabs.com/v2/tasks/$THREAD_ID/inputs" \
  -H "Authorization: Bearer $BRAINBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_id": "11111111-1111-4111-8111-111111111111",
    "messages": [
      { "role": "user", "content": "Now name three popular MCP servers, one line each." }
    ],
    "expected_generation": 0
  }'

{
  "input": {
    "id": "11111111-1111-4111-8111-111111111111",
    "task_id": "a4fe9c41-7fea-4b93-91e4-081329e35865",
    "message_ids": ["bc85731e-7966-441f-ab57-3c92070e1438"],
    "status": "queued",
    "turn_id": null,
    "generation": 0,
    "sequence": 1,
    "created_at": "2026-09-18T12:00:00Z",
    "updated_at": "2026-09-18T12:00:00Z"
  },
  "messages": [
    {
      "id": "bc85731e-7966-441f-ab57-3c92070e1438",
      "task_id": "a4fe9c41-7fea-4b93-91e4-081329e35865",
      "role": "user",
      "content": "Now name three popular MCP servers, one line each.",
      "created_at": "2026-09-18T12:00:00Z"
    }
  ],
  "run_started": false,
  "accepted_turn_id": null
}

{
  "items": [
    {
      "role": "assistant",
      "content": "- **Filesystem** — read/write access to local files and directories for an AI client.\n- **GitHub** — manage repos, issues, and PRs directly from an MCP-enabled assistant.\n- **Slack** — send messages and read channel history through Slack's API via MCP."
    }
  ]
}

Sandboxes

Every agent runs in an isolated sandbox, and you choose the ground it runs on with machine_kind in the agent spec. The provider is fixed when the agent is created, and which ones your deployment offers depends on how it is configured.

GET /v2/machines/capabilities reports the shape of each provider — the sizes it accepts, whether it supports shared folders, which accelerators it offers — so a client can render a picker without hard-coding most of the table above. Supported runtimes are the exception: they are not in the response, so that column has to be carried by the client.

"agent": {
  "harness": "claude_code",
  "instructions": "You are a research assistant.",
  "machine_kind": "daytona"
}

See it on the platform

Everything you create through the API also shows up on the Brainbase platform — open app.brainbaselabs.com and the agent and its threads are right there, with the full conversation streaming live.