# Brine hub, for agents The hub is at https://hub.brine.systems. Everything a person does there, an agent can do over HTTP with no human in the loop, except RUNNING JOBS, which uses the hub's WebSocket protocol through the Python client (brine.hubclient, `python -m brine agent`): OpenAPI cannot describe it. Machine-readable API: https://hub.brine.systems/v1/openapi.json (generated from the same route table as this text). ## 1. Register an account (no email, no person) a. Make a DID (Ed25519 did:key; brine.identity.Identity()) and a key: `brk_` + 24+ random url-safe bytes. Keep the key; send only its sha256. b. GET /v1/nonce -> {nonce, aud}. c. POST /v1/accounts/agent {"msg": } name is 1-40 characters of A-Z a-z 0-9 space _ . - (no @). Add ?dry_run=1 to check the limits and the name and create nothing. The answer has your account id, a 24 hour agent cert and the hub's public keys. Your DID holds run, read, pair and admin; the key's cap is 50 credits a month. A retry with the same DID and key_hash and a NEW nonce returns the same account. Limits: 5 accounts per IP per day and a global daily cap. ## 2. Sign every read, pair and admin call A read, pair or admin call carries `Authorization: Bearer brk_...` and a header `Brine-Signature`: a document signed by a DID that holds the scope, {type: "http.request", method, path_and_query (the query is signed too, so ?dry_run=1 is covered), body_sha256 (hex sha256 of the body bytes, of the empty string for no body), aud (the hub origin, https://hub.brine.systems), nonce (from GET /v1/nonce, single use, 2 minutes), iat (seconds)} plus the usual `from` (your did:key), `id`, `spec` and `sig` that brine.identity.Identity.sign() adds. The header value is that document as JSON (or its base64url). Errors are JSON {ok: false, error, detail?}; the codes are listed below and in openapi.json. ## 3. Pair a machine with no browser and no email On the machine: the node app's control API (loopback, bearer token in /control.json): node POST /v1/signin (no body) -> {url, code}; the pair id is the last path segment of url (or read pairing.code from GET /v1/status later) hub POST /v1/pair/{pair_id}/approve {"code": code} (scope pair, signed; five wrong codes kill the pair id; ?dry_run=1 checks) node POST /v1/pair/confirm -> the machine is on your account A person pairs differently (the app opens their browser, or they type an email in the app); neither an email-mode nor a browser-mode pairing can be approved this way. ## 4. Run jobs Jobs on a machine of your OWN account need no balance (they only count against the key's monthly cap). Use the Python client: BRINE_AGENT_KEY=brk_... python -m brine agent --hub https://hub.brine.systems --state ./agent-state fulfil intent.json or the library, brine.hubclient.HubAgent. The key comes from $BRINE_AGENT_KEY, --key-file or stdin, never an argument. Progress while a slow node works (exec.progress, opt in with `progress: 1` on the exec.request): A node that is slow to start (a first job can fetch a runtime add-on and a model: minutes) tells you it is alive with `exec.progress` {execution_id, seq, stage: runtime|model|starting|running, bytes, total}, signed by the node, relayed by the hub to the connection that sent the request. It only sends them if your `exec.request` carries `"progress": 1` (exactly the number 1); without it you get none and your own timeout is the only judge. Each one restarts your idle timeout; `seq` rises, ignore one that is not newer. It is a sign of life, never a result: it moves no money. The hub's ack to a relayed `exec.request` carries `exp` (unix seconds): when the hold closes, so stop waiting a minute before it. brine.hubclient does all of this for you. ## 5. Read and manage the account GET /v1/account (read): machines, keys with scopes and spend, credits (spendable, grant, grant_earned, earned and spent by day), the latest ledger entries and jobs, limits. POST /v1/agents (admin): add a key with a subset of your scopes and a cap no higher than yours; name the DID that will hold scopes beyond run. POST /v1/agents/{id} (edit), DELETE /v1/agents/{id} (revoke), DELETE /v1/machines/{did} (admin). POST /v1/agents/{id}/dids {did, proof, scopes?} (admin): bind another identity to a key. `proof` is signed BY THAT DID: {type: "agent.did.add", agent: , aud, nonce}. An account holds at most 10 keys. Revoking the last admin key of an unclaimed account is refused (409 last_admin). DELETE /v1/account?confirm=delete (admin) deletes an UNCLAIMED agent account. ## 6. Hand the account to a person (claim) POST /v1/account/claim-token (admin) -> {token, url}. Give the url to the person: they type an address, open the emailed link IN THE SAME BROWSER, choose Keep or Remove for every machine and key (default Remove) and press Claim. The address is attached to THIS account (never a second one); an address that already has an account is refused. After a claim every admin drops to run, read, pair until the person grants admin again. ## Limits for agent and claimed accounts without paid history (human accounts are unchanged) 2,000 relays a day per account and a global daily budget (daily_limit / busy with Retry-After); 256 MiB of upload and 256 MiB of download a day; every key's cap at most 50 credits a month. Paid history: at least 3 captures of at least 1 credit as payer toward other accounts, from a human or claimed account. ## 7. Be added by a person's phone (no key to copy) Instead of a person creating a key in the dashboard and handing it to you: `python -m brine agent --hub https://hub.brine.systems --state ./agent-state --link serve`. By hand: make a DID, POST /v1/links {"kind": "agent", "did", "name", "agent_name"} -> {id, poll_secret, url, fp, expires_at}; draw `url` as a QR on YOUR screen (brine.qr.terminal(url)); the person signs in on their phone, opens Dashboard -> Scan, scans it and presses Approve ("Add an agent called ?"). Poll POST /v1/links/{id}/claim {poll_secret}: 202 pending, then 200 once with {api_key, agent, owner}; bind your DID with that key as usual (run scope, cap 10 credits a month). A code lives 15 minutes; ask for a new one. Nothing a phone holds moves to you, and nobody can approve through the API: only a signed-in person's browser. ## Smoke test scripts/hub_smoke.py --hub https://hub.brine.systems registers SALT-smoke-, pairs a scratch node, runs text.normalize, checks the ledger, unpairs and deletes the account. ## Routes GET /v1/openapi.json (no auth) This API as OpenAPI 3, generated from the hub's route table, with the signing scheme and the error enum. GET /v1/nonce (no auth) A single-use nonce for a signed request (good for 2 minutes; throttled per IP). GET /v1/keys (no auth) The hub's public key set {kid: did} that certificates are signed under. GET /v1/agents/bind/nonce (no auth) A nonce for `POST /v1/agents/bind` (same as `GET /v1/nonce`). POST /v1/agents/bind (no auth) Bind a DID to an agent key: the key plus a message signed by the DID `{type: agent.bind, key_hash, aud, nonce}`. POST /v1/accounts/agent (no auth) An agent registers its own account. POST /v1/links (no auth) Ask a person to add THIS agent by scan (`python -m brine agent --link` does it). POST /v1/links/{id}/claim (no auth) Poll a scan request with its `poll_secret`. POST /v1/agents (signed, scope admin) Add a key. POST /v1/agents/{id} (signed, scope admin) Change a key's cap and/or scopes, bounded exactly like creating one. DELETE /v1/agents/{id} (signed, scope admin) Revoke a key, every DID bound to it, and close their connections. POST /v1/pair/{id}/approve (signed, scope pair) Approve a pairing, as a person pressing "Pair this machine" does. GET /v1/account (signed, scope read) The account as data: machines, keys (name, scopes, cap, spend this month, DIDs), credits (spendable, grant, grant_earned, held, earned and spent by day), the latest ledger entries and the latest jobs (holds, with their state), the account's `kind` and its limits. DELETE /v1/machines/{did} (signed, scope admin) Unpair a machine of this account (revokes its certificate and closes its connection). DELETE /v1/account (signed, scope admin) Delete the account: revokes its machines and keys and forfeits its credits. POST /v1/account/claim-token (signed, scope admin) Make a one-time token (24 hours, shown only here) for a PERSON to attach their email to this unclaimed agent account: give the person `url`; they open it, type their address, press the link in the email IN THE SAME BROWSER, review every machine and key on the account (Keep or Remove, default Remove) and press Claim. POST /v1/agents/{id}/dids (signed, scope admin) Bind a DID to a key now, with `scopes` (a subset of the acting DID's and the key's). ## Errors {ok: false, error, detail?} bad_nonce (HTTP 401) The nonce is unknown, expired or already used. Get a fresh one from `GET /v1/nonce`. bad_request (HTTP 400) The body, a field or the query is missing or malformed. `detail` says which. bad_signature (HTTP 401) The `Brine-Signature` header is missing or does not verify, or does not cover this request (method, path and query, body hash, aud, iat). busy (HTTP 503) The hub is busy (storage contention, or the global free-account budget for today is used). See `Retry-After`. cap_too_high (HTTP 403) The cap is above the acting key's cap, or above the 50 credit limit of an account without paid history. conflict (HTTP 409) The account changed while the call ran (it was claimed, or another admin change won the race). Nothing was applied: read the account and decide again. cookies_refused (HTTP 400) A request to a key-and-signature route carried a hub cookie. Send no cookies. daily_limit (HTTP 429) The account's daily limit is used up. See `Retry-After` (seconds to the next UTC day). did_in_use (HTTP 409) That DID is already bound (to this or another key). email_in_use (HTTP 409) That address already belongs to an account. Merging accounts is not supported. forbidden (HTTP 403) The signing DID does not hold the scope this route needs (`detail`: the scope), or the action is not allowed for this account. gone (HTTP 410) The pair id, claim token or link has expired or is used up. key_in_use (HTTP 409) That key hash already belongs to another DID. last_admin (HTTP 409) That would leave an unclaimed agent account with no admin key. machine_offline (HTTP 409) The machine that asked to pair is not connected any more. Start again on the machine. method_not_allowed (HTTP 405) The path exists but not for this method. not_found (HTTP 404) No such thing in this account (a thing that is not yours looks the same). pair_dead (HTTP 410) The pair id has had five wrong codes, or has expired or been used. scope_too_wide (HTTP 403) The scopes asked for are not a subset of the acting DID's scopes (or of the key's). throttled (HTTP 429) Too many calls from here. See `Retry-After`. too_many_dids (HTTP 409) A key holds at most 5 active DIDs. too_many_keys (HTTP 409) An account holds at most 10 active keys. unauthorized (HTTP 401) No bearer key, or the key is unknown, revoked, or its account is gone. wrong_code (HTTP 403) The pairing code is wrong. Five wrong codes kill the pair id.