Approval and Holds

A fleet admits new members either automatically or by hand. Switching to by-hand makes minting a node and letting it talk to its siblings two separate decisions, each with a name against it. All four steps below are control-plane calls to POST https://graph.whisper.online/api/query with an X-API-Key header.

1. Require admission by hand

CALL whisper.agents({
  op: 'policy',
  args: { whale: { approval: 'manual' } } })

The setting is sticky: it stays until you change it. auto, automatic and open all mean admit on mint; manual, approve and approval all mean wait for a person. Because a whale argument is present, this call takes the dns:whale:write scope, which is never granted automatically. See keys and scopes.

A node minted while this is set still holds its /128, resolves, publishes its name and reaches the internet. Only reachability to its siblings waits.

2. See which nodes are waiting

CALL whisper.agents({
  op: 'list',
  args: { kind: 'whale' } })

Each row carries agent, address, tags, reusable, ephemeral, approved, east_west, connects, approved_by, approved_at and created_at. Read east_west: it says admitted or pending_approval. approved_by and approved_at are the audit trail, which is the reason to admit through this path rather than by flipping the fleet to automatic for a minute.

3. Admit one node

CALL whisper.agents({
  op: 'firewall',
  args: { agent: 'ae3b051ff3bf7f478',
    whale: { op: 'approve', reason: 'change 4821' } } })

Name the node with either agent or address. admit and allow are accepted spellings of approve. The reason is trimmed and stored with the admission, so keep it short and make it something you will recognise later: a change number, a ticket, a person.

The reply row carries the same fields as the list above, so the east_west value in the response is your confirmation. To mint a node that is admitted from the start, without a second call, pass preapproved in the whale map at register.

4. Put a live node on hold

CALL whisper.agents({
  op: 'firewall',
  args: { address: '2a04:2a01:b69a:6717:e3b0:51ff:3bf7:f478',
    whale: { op: 'deny', reason: 'triage' } } })

deny unbinds a node that is live. revoke, hold and unapprove are accepted spellings of the same thing, and a deny wins over anything that would otherwise admit the node. Use this when you want a member off its siblings while you look at it, and to put it back, call approve again with a fresh reason.

To read one node's state without changing it, send whale: { op: 'status' } with the same agent or address.

Which containment to reach for

A hold is not the same act as ending an identity.

Narrowing which of your members may reach which, as a standing rule rather than a decision about one node, is the access document instead.