Runner protocol

Runner protocol version 1 is an authenticated HTTP/NDJSON contract implemented by operator-supplied runner services. The server sends the token from WORKFLOW_RUNNERS as Authorization: Bearer <token>. A compatible runner must reject missing or invalid credentials.

Capabilities

GET /v1/capabilities returns protocol version, supported node/runtime features, streaming support, and execution constraints. A runner advertises the node types and runtime services available in its own deployment. The server only delegates executions compatible with that response.

Start execution

POST /v1/executions accepts:

{
  "version": 1,
  "workflow": {},
  "input": {},
  "trace": false,
  "runtime": {
    "models": [],
    "toolsets": [],
    "workflows": [],
    "http": { "policy": {}, "secrets": {} }
  },
  "permissions": [],
  "authorization": {},
  "toolPolicies": [],
  "consentAvailable": false
}

runtime, permissions, authorization, toolPolicies, and consentAvailable are optional. The server includes the applicable workflow capabilities, launch grants, host tool policies, and whether the launch has an interaction route for consent. A runner must apply the same permission decisions as built-in execution and emit them for auditing.

Invalid protocol/workflow requests return 400 INVALID_EXECUTION; authentication failures return 401 UNAUTHORIZED. Protocol validation occurs before acceptance, so unsupported versions fail without an accepted event. A valid request switches to application/x-ndjson and emits one JSON event per line.

When runtime.models is supplied, role lookups are reconstructed from that payload. If a requested role is missing and general exists, execution falls back to general.

Event order

1. accepted with a generated executionId.
2. Zero or more node.started, permission.decision, node.completed, node.failed, or node.suspended events.
3. Exactly one result, or an error with EXECUTION_FAILED.

Each event includes version: 1. The connection closes after the terminal event. Acceptance is the handoff boundary: callers must not assume a failed connection after acceptance is safe to rerun elsewhere.

executionId is generated by the runner and included in the accepted event.

Security

Runtime configuration may contain model API keys, MCP authorization headers, named HTTP secrets, and complete child workflow definitions. Use TLS or a private network, rotate bearer tokens, and avoid logging bodies. The runner is intentionally stateless and cannot execute workflows that require server checkpoint or persistent-value services.