Service discovery | LMSP 1.0 Draft

3.1 Discovery methods

A client discovers a service by trying these methods in order:

Manual configuration. The user enters the service address directly.
Probing conventional local addresses. The client requests /.well-known/lmsp.json from candidate addresses. The conventional candidates are http://127.0.0.1:17832 and http://[::1]:17832.
LAN discovery. The client browses for _lmsp._tcp.local. with mDNS and DNS-SD.

A method succeeds when it yields a valid service description (section 3.3). An address the user entered manually always takes precedence over discovered ones.

3.2 LAN advertisement

DNS-SD uses PTR records to find service instances, SRV records to get the host and port, and TXT records to carry a small amount of extra information. Combined with mDNS it provides zero-configuration discovery on a local network (RFC 6763, RFC 6762).

An example advertisement:

Service type:   _lmsp._tcp.local.
Instance name:  Workstation LMSP._lmsp._tcp.local.

TXT record:
  v=1
  id=svc_01J8M4Y8K6M5E6K6Z7Z0Y8W3M2
  path=/
  auth=pairing

TXT key	Meaning
`v`	Version of the advertisement format. `1` for LMSP 1.0.
`id`	The service id, equal to `service.id` in the service description.
`path`	URL path of the service root. Clients request `{path}.well-known/lmsp.json`.
`auth`	Authentication hint. `pairing` means a client must pair before using the service.

Rules:

A service MUST NOT put access tokens, model lists, file paths or any other sensitive information in the TXT record. The record only locates the service. Real capabilities MUST be read from the service description.
A service MUST keep mDNS advertisement disabled by default. It is enabled only when the user explicitly turns on LAN discovery. A service used only on the local machine does not advertise.
A service that advertises on the LAN has to listen beyond loopback, which is only allowed in LAN mode (section 10.5).
A client MUST treat the TXT record as an unverified hint, and confirm the service by reading its description.

3.3 Service description

GET /.well-known/lmsp.json

A service MUST serve this document as application/json without requiring authentication.

{
  "protocol": "lmsp",
  "versions": ["1.0"],
  "service": {
    "id": "svc_01J8M4Y8K6M5E6K6Z7Z0Y8W3M2",
    "name": "Workstation Local Models",
    "version": "1.0.0"
  },
  "interfaces": [
    {
      "kind": "lmsp",
      "version": "1.0",
      "url": "http://127.0.0.1:17832/lmsp/v1",
      "transport": "http+json"
    },
    {
      "kind": "openai",
      "version": "responses+chat",
      "url": "http://127.0.0.1:17832/v1",
      "transport": "http+json"
    }
  ],
  "capabilities": {
    "streaming": true,
    "tasks": true,
    "event_resume": true,
    "conversations": true,
    "model_management": true
  },
  "authentication": {
    "type": "bearer",
    "pairing_url": "http://127.0.0.1:17832/lmsp/v1/pair"
  },
  "openapi": "http://127.0.0.1:17832/lmsp/v1/openapi.json"
}

Field	Meaning
`protocol`	Always `"lmsp"`.
`versions`	The LMSP versions the service supports, as `major.minor` strings.
`service`	`id` is a stable service identifier, `name` a display name, and `version` the version of the service software.
`interfaces`	The interfaces on offer. Each has a `kind` (`lmsp`, `openai` or `ollama`), a `version`, a base `url` and a `transport`. For `openai`, `version` names the API families served, such as `responses+chat`.
`capabilities`	Boolean feature flags, listed below.
`authentication`	`type` is `bearer`. `pairing_url` is where clients exchange a pairing code for a token (section 10.2).
`openapi`	URL of the OpenAPI document that describes the LMSP interface.

Capability flags:

Flag	Meaning
`streaming`	Responses can be streamed as server-sent events. MUST be `true` in 1.0.
`tasks`	Asynchronous tasks are available. MUST be `true` in 1.0.
`event_resume`	Task event streams can be subscribed to and resumed (`GET /lmsp/v1/tasks/{task_id}/events`).
`conversations`	The service stores responses, so `store` and `previous_response_id` work and `GET /lmsp/v1/responses/{response_id}` is available.
`model_management`	Models can be loaded and unloaded explicitly.

3.4 Client behavior

A client:

SHOULD select the highest version in versions that it also supports.
SHOULD select the LMSP interface or the OpenAI interface from interfaces, according to what it can speak.
MUST use only the capabilities the description declares. A missing flag means false.
MUST ignore extension fields it does not recognize.
SHOULD re-read the service description periodically and when a request fails, instead of caching it forever.
SHOULD remember a chosen service by service.id rather than by address, because addresses can change.