Documentation Index
Fetch the complete documentation index at: https://docs.getbindu.com/llms.txt
Use this file to discover all available pages before exploring further.
Budget about 20 minutes to go from
git clone to a signed message landing in the right rail. No prior bindu knowledge required — every step in the next chapter explains what it does and what you should see.context_id. Signatures are verified inline so you can see whether a peer is actually who it claims to be. It’s an operator console — for you, your auditor, and your future self trying to figure out what went wrong at 2am.
The roadmap
What's in this section
The five processes that make the inbox tick, and why each one is there.
Quickstart
Five steps. One persona. Two demo peers. One signed message.
Verify the auth
Prove from your terminal that calls really are signed and authed.
Using the inbox
Layout, sending, reading a thread, replying.
Troubleshooting
Common boot failures and the env knobs that fix them.
Why this exists
Most agent frameworks treat the wire as someone else’s problem. You write a handler, youPOST to it, you hope it returns. If something goes wrong — wrong signer, expired token, a peer that lied about its DID — you get a stack trace and you start grepping logs across three machines.
The inbox flips that. It treats every A2A message as a first-class object with:
- A state pill —
submitted·working·input-required·payment-required·auth-required·completed·failed. - A trust pill —
first-contact(new peer) ·known·self(your own agents / planner). - A DID of the counterparty — click for the full agent card.
- The canonical body that was signed, the signature, and the timestamp nonce — all verifiable inline.
publicKeyBase58 — same code path a hostile peer would face on the wire.
What ends up running
By the time you finish the quickstart, five things will be alive on your machine:| Port | Process | What it does |
|---|---|---|
3775 | Vite dev server | The React UI you open in your browser. |
3787 | Hono API (server/index.ts) | SQLite event store, webhook intake, outbound A2A composer. |
<auto> (e.g. 5xxxx) | Your personal agent (Python, spawned on demand) | Your DID + Hydra OAuth client. Listens for inbound A2A and signs everything you send. |
5773 + 5776 | Demo peers (joke + poet) | Two example agents to talk to. Optional — bring your own if you have them. |
3774 | Gateway (optional) | The planner. Only spawns when you message ≥2 agents at once. |
What “auth on” means here
There are three independent auth layers in play. The inbox uses all three:| Layer | Who enforces it | Default |
|---|---|---|
| Peer A2A auth — outbound calls must carry a JWT + DID signature | The peer’s bindufy middleware (-32009 if missing) | On |
Operator gate — /api/* on the inbox requires a bearer token | inbox/server/index.ts | Off (single-user dev) |
| Webhook gate — agents POSTing back must carry a bearer token | inbox/server/index.ts | Off |
What the inbox is not
It's not a CRM
It's not a CRM
Threads are grouped by
context_id, not by contact. The same peer can show up in dozens of unrelated threads and the inbox treats each one independently.It doesn't host agents
It doesn't host agents
Your personal agent runs as a separate Python process the inbox spawns on demand. Demo peers and any peer you add run wherever they run. The inbox is the observer.
It's not multi-user yet
It's not multi-user yet
Single operator, single machine.
BINDU_COMMS_TOKEN is a gate for sharing the URL with a teammate; full SSO is on the roadmap.What you’ll have by the end
An identity
Your operator DID (
did:bindu:<author>:<persona>:<uuid>), an Ed25519 keypair on disk, and a Hydra OAuth client registered to that DID.Two peers
joke_agent and poet_agent running locally with AUTH__ENABLED=true — same auth shape as a production bindufy agent.A verified thread
A
Sent row, an Inbox reply, both signed, both verified, both threaded under the same context_id.