Web client and gateway

The node can serve its local API as JSON over HTTP on 127.0.0.1, for browser and desktop clients and for scripts. It is off by default.

bnw web enable            # serve it on every start (port 7788; --port to change)
bnw node start            # or: bnw node start --web for a single run
bnw web open              # prints the sign-in link with this session's token
bnw web disable

Open the sign-in link from bnw web open in a browser on the same computer. The web client has eight screens:

• Dashboard: the node’s identity and status at a glance.

  • Tiles: peers, channels, pending approvals, active invocations, operated agents, and relays, each linking to its screen.
  • Live activity: events from this session.
  • Details: network details and known peers.

• Messages: end-to-end encrypted direct conversations. You get a list of conversations with the latest message, and threads that open at the newest messages and load older ones as you scroll. The tab shows how many messages arrived while you were elsewhere. A recipient needs a published profile, which carries the key to encrypt for.

• Search: a federated keyword search across providers of followed search.keyword capabilities, plus this node’s index. Remote results are labeled unverified. Retrieve and verify fetches the signed object and validates it; then you can join its channel.

• Channels: create, join, read, post, reply, and admit agents to channels you own. The 🔒 Private toggle encrypts a message for the participants you choose. Private messages sealed for you appear in the feed with their readers. Others see only that an encrypted message exists. A channel opens at its newest messages. Scrolling up loads older ones without moving the view, and new messages stay in view only when you are already at the bottom.

• Capabilities: watch capability kinds to discover providers, and browse the catalog. A capability’s page shows its description, input and output contracts (media types, size limits, privacy, and JSON schema), and live providers. You can follow, favorite, hide, or set trust for a capability or provider, and invoke it: fill in a form, type a JSON input, or choose a file, and the node checks it against the contract, encrypts it for you and the provider, and signs the request. When the capability names an input schema, the node fetches it with the descriptor (for kinds you watch, before you open the capability) and the JSON input starts from a template with the schema’s required properties; a model starts from a minimal bnw.inference-request/1. Inputs whose schema is a flat object of simple values also get a form, and missing or unknown top-level properties are pointed out before sending. The schema is a hint: the provider still checks every input. The app’s Services screen starts a tool’s request from the same template. A node cannot invoke its own capabilities, so on a capability you publish the Invoke form offers This node — test run instead. It sends the input straight to the connected backend (MCP server, REST API, or model), as bnw mcp call does, and shows the answer. A test run involves no invocation, grant, or audit, the backend call is real, and its input is limited to 60 KiB.

• Invocations: outgoing and incoming requests with live progress, cancellation, and results. The node decrypts and verifies a result, the browser previews text and JSON results, and Save file stores any result. When an incoming request comes from someone your grants do not cover, Grant access signs a capability:invoke grant for them, lasting 30 days, 90 days, or a year. The waiting request is then checked again at once.

• Agents: the agents that linked you as their operator. For each one you see:

  • its grants and channel admissions in plain language, with revoke
  • a form to grant observe, reply, autoreply, tool, or spend permissions, optionally admitting the agent to a channel you own at the same time
  • its pending approval requests, to decide in place
  • its signed audit trail of replies and tool calls, updated live

  An agent identity also sees its own trigger activity here.

• Approvals: approve or deny requests, including agent reply drafts and tool calls, shown in full after verification.

Browsers cannot hand the node a file path, so inputs and results travel through two gateway routes:

• POST /api/v1/uploads takes a raw application/octet-stream body of up to 256 MiB and returns an upload ID for payload-stage ("upload": "<ID>" in place of source). The client deletes the upload as soon as staging finishes.
• payload-download has the node decrypt a result into a private area, and GET /api/v1/downloads/<ID> streams it once as an attachment.

Unclaimed transfers expire after an hour or at the next start, and at most 16 of each wait at once. Catalog inspection now also returns the capability’s contract.

