| Internet-Draft | AI Gateway Discovery | October 2026 |
| Su | Expires 1 May 2027 | [Page] |
This document defines how a multi-protocol AI gateway announces itself
on a local network using DNS-Based Service Discovery (DNS-SD), and how a
client discovers it. A gateway publishes its host name, TCP port,
gateway mount path (path), and supported protocol identifiers using
_ai-gateway._tcp, DNS-SD subtypes, and a compact, vendor-neutral TXT
record.¶
A single AI gateway listener can expose text, reasoning, token counting, image generation, video generation, speech synthesis, realtime voice, and search across HTTP, Server-Sent Events (SSE), WebSocket, and WebRTC/SDP sessions. This profile lets clients discover those capabilities without hardcoding addresses, ports, or vendor-specific TXT keys, while keeping the default DNS TXT payload under 200 bytes (and strictly capped at 400 bytes).¶
This document only covers service discovery. It does not define AI request payloads, model catalogs, API key distribution, or trust bootstrap. Data learned from mDNS or DNS-SD is untrusted network input and does not prove who operates the gateway.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 1 May 2027.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
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 [OpenResponses]
(/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) [RFC6762] and DNS-Based Service Discovery
(DNS-SD) [RFC6763] 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 [RFC6763]).¶
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 [RFC6335].¶
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.¶
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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
An HTTP server or reverse proxy that exposes one or more AI wire protocols over a TCP listener.¶
The component that publishes the gateway's DNS-SD records.¶
An application, CLI, or library that browses and resolves those records.¶
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.¶
A discovered gateway endpoint that has been parsed, but has not yet been trusted or approved for sending credentials.¶
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 [RFC6762] and [RFC6763] apply without change.¶
The advertised TCP listener speaks HTTP [RFC9110], optionally protected by TLS [RFC9846]. Within that HTTP listener, individual endpoints MAY use:¶
standard HTTP request/response (JSON, binary audio/video content, or SDP payloads [RFC9429]);¶
Server-Sent Events (SSE) for streaming token or event output;¶
WebSocket upgrades [RFC6455] 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 [RFC9114] over QUIC (when tls=1) MAY
upgrade discovered HTTPS connections to HTTP/3 using the standard HTTP
Alt-Svc header field [RFC7838]. Direct advertisement of QUIC-only
listeners via _ai-gateway._udp or DNS SVCB records is left for a
future extension.¶
As required by [RFC6763], 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 [RFC6762] and
[RFC6763]. 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.¶
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).¶
| 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
|
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 records follow Section 6 of [RFC6763]:¶
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 [RFC6763], 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 [RFC6763].¶
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 [RFC6763]), 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.¶
Every advertisement under this profile MUST include these four attributes:¶
| Key | Length | Allowed value | Meaning |
|---|---|---|---|
txtvers
|
7 |
1
|
Version of this discovery TXT format ([RFC6763] Section 6.7) |
path
|
4 | Valid relative path (typically /) |
Root mount path of the gateway on the HTTP host ([RFC6763] 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 [RFC6763].
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 ([RFC6763] 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.¶
path and Endpoint Construction
The path value is always an absolute-path reference [RFC3986] 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):¶
| 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.¶
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:¶
auth_type Tokens
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.¶
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.¶
The example below shows a CLIProxyAPI instance (CPA-8F3B) advertising
on port 8317 over mDNS with its core subtypes and 9-key TXT record:¶
_ai-gateway._tcp.local. PTR CPA-8F3B._ai-gateway._tcp.local. CPA-8F3B._ai-gateway._tcp.local. SRV 0 0 8317 cpa-8f3b.local. CPA-8F3B._ai-gateway._tcp.local. TXT ( "txtvers=1" "path=/" "tls=0" "auth=1" "auth_type=api_key" "product=cliproxyapi" "id=8F3B" "role=standalone" "protocols=responses,chat-completions,messages,interactions" ) cpa-8f3b.local. A 192.0.2.10 cpa-8f3b.local. AAAA 2001:db8::10 _responses._sub._ai-gateway._tcp.local. PTR CPA-8F3B._ai-gateway._tcp.local. _chat-completions._sub._ai-gateway._tcp.local. PTR CPA-8F3B._ai-gateway._tcp.local. _messages._sub._ai-gateway._tcp.local. PTR CPA-8F3B._ai-gateway._tcp.local. _interactions._sub._ai-gateway._tcp.local. PTR CPA-8F3B._ai-gateway._tcp.local.¶
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.¶
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.¶
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 [RFC9525], pinned certificates, or
pre-configured policy.¶
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.¶
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.¶
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 has registered the ai-gateway service name (without a fixed
port) in the Service Name and Transport Protocol Port Number Registry
under [RFC6335]:¶
| 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 [RFC8126].¶
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.¶
This document draws on the DNS-SD and mDNS specifications ([RFC6762], [RFC6763]), the Open Responses specification [OpenResponses], and implementation work in CLIProxyAPI.¶