DNS-Based Service Discovery for AI Gateways

Introduction Local developer tools, CLI agents (such as Codex CLI, Claude Code, and DeepSeekHarness), IDE extensions, and desktop apps increasingly connect to AI models through a unified gateway. Unlike a single-purpose inference server, a full-featured AI gateway (such as CLIProxyAPI) acts as a protocol router and translator across multiple wire protocols and transport modes on a single listening port:

Text and reasoning: Open Responses (/v1/responses over HTTP, SSE, compaction, and persistent WebSocket streams), Chat Completions (/v1/chat/completions), Legacy Completions (/v1/completions), Messages (/v1/messages), and GenerateContent / Interactions (/v1beta/models/{model}:generateContent, :streamGenerateContent, /v1beta/interactions).
Token accounting and model metadata: Authenticated model catalogs (/v1/models, /v1beta/models) and token counting (/v1/messages/count_tokens, :countTokens).
Multimodal generation: Image generation and editing (/v1/images/generations, /v1/images/edits), video generation and retrieval (/v1/videos*), and speech synthesis (/v1/audio/speech, /v1/tts).
Realtime and agentic extensions: Realtime WebSocket and WebRTC/SDP call sessions (/v1/realtime*, /v1/live*) and agentic search (/v1/alpha/search).

On a local network, that gateway's IP address or port can change, and users should not have to type connection settings by hand on every device. Multicast DNS (mDNS) and DNS-Based Service Discovery (DNS-SD) already solve host and port discovery on a LAN. This document defines a vendor-neutral DNS-SD profile using the IANA-registered service type _ai-gateway._tcp, capability subtypes, and a 9-key TXT record format where every key is at most 9 characters long (per Section 6.4 of ).

Status of This Document This is an individual Internet-Draft (-01). Submitting an Internet-Draft does not mean the IETF has endorsed it, adopted it in a Working Group, or approved it as an Internet Standard. The service name ai-gateway (transport protocol TCP, service name only) and its nine defined TXT keys (txtvers, path, tls, auth, auth_type, protocols, product, id, role) have been registered by IANA in the Service Name and Transport Protocol Port Number Registry under .

What This Document Covers and What It Does Not This document covers four things:

how to list AI gateways on a local network;
how to find a gateway's host, port, and root mount path (path);
how to advertise supported wire protocols and multimodal capabilities using vendor-neutral identifiers;
how a client validates discovery data safely before authenticating and querying model catalogs.

This document does not cover:

model names, per-model capabilities, or model routing rules;
request or response JSON schemas for any AI API;
sending API keys, OAuth tokens, or passwords over discovery;
automatic pairing, trust bootstrap, or certificate issuance;
gateway administration (/v0/management, /v8/management), billing, or control-plane cluster protocols;
wide-area discovery relays or standalone UDP/QUIC mDNS records.

Conventions and Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Gateway:: An HTTP server or reverse proxy that exposes one or more AI wire protocols over a TCP listener.
Advertiser:: The component that publishes the gateway's DNS-SD records.
Client:: An application, CLI, or library that browses and resolves those records.
Gateway mount path (path):: The root URI path prefix where the gateway is mounted on the target host (normally /, or a reverse-proxy prefix such as /ai). Each individual wire protocol appends its own standard versioned route (such as /v1/responses or /v1beta/interactions) beneath path.
Candidate endpoint:: A discovered gateway endpoint that has been parsed, but has not yet been trusted or approved for sending credentials.

Service Records

Service Type and Transports The DNS-SD service type is _ai-gateway._tcp. In the IANA Service Name and Transport Protocol Port Number Registry, this corresponds to the registered service name ai-gateway over TCP. This specification does not ask for a fixed TCP port. Clients MUST read the port from the SRV record and MUST NOT fall back to hardcoded ports such as 80, 443, or 8317. On a local link using mDNS, the discovery domain is local., so the full service browse name is _ai-gateway._tcp.local.. Standard mDNS and DNS-SD rules from and apply without change. The advertised TCP listener speaks HTTP , optionally protected by TLS . Within that HTTP listener, individual endpoints MAY use:

