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. The same gateway also exposes unauthenticated operational HTTP endpoints, /health, /ready, and /health/native; their readiness contract is described in Observability and runtime maintenance.

Authentication

The WebSocket handshake uses an access credential from a device session:

Authorization: Bearer <access-credential>

Create a pending client device on the gateway host with:

pioneer device create

The command prints a short-lived activation code. Enter it in the desktop or mobile gateway setup flow. The client exchanges the code through the restricted auth/device/activate method and stores the returned access and refresh credentials in its platform keystore. Clients refresh the access credential with auth/refresh and can revoke a session with auth/session/revoke or auth/logout. The gateway validates the access credential during the WebSocket handshake. A missing, expired, revoked, or invalid credential rejects the connection with HTTP 401. The gateway keeps signing material internal; clients never mint or rotate it. See Authentication and authorization for the credential exchange and Identity and authentication for session and capability state.

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 and Claude Code runtime listing, model catalogs, thread bindings, approvals, login, review, compaction, fork, and turn steering.

Settings

Gateway-scoped general, memory, self-improvement, thread-context, CLI runtime, remote-access, and voice-input 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.

Authentication and access

Device activation, sessions, invitations, membership, profile updates, and capability snapshots.

Agent domain

Agent identities, authored work, delegation routes, and agent execution projections.

Patch history

Authorized file mutation, exact patch records, scoped history queries, and filesystem view grants.

​Transport

​Authentication

​Request envelope

​Notifications

​Naming conventions

​Schemas

​Reference sections