This document defines the "llm" URI scheme, which identifies a language model by serving host, transport, model state, and credential name, and a well-known URI through which a host describes its endpoints, API dialects, and available models.
This document is an unsubmitted draft. It has not been reviewed by the IETF. It is published at llmns.info and expires on 26 February 2027.
Existing tools identify language models with tool-specific formats: LiteLLM writes "openai/gpt-4o", Hugging Face writes "org/model", Ollama writes "llama3.2:3b". These formats do not carry the serving host, the transport protocol, or the credential required for access. Deployments therefore duplicate this information in per-tool configuration, and model identifiers are not portable between tools.
This document defines a URI scheme that carries all four properties in a single reference: the serving host, the transport, the model state, and the name of a credential.
This document specifies model identification only. Request routing, retries, load balancing, distribution of model weights, and metadata such as capabilities or pricing are out of scope. The scheme defines no short names: a client MAY expand a locally configured alias (for example, "anthropic") into a full reference, but expansion MUST occur before parsing, and aliases do not appear in references.
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.
The syntax of a reference is given below in the ABNF of [RFC5234], with the case-sensitive string literals of [RFC7405]. The rules host, port, unreserved, pct-encoded, and sub-delims are defined in [RFC3986].
reference = scheme "://" [ credential "@" ] host [ ":" port ]
"/" model [ "@" pin ] [ "?" hints ]
scheme = "llm" [ "s" ] [ "+" transport ]
transport = 1*( ALPHA / DIGIT )
credential = 1*( unreserved / pct-encoded / sub-delims )
model = 1*( mchar / "/" )
pin = kind ":" value
kind = %s"name" / %s"hash" / %s"version"
value = 1*( mchar / "/" )
mchar = unreserved / pct-encoded / sub-delims / ":"
hints = hint *( "&" hint )
hint = hkey "=" hvalue
hkey = 1*unreserved
hvalue = *( unreserved / pct-encoded / ":" / "/" )
The "s" suffix selects TLS: when it is present, the connection MUST use TLS; when it is absent, the connection MUST NOT use TLS. This parallels "http" and "https". The "+transport" suffix names the transport protocol; when it is absent, the transport is HTTP. The model and value rules do not admit an unencoded "@": a literal "@" within a model identifier or a pin value MUST be percent-encoded as "%40". A pinned reference therefore has exactly one derivation. Hints are key=value pairs joined by "&"; Section 5 defines their interpretation.
llms+grpc://work@triton.internal:8001/qwen3-ft@name:step-2000?api=openai \__________/\___/\__________________/\_______/\_____________/\_________/ scheme cred. host:port model pin hints
Example references:
llms://api.anthropic.com/claude-fable-5 llms://api.openai.com/gpt-5@version:2026-03-01 llms://work@api.openai.com/gpt-5 llms://huggingface.co/meta-llama/Llama-3.1-8B@hash:6f6073b llm://localhost:11434/llama3.2:3b?api=openai llms+grpc://triton.internal:8001/qwen3-ft@name:step-2000?api=openai
A pin identifies a fixed state of a model. The pin kind declares how firmly that state is fixed:
A reference without a pin denotes the provider's current default state for that model. Clients SHOULD pin with the strongest kind the provider offers.
Two references are equivalent if and only if their normalized (host, port, model, pin) tuples are equal. Normalization applies to the host, the model, and the pin: it lowercases the host, uppercases the hexadecimal digits of percent-encodings, and decodes percent-encodings of unreserved characters, as defined in Section 6.2.2 of [RFC3986]. After normalization the components, including the pin kind, are compared octet by octet. The port is compared as given: a reference that names a port and a reference that does not are not equivalent.
Equivalence is a relation on references, not on model weights. A pinned reference and an unpinned reference to the same model identifier are not equivalent, and two occurrences of a name pin remain equivalent after the provider moves the binding (Section 3).
The credential, the hints, the transport, and the use of TLS do not contribute to equivalence. For example, llms://work@api.openai.com/gpt-5 and llm+grpc://api.openai.com/gpt-5 are equivalent.
A reference states where a model is served; resolution determines how to communicate with the host. A client SHOULD retrieve the host's well-known document (Section 6), which declares the available API dialects, the authentication scheme, and the model catalog.
Hosts that do not serve the document (for example, a local development server) are configured through hints: the "api" hint names the dialect. When a host serves several dialects, the "api" hint selects among them (Section 6). A hint MUST NOT name a dialect the host does not serve. Hint keys are case-sensitive; when a key occurs more than once, the first occurrence applies; a client MUST ignore keys it does not recognize.
Resolution yields an API dialect and, when the document is available, an endpoints entry. When the document is unavailable, the dialect comes from the "api" hint; a reference that carries no "api" hint to a host that serves no document does not resolve. The client resolves the credential name as described in Section 7 and then uses the provider's API directly.
A host publishes a JSON document at /.well-known/llmns.json, a well-known URI as defined in [RFC8615], with media type application/json. The client retrieves the document over HTTP from the host of the reference, with TLS as selected by the "s" suffix, at the port of the reference; when the reference names no port, at port 443 with TLS and at port 80 without. The "+transport" suffix does not apply to this retrieval. The document is unavailable when one of these conditions is true:
When the document is unavailable, the hints of Section 5 apply. A network failure can be temporary. A client MAY retry the retrieval before it applies the hints of Section 5. Example:
{
"llmns": 1,
"endpoints": [
{ "api": "openai", "transport": "http", "tls": true,
"path": "/v1",
"auth": { "scheme": "bearer", "realm": "acme-inference" } },
{ "api": "openai", "transport": "grpc", "tls": true,
"port": 8001,
"auth": { "scheme": "header", "header": "x-api-key",
"realm": "acme-inference" } }
],
"models": [
{
"model": "qwen3-ft",
"pins": {
"hash": ["6f6073b", "9c81d2e"],
"name": { "step-2000": "6f6073b",
"step-4000": "9c81d2e" },
"version": { "2026-03-01": "6f6073b" }
}
}
]
}
Top-level members:
Members of an endpoints entry:
An auth object has up to three members: a REQUIRED scheme ("bearer", "header", or "none"); when the scheme is "header", a REQUIRED header naming the header, for example "x-api-key"; and an OPTIONAL realm. An auth object whose scheme is "none" MUST NOT carry a header or a realm. The realm names the credential that endpoints share: endpoints that name the same realm accept the same credential. Naming a realm does not entitle the host to receive the credential; which hosts a realm credential is presented to is fixed in the client's credential store (Section 7), never by this document. The auth object never contains a secret. A models entry has a REQUIRED model member, identical octet for octet to the normalized model component of a reference (Section 4), and an OPTIONAL pins object. The hash member of pins is an array of the hashes the host serves. The name and version members are objects that map each label to the hash the label denotes, or to null when the host publishes no hash for that label. This makes the legal combinations explicit: a label pins exactly the state its hash identifies. A name binding MAY change between retrievals. A version binding MUST NOT change from one hash to another or from a hash to null; replacing null with a hash is permitted and asserts that the state the label denotes has not changed. Every hash that appears as a value MUST also be listed in the hash member.
A client considers the endpoints entries in document order and selects the first entry that matches the reference: the entry's transport and TLS mode equal those of the reference scheme; when the reference names a port, it equals the entry's port, explicit or default; and when the reference carries an "api" hint, it equals the entry's api member. The connection uses the selected entry's port. If no entry matches, resolution fails; a client MUST NOT substitute another transport, port, or dialect. A client MUST ignore unrecognized members and MUST NOT use a document whose llmns version it does not implement.
References appear in logs, shell history, error messages, and stack traces. A reference MUST NOT contain a credential value; the credential component is a name.
Credential resolution happens in the client, never on the wire. A client maintains a credential store with two kinds of entries. A (host, name) entry is keyed by the normalized host (Section 4) and a name; it MUST NOT be shared between hosts. A realm entry is keyed by a realm and carries the set of normalized hosts it applies to. The operator fixes that set when storing the credential; the client MUST NOT extend it on a host's own assertion. A well-known document names a realm, it does not prove membership: a client that presented a realm credential to every host naming the realm would hand one provider's secret to any host that claims the realm name.
When an endpoints entry is selected (Section 6), the client selects the secret in this order:
When the document is unavailable and no endpoints entry is selected, steps 1, 3, and 5 do not apply: the client presents the (host, name) entry when the reference names a credential, and resolution fails when that entry does not exist; otherwise it presents the (host, "default") entry when one exists; otherwise it presents no credential, and the host decides whether to accept the request. The storage mechanism (an environment variable, a keychain, a configuration file) is implementation-defined. The auth object states how the resolved secret is presented to the host; the secret itself never appears in a reference or in the well-known document.
Schemes without the "s" suffix transmit in cleartext, including any credential the client presents, and a well-known document retrieved without TLS can be modified in transit. Plaintext transports SHOULD be restricted to loopback and private networks.
The pin component follows the tag and digest addressing of container image references. The "+transport" suffix follows established composite scheme names such as "git+ssh". The remaining syntax is that of the generic URI [RFC3986].