Skip to main content
By now your personal agent is alive, two demo peers are listed under Contacts, and you’ve sent one signed message. This chapter is the user manual for everything you’ll do after that.

​
Layout

PaneWhat it shows
LeftFolders (Inbox / Sent / Drafts / Archive), Contacts grouped into Gateways (orchestrators for multi-agent plans) and Agents (single-purpose peers). Your operator identity sits at the bottom.
MiddleThread list — newest first, one row per context_id. The badge is the message count.
RightSelected thread, oldest message at top. State pills + DID per row; bodies render inline. Reply composer pinned at the bottom.
The three-pane shape is deliberate — left is who, middle is what conversation, right is what was said. You can navigate the entire thing with one hand.

​
Sending

Click Compose at the top of the sidebar. The recipient picker drives the path:

One agent

Direct A2A message/send to that peer. No planner involved. The fastest path — round-trip is just inbox → peer → webhook back to inbox.

Two or more agents

Comms auto-spawns a gateway (see gateway-spawned-* in Contacts), forwards your prompt as a plan, threads the per-agent tool calls under one context_id.
The gateway’s /plan endpoint is bearer-gated. The inbox auto-loads GATEWAY_API_KEY from gateway/.env.local if it’s there. If you didn’t set one, multi-agent compose 401s — single-agent still works.
⌘↵ sends. The composer closes; the row appears in Sent.

​
Reading a thread

Click a thread in the middle pane. The right rail opens with the oldest message at the top. Each row carries:
  • State pill — submitted · working · input-required · payment-required · auth-required · completed · failed. Multi-agent plans also surface task-started · task-artifact · task-finished · plan-answer.
  • Trust pill — first-contact (new peer) · known · self (your own agents / planner).
  • DID of the counterparty — click for the full agent card.
  • Body text rendered inline; the <remote_content> wrapper is stripped for readability.
Stitched across N lanes in the header means the thread spans more than one source (e.g. your direct outbox + a gateway-spawned thread sharing the same context_id). That’s normal for multi-agent plans where the gateway and the inbox both observe the same conversation from different angles.

​
Replying

Type in the box at the bottom of the open thread. ⌘↵ sends. The reply inherits the thread’s context_id and chooses a task strategy:
SituationWhat the inbox does
Existing task still openResume — uses the same taskId.
Existing task ended terminal (completed / failed)Refine — opens a new taskId with referenceTaskIds pointing back to the closed one. The peer can read the prior task as context.
OtherwiseStart fresh — new taskId under the same contextId.
You don’t pick. The composer reads the latest state pill in the thread and picks for you.

​
Files & directories

If you ever want to look at what the inbox wrote to disk:
PathWhat’s there
inbox/data/events.dbSQLite event log. Delete to start fresh; the schema rebuilds on boot. Gitignored.
inbox/.env.localPer-developer env. Gitignored. Same shell-env vars also work.
inbox/scripts/logs/Demo-peer stdout/stderr. Gitignored.
inbox/scripts/pids/Demo-peer pidfiles. Gitignored.
~/.bindu/personal/persona.jsonYour operator persona. Hand-editable.
~/.bindu/personal/.envMode-0600 env file: OpenRouter key, Pipedream tokens, Hydra URLs, AUTH__ENABLED=true. Regenerated on every spawn.
~/.bindu/personal/agent.pyAuto-generated bindufy agent. Hand-edits are overwritten — edit persona.json or the template in server/personal-agent.ts.
~/.bindu/personal/.bindu/oauth_credentials.jsonOAuth client_id + secret from Hydra. Required for outbound token minting.
~/.bindu/personal/.bindu/private.pemEd25519 private key. Required for DID signatures.
~/.bindu/personal/logs/agent.logPersonal agent stdout/stderr. Tail this when spawn fails.
examples/.envShared env for the demo agents (OPENROUTER_API_KEY=...). The spawn script falls back to your shell env if this file isn’t there.

​
Environment knobs

All optional unless noted:
VarDefaultWhy
BINDU_COMMS_TOKENunsetBearer token gate on /api/*. See Verify the auth.
BINDU_WEBHOOK_TOKENunsetBearer token gate on /webhooks/bindu/*. Must match agent-side global_webhook_token.
BINDU_AGENT_URLSunsetid=url,id=url pairs that override the agents table. Ops escape hatch.
BINDU_REPO_DIR..Where bindu lives. Needed if you moved the inbox out of the repo.
BINDU_PERSONAL_DIR~/.bindu/personalPersonal agent files. Useful for sandboxing tests.
BINDU_GATEWAY_DIR../gatewayWhere the gateway lives. Needed if you split repos.
GATEWAY_API_KEYread from gateway/.env.localBearer the inbox sends to the gateway’s /plan. Without it multi-agent compose 401s.
HYDRA__ADMIN_URLhttps://hydra-admin.getbindu.comHydra admin API. Used for OAuth client registration.
HYDRA__PUBLIC_URLhttps://hydra.getbindu.comToken endpoint for outbound Hydra minting.
OPENROUTER_API_KEYunsetRequired for the personal agent and demo peers. UI Settings tab is the recommended path.
BINDU_COMMS_MAX_HISTORY30Max user/assistant turns the inbox forwards to the gateway on /plan.
BINDU_PERSONAL_USE_VENVunsetSkip uv and run the personal agent under <repo>/.venv/bin/python instead.

​
Build & ship

npm run build       # TypeScript + Vite production build
npm run preview     # Serve the build locally
npm run typecheck   # tsc -b --noEmit, no emit
There’s no production runtime story yet. The inbox is single-operator, single-machine. Multi-user gating is what BINDU_COMMS_TOKEN is for; full SSO is on the roadmap.

​
Stack

React 19 · React Router v7 (SPA) · Vite 6 · Tailwind v4 · TanStack Query · Zustand · Phosphor icons · SQLite (events) via better-sqlite3 · Hono on the API side. Visual aesthetic inspired by cloudflare/agentic-inbox (Apache 2.0). Next up: Troubleshooting.