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 25 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]. The rules host, port, pchar, query, 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*( pchar / "/" ) ; no unencoded "@"
pin = kind ":" value
kind = "name" / "hash" / "version"
value = 1*( pchar / "/" )
hints = query
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 "@" that separates the model from the pin is the first unencoded "@" in the path; a literal "@" within a model identifier MUST be percent-encoded as "%40".
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
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 denote the same model if and only if their normalized (host, model, pin) triples are equal. Normalization lowercases the host; the port, when present, is part of the host component. The model and pin components, including the pin kind, are compared octet by octet and MUST NOT be altered.
The credential, the hints, the transport, and the use of TLS do not contribute to identity. For example, llms://work@api.openai.com/gpt-5 and llm+grpc://api.openai.com/gpt-5 denote the same model.
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 one. A hint MUST NOT name a dialect the host does not serve.
Resolution yields an endpoint, an API dialect, and a credential requirement. 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, at the host and port of the reference, with TLS as selected by the "s" suffix; the "+transport" suffix does not apply to this retrieval. If the host does not answer HTTP on that port (for example, a port serving only gRPC), the document is unavailable and the hints of Section 5 apply. Example:
{
"llmns": 1,
"endpoints": [
{ "api": "openai", "transport": "http", "tls": true,
"path": "/v1" },
{ "api": "openai", "transport": "grpc", "tls": true,
"port": 8001 }
],
"auth": { "scheme": "bearer" },
"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 a REQUIRED scheme member ("bearer", "header", or "none") and, when the scheme is "header", a REQUIRED header member naming the header, for example "x-api-key". A models entry has a REQUIRED model member, identical octet for octet to the model component of a reference, 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 hashes. 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. Every hash that appears as a value MUST also be listed in the hash member.
A client selects the endpoints entry whose transport and TLS mode match the reference scheme. If no entry matches, resolution fails; a client MUST NOT substitute another transport. 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 that maps a (host, credential name) pair to a secret. The client resolves the credential component against this store, scoped to the host of the reference; a name MUST NOT select a secret stored for a different host. When the credential component is absent, the client uses the store's default entry for the host, when one exists. The storage mechanism (an environment variable, a keychain, a configuration file) is implementation-defined. The auth member of the well-known document (Section 6) states only how the resolved secret is presented to the host.
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].