Nodes, Names and Tags

A node is anything that holds a Whalenet /128: a server, a container, or an agent that lives for the length of one job. A node is minted. The control plane draws the address, publishes the records that make it verifiable, and hands back the credential the node will use.

Minting is one control-plane call. The whale sub-map on args is the intent that makes the new principal a fleet member; there is no separate whale operation.

CALL whisper.agents({
  op: 'register',
  args: { label: 'build-runner-7',
    whale: { hostname: 'build-runner-7', tags: ['tag:ci', 'tag:prod'], reusable: false } } })

reusable: false mints a single-use credential, which is what you want for a machine that is built once. Send the call to POST https://graph.whisper.online/api/query with an X-API-Key header; the request envelope has the body shape and the columns every reply carries. The reply for a fleet member returns api_key, agent, address, fqdn, ptr, doh_url, resolver_ip, member and member_published. The api_key is shown once. Capture it before you close the shell, and treat the doh_url as a password, because the device credential is in its path. Mint an identity covers the rest of the operation.

The two names

The canonical name is a<hex>.t<tenant>.agents.whisper.online, where the label is a pure function of the address. It is published when the node is minted and withdrawn with it, so the name and the identity can never disagree. Why the address is the identity, and what a third party can check about it, is the address as identity.

The member name is an optional second name you choose with whale.hostname: one DNS label of lower-case letters, digits and hyphens, published as a friendly alias for the canonical one. Pass publish_name: false to decline it and leave only the canonical name; read member_published rather than looking for an empty member. Neither name is editable through the records API, so to change one, rename or release the agent that holds it.

Tags

A tag is written tag:<label>. Tags are canonicalised to lower case, de-duplicated and sorted, and they are minted with the node at register. A node may restate the same tags when it connects, but it cannot change them: a restatement that differs comes back as a 400. That is what lets the access document name a set of machines by role and trust the answer.

Two more shapes the control plane refuses, both as a 400: a whale intent alongside fleet: true or device: true, and tags alongside an expiry argument. A credential minted as single-use answers 409 CREDENTIAL_SPENT on a second attempt, which is the point of minting it that way for a build runner.

What a fresh node already has

A node that has been minted resolves, publishes its own name, holds its /128, and reaches the internet through it. What it waits for, when the fleet is set to admit members by hand, is reachability to its siblings: see approval and holds. To read the roster back, including each node's tags and admission state, use read your fleet with {kind: 'whale'}.