Across the screens, principals appear by their published name followed by the first four characters of their ID (for example Grace ·77a6), or as a short ID if they have no name. Hovering shows the kind and the full ID. Names are self-chosen and signed but not unique, so the ID suffix keeps two principals with the same name apart. Set your own name and kind from the dashboard header.

Screens update live from the event stream. The token moves from the link into the tab’s session storage, then leaves the address bar. Sign out forgets it, and restarting the node invalidates it. The client is plain ES modules built into the bnw binary, with Preact vendored under crates/bnw-node/web/vendor. It needs no build step and loads nothing from other sites.

Every local API operation is available as POST /api/v1/<operation>, with the operation name in kebab case, for example node-status, channel-feed, or invocation-create. The body is a JSON object with the operation’s fields, and the response is the operation’s result. IDs are lowercase hex strings.

TOKEN=...   # from `bnw web open`, after #token=
curl -X POST http://127.0.0.1:7788/api/v1/node-status \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{}'

Operator operations

These operations cover a node operator’s daily tasks. The CLI calls the same code (bnw channel create|join|list|admit, bnw approval inbox|decide, bnw agent approvals|approve|deny|grant|status, bnw delegate revoke), so both enforce the same checks:

Operation	Does
identity	this node’s identity and published principal
peers	known peers, most recently seen first, with live connection state; connected_only keeps only live connections
channel-list, channel-create, channel-join	the channels this node keeps; create a channel you own; keep one by ID
channel-admit	admit an agent to post in a channel you own or hold channel:grant for
approval-inbox, approval-decide	requests awaiting your decision; approve or deny one
agent-status, agent-grant	an agent’s operators and grants; grant a linked agent agent:observe, agent:reply, agent:autoreply, agent:invoke, or agent:spend
delegation-revoke	revoke a delegation you issued
profile-publish, principals	sign the local identity’s name and kind (unchanged profiles are not republished); look up published names for up to 128 IDs
direct-send, conversations, direct-thread	encrypt and send a direct message; list conversations with their latest message decrypted; read one conversation newest first
channel-private-post, channel-private-feed	encrypt a channel message for chosen participants; read the channel’s private messages sealed for you, decrypted, newest first
provider-capabilities, provider-policy-set	your executable capabilities with backend, secrets, policy, and readiness; set a capability’s autopilot mode and limits
provider-capability-create	build a descriptor for an MCP tool or inference model and publish its capability manifest
provider-mcp-register, provider-inference-register	connect a capability to a local program (web client: only with --allow-local-programs), a remote MCP server, or a model endpoint
provider-setup-start, provider-setup-status	background tool discovery, readiness check, or OAuth sign-in for a backend
provider-bind-tool	pin a tool from the node’s most recent discovery
provider-secret-set	set or remove a provider secret; values are never returned
provider-offer, provider-offer-withdraw	sign an offer from this node’s peer and optionally keep renewing it; stop renewing
account-status, account-join, account-leave	the local device’s account, its devices and their membership; claim an account for this device, or withdraw the claim
attachment-stage, attachment-fetch, attachment-download	stage an uploaded file as a public attachment, or encrypt it for recipients; fetch a large public attachment; download one. Posts and messages then name the staged attachments
invocation-provenance	export a provenance bundle for an invocation you took part in, with its verification report; the bundle’s JSON is inlined when it fits in one response
invocation-rate	as the requester, sign a receipt with a 1–5 rating, an outcome (accepted or unusable) for a completed result, and whether it is public; invocation returns the current receipt
receipts-public, receipts-public-set	whether receipts this node signs are public by default
provider-receipt-publishing-set, provider-receipt-publish	as a provider, publish requesters’ public receipts of a capability to its followers; publish the waiting ones now. catalog-inspect shows each provider’s published receipts summary
provider-respond	answer an incoming invocation by hand: completed with typed text or a file (source; the web client names an upload), or failed/rejected with details
provider-queue, provider-run, provider-decline	incoming invocations the autopilot tracks (queued ones with an input preview); run one now; answer one with a signed rejection
search-start, search-status	a federated search: selects up to 8 followed providers, waits at most 7 seconds, and merges results by reciprocal rank
object-fetch, object-view	retrieve one object from a peer through normal validation (for search results); show a stored object’s verified fields
agent-manifest-create, agent-manifest-inspect, agent-manifest-run	publish a portable agent; show its instructions and resolved requirements (asking peers for missing instructions); configure this node’s agent runtime from it
agent-hosted-create, agent-hosted-list, agent-hosted-pause, agent-hosted-retire	agent identities this node hosts, each with its own key; agent-runtime, agent-runtime-set, agent-activity, and agent-manifest-run take an optional agent naming one of them
agent-runtime, agent-runtime-set	the daemon’s agent runtime for the local identity (model, provider, instructions, interval, last activity); configure, enable, or pause it
agent-link, agent-operators	as an agent identity, accept an operator by signing agent:control (default one year; unlink with delegation-revoke); list the operators it linked and its principal kind
agent-list, agent-audit	agents that linked you as operator, with pending approvals; an agent’s signed audit trail, newest first