standard HTTP request/response (JSON, binary audio/video content, or SDP payloads );
Server-Sent Events (SSE) for streaming token or event output;
HTTP/2 negotiated via ALPN or cleartext upgrade;
WebSocket upgrades on supported paths (such as <path>/v1/responses and <path>/v1/realtime).

While _ai-gateway._tcp advertises the initial TCP listener, a gateway that also enables HTTP/3 over QUIC (when tls=1) MAY upgrade discovered HTTPS connections to HTTP/3 using the standard HTTP Alt-Svc header field . Direct advertisement of QUIC-only listeners via _ai-gateway._udp or DNS SVCB records is left for a future extension.

Instance, Target Host, and IP Addresses As required by , an advertiser MUST publish:

a PTR record from _ai-gateway._tcp.<domain> to the service instance name;
an SRV record giving the target host name and TCP port for that instance;
a TXT record carrying the metadata defined in this document;
A and/or AAAA records for the target host name.

The SRV target is a DNS host name, not a URL. If the SRV target is ., the service is unavailable and clients MUST ignore it. A gateway MUST only advertise addresses that are actually reachable on the network interface where the announcement is sent. It MUST NOT advertise a loopback-only listener (127.0.0.1 or ::1) on a LAN. Each service instance represents one listening port and one TLS mode. If a gateway listens on both plaintext HTTP and HTTPS, it MUST advertise them as two separate service instances. Instance naming, uniqueness probing, conflict resolution, TTL handling, cache-flush flags, and goodbye packets MUST follow and . A gateway MAY append a short stable suffix (such as CPA-8F3B) so humans can recognize it across restarts, but clients MUST NOT treat the instance name or id as proof of identity. Clients MUST retain the network interface scope when handling IPv6 link-local addresses.

Capability Subtypes and Wire-Protocol Routes A gateway MAY publish DNS-SD subtype PTR records so clients can filter by wire protocol during browsing. Every subtype name is vendor-neutral and names the wire operation rather than a company or model brand. To prevent mDNS packet bloat while supporting rich gateways, subtypes are organized into two tiers: Core Subtypes (advertised by default when supported) and Extended Subtypes (advertised when configured by the operator).

Core Subtypes

Subtype label	Primary Inference Route	Optional Model Catalog Route
`_responses`	`POST/GET <path>/v1/responses`, `/v1/responses/compact`	`GET <path>/v1/models`
`_chat-completions`	`POST <path>/v1/chat/completions`	`GET <path>/v1/models`
`_messages`	`POST <path>/v1/messages`, `/v1/messages/count_tokens`	`GET <path>/v1/models`
`_generate-content`	`POST <path>/v1beta/models/{model}:generateContent`, `:streamGenerateContent`	`GET <path>/v1beta/models`
`_interactions`	`POST <path>/v1beta/interactions`	`GET <path>/v1beta/models`

Extended Subtypes Gateways that expose multimodal, realtime, or specialized agent endpoints MAY also advertise the following subtypes:

Subtype label	Standard Route Relative to path	Capability
`_completions`	`POST <path>/v1/completions`	Legacy text completions
`_responses-ws`	`GET <path>/v1/responses` (WebSocket)	Persistent WebSocket Responses stream
`_realtime`	`GET/POST <path>/v1/realtime`, `/v1/live`	Realtime voice/video (WebSocket, WebRTC SDP, SIP control)
`_images`	`POST <path>/v1/images/generations`, `/v1/images/edits`	Image generation and editing
`_videos`	`POST/GET <path>/v1/videos*`	Video generation, editing, and retrieval
`_audio`	`POST <path>/v1/audio/speech`, `/v1/tts`	Speech synthesis (TTS)
`_count-tokens`	`POST <path>/v1/messages/count_tokens`, `:countTokens`	Standalone token counting
`_search`	`POST <path>/v1/alpha/search`	Agentic web/code search

For example, a gateway advertising the _responses subtype over mDNS publishes a PTR record at: _responses._sub._ai-gateway._tcp.local. pointing to the same service instance name as _ai-gateway._tcp.local.. A gateway MUST only advertise subtypes for routes that are enabled on that listener. Advertising a subtype does not guarantee that every user credential or upstream model supports that operation. If a client sees a subtype it does not recognize, it MUST ignore the unknown subtype rather than rejecting the gateway.

TXT Record Format

Basic Rules, Key Length Compliance, and the 400-Byte Budget TXT records follow Section 6 of :

