Executor Protocol

The Executor Protocol connects a harness (the brain that assigns sessions and calls tools) to an executor (the hand that runs them). It is JSON-RPC 2.0 over one WebSocket with subprotocol bma.executor.v1 or bma.executor.v1.1. The machine-readable contract (OpenRPC, AsyncAPI, JSON Schemas, conformance examples) lives in contracts/bma/executor of bma-executor-sdk; the BMA server, bmad and the three SDKs are all generated from or tested against it.

             Executor Protocol (JSON-RPC 2.0 over WebSocket)
 harness (brain) ◀──────────────────────────────────▶ executor (hand)
 assigns sessions, calls tools, reads output          runs tools / processes / PTYs, reports results

In scope: registration and capability negotiation, session assignment, tool calls, processes and terminals, file transfer, Git credentials, skill installation, cancellation, the MCP channel, reconnect, event reporting. Out of scope: how the brain thinks.

Roles are relative

Role	Sends / receives	Examples
Harness	sends `session.assign`, `tool.call`, `process.`, `terminal.`; receives results and events	The BMA platform; your local brain built with the SDK `Harness`
Executor	registers, heartbeats, executes, reports	`bmad` in every BMA sandbox, `bmad` on your computer, an app built with the SDK
Agent provider	an executor with the `agent` capability: takes turns, returns full agent events	Your own agent loop (Preview)

Whoever directs is the harness. Who dials is independent of the role: in the cloud the executor always dials out, so it works behind NAT and BMA never connects in.

Deployment shapes

Shape	Executor	Credential	Status
BMA sandbox	`bmad executor` in the machine template	Machine token	Available
Your computer or VM (BYO)	`bmad`	Machine token	Available (early access)
Embedded in your desktop app	Your app, using the Go SDK (`Client` + `Core` + `NewProcessCapability`)	Machine token from pairing	Available (early access)
Self-hosted worker	The selfhost worker	Environment key	Available

One executor per computer. A machine token always maps to executor id exec_<machine_id>. A new registration with the same id closes the old connection with code 4004; an executor that receives 4004 must stop and not reconnect. Run either bmad or your embedded executor on a computer, never both.

Capability status

Capability	Platform	`bmad`	Go SDK
Register, heartbeat, reconnect with resume, drain	✅	✅	✅
`process.*` (the machine tool path)	✅	✅	✅ `NewProcessCapability`
`terminal.*` (PTY)	✅	✅ (not on Windows)	register your own capability
`skill.install`, file transfer, Git credentials	✅	✅	✅
`tool.call` (bash and file tools)	environment path	`bash`	✅ `Core`
Artifact upload	environment path	environment path	✅ `UploadArtifact`
`workspace.backup`	✅	✅	—
MCP channel (`channel=mcp`)	✅	✅	✅
`agent` capability (`turn.*`, interactions)	Preview: text input only	not yet	✅ (all three languages)
Local socket (brain dials `bmad`)	—	Roadmap	✅

Capabilities are negotiated in executor.register; a peer never receives methods for capability bits it did not advertise.

Connecting

Exchange the machine token or environment key at the token endpoint for a short-lived JWT (5 minutes).
Open the WebSocket with the JWT and the subprotocol, send executor.register with your capabilities.
Serve requests; reconnect with exponential backoff and a fresh token, sending resume with your executor id and active sessions.

The SDKs do all of this. See bma-executor-sdk.

Agent capability

Run BMA sessions on your own agent loop

Brains roadmap

Generic ACP brains: DeepSeek Harness, Codex, Claude Code

Get started

Concepts

Executor & brains

Roles are relative

Deployment shapes

Capability status

Connecting

Agent capability

Brains roadmap

​Roles are relative

​Deployment shapes

​Capability status

​Connecting

Agent capability

Brains roadmap

Roles are relative

Deployment shapes

Capability status

Connecting