Register an extension
Makes a program at an HTTPS address a principal of this home: it may then observe the event stream, transform what the agent assembles, and occupy the slots it claims. This response carries the registration’s secret, and it is not stored anywhere a read can reach — a caller that loses it rotates rather than re-reads. Requires extensions:manage, which is what “the home’s owner” means in the mechanism; an ordinary member is answered 403 NRY-0028.
The endpoint must be https:// with no exception, loopback included, and the address it resolves to is judged before anything is stored: a loopback or private address is refused unless an operator wrote that range into this host’s configuration, and a link-local, metadata, unspecified, multicast or NAT64-wrapped address is refused with no configuration able to admit it. A second claimant on an exclusive slot is answered 409 NRY-0006 naming the one that already holds it — unless this host’s [extensions] prefer configuration already names one of the two contesting registrations as that slot’s winner. That entry is the explicit tie-break, and it is the only thing that admits a second claimant here: without it, no winner may be picked implicitly, so the registration is refused. Where it is present the second registration is stored, the named registration occupies the slot, and the other one stays registered, stays enabled, keeps every other slot it claims and simply stops occupying the contested one. Revoking the occupant returns the slot to the survivor.
A slot this write claims is stored CLAIMED AND UNSERVED (a model-supplier given models in this body serves them already), and this write reaches the endpoint NOT AT ALL. A discovery call made here would be signed under the secret this response has not handed over yet. Register in ONE write, take the secret from this response, configure the far side with it, and send refreshModels: true. On an enabled row — which is what this write leaves behind unless it asked for otherwise — that update reads /models under a secret both sides hold by then, and is the same road that re-reads the list afterwards.
Until that read the slot is claimed and offers no model. It is in slots, models is ABSENT — the property is omitted from the response rather than served as an empty array — and no picker, no turn and no spend ceiling can select anything from it: the catalogue skips a claimed-and-unserved row exactly as it skips a disabled one, so nothing half-registered is selectable. What this write still decides is everything this home can decide alone — the arity above, and a 409 for a supplier whose models would answer under a provider name this host’s catalogue already carries. Stating models on this write is the one way to register a supplier already serving, because those are on the row rather than at the far side.
A tool-server slot is stored the same way, for the same reason. The /tools listing a tool name is judged against would be signed under that same unhanded secret, so it is not read here either. The listing is read on the first write that follows under a secret both sides hold — a change whose resulting row is enabled and that moves the endpoint or claims the slot — and on the tool sweep’s own clock regardless. Until a list is read this home serves none of that registration’s tools, and a name it would contest is refused on the write that reads it rather than on this one.
An operator install rides this same operation under the plane’s operator credential rather than a token carrying extensions:manage. A home holding no operator credential — every BYOC and every local deployment — cannot authenticate such a caller at all.
Authorizations
Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.
Body
A request to make a program at an address a principal of this home.
Namespaced name, publisher/extension form.
^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$Where this host calls it. https:// with no exception, loopback included — a developer terminating TLS locally is one command, and a leaked secret is not one command back.
500The decision points to sit on.
The slots to occupy. A slot claimed here is stored CLAIMED AND UNSERVED (a model-supplier given models in this body serves them already): this write reaches the endpoint not at all, because a call made here would be signed under a secret the caller has not been given yet. For model-supplier, send refreshModels: true once the far side holds the secret and the list is read on that update so long as the row it produces is enabled; until it is read, the slot offers no model to any turn. For tool-server, this registration reads no /tools listing: the first LATER update whose resulting row is enabled and that moves the endpoint, newly claims the slot or switches on a row already holding it reads it, and so does the tool sweep on its own clock; until it is read this home serves none of that registration's tools, and a tool name this home already holds is refused on the update that reads the listing.
Where in the ordered pipeline. Defaults to 0.
Permission slugs to grant ON this registration.
What this extension serves, if it occupies a supplier slot. Stating it here is the one way to register a supplier already SERVING, because these are on the row rather than at the far side. Leaving it out stores the slot claimed and unserved until an enabled update carrying refreshModels, or one moving the endpoint, reads the endpoint's catalogue.
Whether it starts enabled. Defaults to true.
Response
The registration, with its secret. The secret appears here and in the rotation's response and nowhere else, ever.
A registration and the secret it was minted with. The only other response in this contract that carries a secret is the rotation's.
An extension this host carries: a program this home REGISTERED at an HTTPS address. Never its secret, on any response that uses this schema.
package is absent on a registered extension, which has no package — it is another deployment rather than anything installed here.
The shared secret, shown exactly once. The host signs its outbound calls under it and so does the extension when it calls back. It is stored sealed and no read path in this contract can produce it again; a caller that loses it rotates.