Each attribute is stored as a separate DNS TXT character-string in the form key=value.
Keys are case-insensitive. Advertisers MUST write keys in lowercase.
Strict 9-character key limit: Every TXT key defined in this specification is at most 9 characters long (txtvers, path, tls, auth, auth_type, protocols, product, id, role), strictly complying with Section 6.4 of , and contains no vendor or model trademarks.
Values are case-sensitive unless stated otherwise.
Advertisers MUST NOT put duplicate keys in the same TXT record. If a client receives duplicate keys (even with different casing), it MUST keep the first one and ignore the rest, as required by Section 6.4 of .

To keep mDNS packets small and avoid IP fragmentation on local networks:

each key=value string MUST be at most 255 bytes;
the entire TXT record payload (including the 1-byte length prefix in front of each string) MUST be at most 400 bytes;
all keys and values defined here use printable US-ASCII (0x20 to 0x7E), and every key requires a non-empty value after =.

Advertisers pack TXT attributes in priority order:

Priority 1 (Mandatory Core): txtvers (placed first per Section 6.7 of ), path, tls, auth.
Priority 2 (Capabilities & Identity): protocols, auth_type, product, id.
Priority 3 (Optional Hints): role.

If adding an optional attribute would push the TXT record over 400 bytes, the advertiser MUST omit that optional attribute rather than truncating a value or dropping a required attribute.

Required Attributes Every advertisement under this profile MUST include these four attributes:

Key	Length	Allowed value	Meaning
`txtvers`	7	`1`	Version of this discovery TXT format ( Section 6.7)
`path`	4	Valid relative path (typically `/`)	Root mount path of the gateway on the HTTP host ( Section 6.5)
`tls`	3	`0` or `1`	`0` for HTTP/WS, `1` for HTTPS/WSS
`auth`	4	`0` or `1`	`0` if unauthenticated requests are allowed, `1` if credentials are required

txtvers: Placed as the first TXT key per Section 6.7 of . It identifies the discovery metadata format, not the gateway's software version. Clients that do not support the advertised txtvers MUST NOT parse the record as version 1.
path: Uses the standard DNS-SD HTTP path key ( Section 6.5) to indicate the gateway's root mount prefix on the target host and port. For a standalone gateway, path is /. For a gateway mounted behind a reverse proxy at /ai, path is /ai.
tls: Selects http/ws (0) or https/wss (1). If tls is missing or invalid, the client MUST reject the candidate and MUST NOT default to plaintext.
auth: Uses compact 0/1 boolean encoding (1 means authentication required, 0 means not required). If auth is missing or invalid, the client MUST reject the candidate and MUST NOT assume 0.

Validation of path and Endpoint Construction The path value is always an absolute-path reference on the discovered host and port, never a full URI. To be valid, path:

