# AstrBot Desktop Gateway Protocol v1 Status: provisional P00 contract for desktop development and the local Mock Gateway. Compatibility with a real AstrBot Gateway must not be claimed until the server-side contract is reviewed. ## Source of truth Rust types in `crates/desktop-protocol` are authoritative. JSON Schema files in `schemas/` are generated and checked with: ```text cargo run -p desktop-protocol --example export_schemas -- --write cargo run -p desktop-protocol --example export_schemas ``` Generated Schema files must not be edited manually. ## Trust boundary An inbound `profileId` is an untrusted server hint. The Rust connection object binds each accepted event to its local `profile_id` and `companion` or `operations` slot. `serverInstanceId` must match the identity obtained from `server-info`. The React application never connects directly to this protocol and never receives access or refresh tokens. ## Versioning - REST prefix: `/desktop/v1` - Envelope version: `1.0` - Breaking wire changes require a new major REST prefix and protocol version. - Unknown event types are reported as unsupported and safely skipped; they are not routed to the UI. - Security-sensitive payloads reject unknown outer fields. ## Mock instances Run each instance in a separate process when manually testing independent failure: ```text cargo run -p mock-gateway -- --instance companion --port 43101 cargo run -p mock-gateway -- --instance operations --port 43102 ``` The Mock Gateway refuses non-loopback bind addresses. It uses only runtime-generated mock credentials, has no shell/file/NAS capability, and is not a Tauri release dependency. Available fixed scenarios: - `steady` - `disconnect-once` - `duplicate-events` - `auth-reject` The 30-minute dual-SSE soak is an explicit local Spike acceptance run and must be recorded separately; its result is not implied by unit tests. ## Real AstrBot transport note As of the 2026-07-20 live probe, real AstrBot servers do **not** implement /desktop/v1. Desktop keeps this protocol as the internal normalized model and maps AstrBot OpenAPI chat SSE through the Rust adapter (TransportKind::astrbot-openapi). See docs/reports/astrbot-real-protocol-review.md and docs/decisions/ADR-0005-astrbot-openapi-adapter.md.