# Desktop Gateway v1 HTTP and SSE surface ## Public discovery ```text GET /desktop/v1/health GET /desktop/v1/server-info GET /desktop/v1/capabilities ``` `server-info.serverInstanceId` becomes the expected server identity for the active connection. A later mismatch freezes that connection rather than silently rebinding it. ## Authentication ```text POST /desktop/v1/auth/login POST /desktop/v1/auth/refresh ``` Credentials and returned tokens remain in the Rust layer. Request and response bodies containing credential material must not derive or use unrestricted debug logging. ## Messaging and events ```text POST /desktop/v1/messages GET /desktop/v1/events/stream POST /desktop/v1/events/{event_id}/ack ``` SSE frames carry both the SSE `id` and the complete JSON event envelope in `data`. Reconnect uses the `Last-Event-ID` request header. Replay and de-duplication are scoped to the local connection profile, so the same event ID on two server instances remains two distinct events. Initial event types: ```text system.heartbeat message.delta message.completed message.proactive agent.status tool.proposal capabilities.changed error ``` ## Local action reporting ```text POST /desktop/v1/local-actions/{action_id}/accepted POST /desktop/v1/local-actions/{action_id}/rejected POST /desktop/v1/local-actions/{action_id}/progress POST /desktop/v1/local-actions/{action_id}/result ``` A `tool.proposal` is only an untrusted proposal. Schema validation, tool registry validation, slot/profile checks, server identity verification, expiry checks, local policy, and user authorization happen before any local execution.