MUST start with a single /;
MAY be / (the default for standalone gateways);
MUST NOT start with // or contain ://;
MUST NOT contain ?, #, \, spaces, or control characters;
MUST NOT end with / (unless the entire path is /);
MUST NOT contain empty segments (//), . segments, .. segments, or percent-encoding (%xx).

If path is missing or fails validation, the client MUST treat the service instance as unusable. To construct a request URL for a supported wire protocol, the client concatenates the scheme (http/https or ws/wss), the SRV target host (or a resolved A/AAAA IP address) and SRV port, the validated path (omitting a trailing slash when path is /), and the protocol's standard route from Section 3.3:

When path=/ (for example, on 192.0.2.10:8317 with tls=0):
- _responses -> http://192.0.2.10:8317/v1/responses
- _chat-completions -> http://192.0.2.10:8317/v1/chat/completions
- _messages -> http://192.0.2.10:8317/v1/messages
- _interactions -> http://192.0.2.10:8317/v1beta/interactions
- _generate-content -> http://192.0.2.10:8317/v1beta/models/{model}:generateContent
- Model catalog -> http://192.0.2.10:8317/v1/models (or http://192.0.2.10:8317/v1beta/models)
When path=/ai (mounted behind a reverse-proxy prefix):
- _responses -> <scheme>://<host>:<port>/ai/v1/responses
- _interactions -> <scheme>://<host>:<port>/ai/v1beta/interactions
- Model catalog -> <scheme>://<host>:<port>/ai/v1/models

Optional Attributes and Capability Vocabulary

Key	Length	Format	Meaning
`protocols`	9	Comma-separated tokens	Supported wire protocols and capabilities
`auth_type`	9	Comma-separated tokens	Accepted authentication mechanisms
`product`	7	Non-empty printable ASCII	Software identifier (e.g., `cliproxyapi`)
`id`	2	Non-empty printable ASCII	Short non-cryptographic instance ID (e.g., `8F3B`)
`role`	4	Non-empty printable ASCII	Deployment role hint (e.g., `standalone`)

For comma-separated lists (protocols, auth_type), tokens use lowercase ASCII letters, digits, -, or _, with no spaces or empty items. Clients MUST ignore unknown tokens.

Standard protocols Tokens The protocols list is the single TXT capability list. Its tokens match the subtype labels in Section 3.3 without their leading underscore:

Core default set: chat-completions, responses, messages, generate-content, interactions
Extended tokens (may be advertised when enabled and within the 400-byte budget): completions, responses-ws, realtime, images, videos, audio, count-tokens, search

Standard auth_type Tokens

api_key: API key authentication. The client sends the key using the standard HTTP header for the wire protocol being called:
- /v1/responses, /v1/chat/completions, /v1/models, and other /v1/* routes: Authorization: Bearer <key>
- /v1/messages and /v1/messages/count_tokens: x-api-key: <key> or Authorization: Bearer <key>
- /v1beta/* (:generateContent, /interactions, /v1beta/models): x-goog-api-key: <key>
oauth: OAuth / token-backed client sessions where applicable.

Exclusion of Management Interfaces Gateways MUST NOT use _ai-gateway._tcp to advertise management endpoints (such as /v0/management, /v8/management, or /management.html), and advertisers SHOULD NOT emit any management TXT key.

How a Client Uses Discovery Results A client follows five steps:

Browse: Query _ai-gateway._tcp (or a desired subtype such as _responses._sub._ai-gateway._tcp) on allowed local interfaces. Clients looking for a specific gateway product (such as CPA) MAY prioritize instances with product=cliproxyapi while retaining standard gateways as fallbacks.
Resolve: Fetch SRV, TXT, and A/AAAA records for each discovered instance.
Validate: Check that txtvers=1, path, tls, auth, the TCP port (1..65535), and usable IP addresses are present and valid.
Filter addresses and preserve IPv6 scope: Reject loopback, unspecified (0.0.0.0, ::), multicast, or other addresses blocked by local policy. When connecting to an IPv6 link-local address (fe80::/10), the client MUST attach the local network interface zone identifier (for example, %en0) learned during discovery.
Confirm trust before sending requests (and optionally query <path>/v1/models): Show the candidate to the user or match it against pre-configured trust rules. Querying <path>/v1/models or <path>/v1beta/models is OPTIONAL: a client that already knows the target model name MAY send inference requests directly after trust confirmation. When a client does query the model catalog to populate a model selector:
- When auth=0 (unauthenticated LAN gateway): after trust confirmation, the client MAY query GET <path>/v1/models or GET <path>/v1beta/models without an API key.
- When auth=1 (authenticated gateway): if the client queries <path>/v1/models or <path>/v1beta/models, it MUST include a valid API key and MUST NOT call those endpoints unauthenticated; pre-authentication filtering relies on DNS-SD subtypes and TXT protocols (and optional GET/HEAD <path>/healthz liveness checks).

Clients MUST NOT automatically send API keys to a newly discovered gateway just because its instance name, product, or id matches a previously seen gateway. On HTTP redirects to a different origin, clients MUST NOT automatically forward credentials.

Example DNS-SD Records (CLIProxyAPI Default Profile) The example below shows a CLIProxyAPI instance (CPA-8F3B) advertising on port 8317 over mDNS with its core subtypes and 9-key TXT record: The TXT payload above is 151 bytes (or 168 bytes when all five core protocols including generate-content are listed, including the 1-byte length prefix for each of the 9 strings) -- well under half of the 400-byte limit -- with every key at most 9 characters long and zero vendor trademarks in the TXT schema.

Operational Guidance

Off by default unless enabled: Gateways SHOULD keep LAN broadcasting disabled until enabled in configuration.
Physical LAN interfaces only (Scheme C): Gateways SHOULD filter out loopback (lo*), container bridges (docker*, veth*, br-*), VPN tunnels (utun*, tailscale*, wg*, tun*, tap*), and virtual interfaces (awdl*, llw*) by default, and refuse to fall back to all interfaces if no physical LAN interface qualifies. In Docker, host networking (--net=host) is required to multicast on the physical LAN.
Zero-config CLI discovery: Implementations SHOULD provide a standalone discovery command (such as cli-proxy-api -discover or cli-proxy-api discover) that can browse the LAN before loading a server configuration file.
Two-stage discovery (unauthenticated mDNS, authenticated /models): Do not place model catalogs, per-provider quotas, or secrets in TXT records. Because different API keys on a gateway can have different model permissions, there is no single unauthenticated model list. Clients filter gateways before authentication using DNS-SD subtypes and TXT protocols, and query <path>/v1/models or <path>/v1beta/models with the user's API key after authentication.
Flood protection: Clients MUST cap retained services, IP addresses per service, and TXT entries per service (for example: at most 256 services, 64 IP addresses per service, and 64 TXT strings per service), cancel internal browsing once the service cap is reached, and strictly respect the caller's cancellation or deadline policy without injecting hidden shorter timeouts.

Security Considerations

Spoofing on the Local Network Anyone on the local network segment can broadcast forged mDNS packets, impersonate CPA-<id>, claim auth=0, or point the SRV record at an attacker-controlled host. Clients MUST treat all discovery fields as untrusted hints until verified by user confirmation, TLS server identity verification , pinned certificates, or pre-configured policy.

Protecting API Keys and Credentials Advertisers MUST NOT place API keys, OAuth tokens, management keys, or private URLs in TXT records. Clients MUST NOT send reusable API keys over plaintext HTTP or WS (tls=0) unless explicitly approved by the user or operator for a trusted local environment. A new mDNS announcement with tls=0 MUST NOT downgrade a previously trusted HTTPS/WSS gateway to plaintext.

Preventing SSRF and Internal Network Probing Because the SRV target host, resolved IPs, and path come from untrusted multicast input, clients MUST validate path using Section 4.3, reject loopback/unspecified/special-purpose IP addresses, and re-verify destinations on any HTTP redirect.

DoS and Local Privacy Clients MUST enforce hard bounds on discovered services, addresses, and TXT bytes to prevent memory exhaustion from mDNS packet floods. Operators SHOULD be able to customize or disable advertised instance names when LAN privacy is required.

IANA Considerations IANA has registered the ai-gateway service name (without a fixed port) in the Service Name and Transport Protocol Port Number Registry under :

Field	Registered Value
Service Name	`ai-gateway`
Transport Protocol	TCP
Description	AI Gateway Local Discovery
Port Number	None (service name only)
Assignee	Changshan Su (Router-for-Me), suchangshan@foxmail.com
Contact	Changshan Su (Router-for-Me), suchangshan@foxmail.com
Registration Date	2026-10-27
Reference	`draft-su-ai-gateway-discovery`
Defined TXT Keys	`txtvers`, `path`, `tls`, `auth`, `auth_type`, `protocols`, `product`, `id`, `role`

This draft does not ask IANA to create any new registries for subtypes or TXT keys; general registration procedures are described in .

Implementation Status This section records current implementation experience for reader context and is intended to be removed before final RFC publication. CLIProxyAPI (CPA) implements LAN service advertisement and discovery in internal/discovery and sdk/cliproxy using github.com/libp2p/zeroconf/v2, paired with the cli-proxy-api -discover CLI command. Repository: https://github.com/router-for-me/CLIProxyAPI CPA exposes Open Responses (/v1/responses), Chat Completions (/v1/chat/completions), Messages (/v1/messages), GenerateContent and Interactions (/v1beta/*), and multimodal/realtime endpoints on a unified TCP listener (supporting HTTP/1.1, HTTP/2, SSE, WebSocket, and WebRTC SDP calls), and advertises _ai-gateway._tcp over mDNS.

Acknowledgments This document draws on the DNS-SD and mDNS specifications (, ), the Open Responses specification , and implementation work in CLIProxyAPI.