> ## Documentation Index > Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt > Use this file to discover all available pages before exploring further. # Protocol Introduction > Pioneer's JSON-RPC 2.0 protocol: transport, authentication, envelopes, method names, notifications, ids, schemas, and conventions. 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: ```text theme={null} 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: ```http theme={null} Authorization: Bearer ``` The token is a gateway superuser JWT. You can issue one from the CLI: ```bash theme={null} 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. ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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. ```json theme={null} { "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: ```text theme={null} 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 listing, creation, selection, renaming, thread creation, folders, history, and subscription cleanup. Thread-tree instruction file read, save, archive, resolve, and notification methods. Turn submission, cancellation, item events, timeline composition, and streaming notifications. Provider listing, model listing, and API key management. Codex CLI runtime listing, model catalogs, thread bindings, approvals, login, review, compaction, fork, and turn steering. Gateway-scoped general, memory, thread-context, CLI runtime, and remote-access settings read/update methods. Skill upload, install, update, uninstall, policy, health, and catalog notifications. Durable memory search, remember, forget, candidate review methods, and memory notifications. MCP install config, policy, restart, uninstall, details, runtime status, and catalog notifications. Durable task creation, scheduling, subagents, task trees, waiting, deliveries, and task events. Workspace file upload, listing, preview reads, downloads, bindings, artifact notifications, and model-facing artifact read behavior.