Socket Protocol

clients should communicate with signald via a unix socket that signald creates on startup.

By default, clients should first try connecting to $XDG_RUNTIME_DIR/signald/signald.sock, and if it does not exist fall back to /var/run/signald/signald.sock. Clients should also allow the end user to specify a path to the socket file.

Messages sent to the socket should be valid JSON, terminating with a new line character (\n). Messages from signald will follow the same format. The structure of requests that may be sent to signald are detailed in the requests section, along with their response types. The protocol documentation is also available in a machine-readable format.

Responses may not be instant, especially for requests that require network operations. To allow clients to track which response is associated with which request, a request ID may be specified in the "id" field of all requests which will be returned in the "id" field of the response. For more information, see Request IDs.

When a client connects to the socket, signald will send a JsonVersionMessage, to inform the client which version of signald is in use.