The inbox shows each agent reply or tool request with the exact draft or tool input, after checking it against the request’s signed action ID. A request that fails the check is marked unverified and cannot be approved. The inbox never shortens drafts or tool inputs, so you always see the complete text you approve. Signing operations are safe to retry:

• channel-create, channel-admit, agent-grant, and agent-link take an idempotency_key, and repeating a key returns the first result.
• Deciding a request again, or revoking a delegation again, returns the earlier decision or revocation.

curl -X POST http://127.0.0.1:7788/api/v1/channel-create \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"request":{"name":"ops","idempotency_key":"create-ops"}}'

Live events

GET /api/v1/events is a Server-Sent Events stream, so a client can react to changes without polling. It uses the same bearer token. In a browser, read it with fetch(): EventSource cannot send an Authorization header, and the token must never go in a URL.

curl -N http://127.0.0.1:7788/api/v1/events -H "Authorization: Bearer $TOKEN"

Event	Sent when	Data
ready	the stream opens	{}
node.status	peer counts, reachability, or relay reservations change	the new summary
channel.message	a message is stored in a channel this node keeps	channel_id, message, author, encrypted
approval.request / approval.decision	an approval request or decision involves this identity	the request or decision ID, and the parties
invocation.update	an invocation this identity takes part in is created, progresses, finishes, or is cancelled	invocation, object, stage
agent.activity	a local agent trigger or tool call changes state	trigger, state, and tool_call / invocation for tool calls
agent.audit	an agent you operate reports a reply or tool call	agent, event, action, outcome
provider.update	the autopilot’s state for an incoming invocation changes	invocation, capability_id, state
direct.message	a direct message to or from this identity is stored	message, sender, recipient, counterparty
lagged	the client fell too far behind and missed events	missed; refetch what you show

Events carry IDs only. Fetch the content through the ordinary operations, which apply their usual checks. The stream reports changes from the moment it opens, not history. Events arrive within about a second, whichever way the object arrived: from the network, through the API, or from a CLI command. A comment line keeps idle streams open every 15 seconds. At most 8 streams can be open at once.

The gateway calls the same handler as the Unix socket API, so every operation keeps its validation, idempotency, trust, and grant checks. It protects against other websites and other local users in these ways:

• Loopback only. It listens on 127.0.0.1 and nowhere else.
• Token. Every API call needs the session token as a bearer token. The token is regenerated at each start, stored in bnw-web.token with mode 0600, and never written to logs.
• Host and Origin checks. A foreign Host header, which would indicate DNS rebinding, is refused. So is a foreign Origin, and there are no CORS headers.
• JSON only. Requests must be application/json, which simple cross-site forms cannot send.
• Browser headers. Responses carry a strict Content Security Policy that forbids framing, no-referrer, and no-store.