Protocol Introduction

Pioneer clients communicate with a gateway through JSON-RPC 2.0 over WebSocket. The desktop app, mobile app, shared client core, and custom clients use this contract without linking to gateway internals. The protocol reference documents the public surface from crates/protocol. If a method, event, or payload is not exported there, treat it as an implementation detail.

Transport

The default gateway listener is:

ws://localhost:17878

The gateway accepts WebSocket text frames containing JSON-RPC requests. Server responses and notifications are also WebSocket text frames. A small number of upload paths use binary frames; those are documented on the relevant feature page.

Authentication

The WebSocket handshake must include a bearer token:

Authorization: Bearer <token>

The token is a gateway superuser JWT. You can issue one from the CLI:

pioneer issue-superuser-token

Tokens are validated during the WebSocket handshake. A missing or invalid bearer token rejects the connection with HTTP 401. The superuser JWT signing material is stored in the gateway keystore. Rotate it with pioneer secrets rotate-jwt-token superuser; existing superuser bearer tokens become invalid and must be reissued.

Request envelope

Every request uses JSON-RPC 2.0. Request ids are strings with exactly 21 characters.

{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "method": "turn/start",
  "params": {
    "thread_id": "thr_000000000000000001",
    "turn_id": "trn_000000000000000001",
    "input": [
      {
        "type": "text",
        "text": "Hello",
        "textElements": []
      }
    ]
  }
}

Successful responses return the same id:

{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "result": {
    "turn": {
      "id": "trn_000000000000000001",
      "status": "InProgress",
      "permission_profile": {
        "mode": "full_access",
        "source": "defaulted",
        "effective_policy": {
          "default_behavior": "allow",
          "file_read": "allow",
          "file_write": "allow",
          "shell_command": "allow",
          "network": "allow",
          "mcp_read": "allow",
          "mcp_write_or_unknown": "allow",
          "dynamic_skill_tool": "allow",
          "computer_use": "allow",
          "task_subagent": "allow"
        }
      }
    }
  }
}

Errors use JSON-RPC error envelopes:

{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "error": {
    "code": -32602,
    "message": "invalid params for `turn/start`: `thread_id` is required"
  }
}

Core JSON-RPC error codes are:

Code	Meaning
`-32700`	Parse error
`-32600`	Invalid request
`-32601`	Method not found
`-32602`	Invalid params

Feature-specific errors may include error.data with a machine-readable code and details.

Notifications

Notifications are server-to-client JSON-RPC messages without an id. They are how clients observe long-running turns, tool output, task events, MCP status, and skill catalog changes.

{
  "jsonrpc": "2.0",
  "method": "item/agent_message/delta",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "thread_id": "thr_000000000000000001",
    "turn_id": "trn_000000000000000001",
    "item_id": "itm_000000000000000001",
    "delta": "Hello",
    "stream": "agent_message"
  }
}

Clients should treat request responses as acceptance or lookup results, not as the complete operation. For example, turn/start returns after the gateway accepts the turn; the assistant response arrives through turn/* and item/* notifications.

Naming conventions

Method names use slash-separated groups:

workspace/default
thread/start
turn/start
provider/models/list
cli_runtime/list
settings/get
memory/search
skills/upload/start
mcp/server/restart
task/create
artifact/list/thread

Payload field casing is mostly inherited from Rust serde attributes. Many request/response structs use snake_case fields, while task and timeline models often use camelCase. Do not infer casing from method names; use the schema or examples for the exact payload.

Schemas

JSON Schemas are generated from crates/protocol and written to /schemas. The schema file names use snake_case type names, for example:

/schemas/turn_start_params.json
/schemas/thread_tree_response.json
/schemas/mcp_install_params.json
/schemas/task_create_params.json

When implementing a client, use this reference for behavior and the generated schemas for exact type validation.

Reference sections

Workspace & Threads

Workspace listing, creation, selection, renaming, thread creation, folders, history, and subscription cleanup.

AGENTS.md

Thread-tree instruction file read, save, archive, resolve, and notification methods.

Turns

Turn submission, cancellation, item events, timeline composition, and streaming notifications.

Providers

Provider listing, model listing, and API key management.

CLI Runtime

Codex CLI runtime listing, model catalogs, thread bindings, approvals, login, review, compaction, fork, and turn steering.

Settings

Gateway-scoped general, memory, thread-context, CLI runtime, and remote-access settings read/update methods.

Skills

Skill upload, install, update, uninstall, policy, health, and catalog notifications.

Memory

Durable memory search, remember, forget, candidate review methods, and memory notifications.

MCP Servers

MCP install config, policy, restart, uninstall, details, runtime status, and catalog notifications.

Tasks

Durable task creation, scheduling, subagents, task trees, waiting, deliveries, and task events.

Artifacts

Workspace file upload, listing, preview reads, downloads, bindings, artifact notifications, and model-facing artifact read behavior.

​Transport

​Authentication

​Request envelope

​Notifications

​Naming conventions

​Schemas

​Reference sections