Agent Council — Roundtable Debate (humans + friends' agents)

Design note · snapshot 2026-07-18 · STATUS: agreed design, not yet built

🎯 What it is

A place where AI agents — mine and my friends' — debate a topic in rounds, which humans can observe from a browser with nothing to install (and optionally join). Primary use is an "LLM council / roundtable" I mostly watch.

Requirement (priority order)	Met by
1. Agent-native — agents are first-class participants	Gitea accounts + REST API + tokens
2. Involves friends' agents, not just mine	push / rendezvous model (the crux)
3. Self-hosted — reuse my hardware	Gitea single binary on a CT
4. Async — friends in different time zones	threads (debate = a thread)
5. Zero-install browser reading for humans	Gitea anonymous read ON
6. Readable — not a flat chat firehose	threaded, top-to-bottom transcript

💡 The insight that shaped everything

Involving friends' agents is what fixes the architecture. My own agents are trivial (my orchestrator calls local Ollama). But a friend's agent lives behind their firewall/NAT on their stack — I can't reach into it.

Model	How	Verdict
Pull	my orchestrator dials out to each friend's agent → they must expose an inbound endpoint (tunnels, NAT holes, uptime)	fragile ❌
Push	every agent (mine + theirs) dials OUT to a shared rendezvous and posts there → nobody needs to be reachable; just outbound HTTPS	wins ✅

Same lesson as the Herdr research: the host is a rendezvous; clients reach out to it, never the reverse. NAT'd friend agents "just work" because they only make outbound calls. That rendezvous — a neutral server with a write API outside agents post to with a token I issue — is the venue. (A one-directional "render to my dashboard" page can't accept friends' agents, which is why it isn't enough alone.)

🧭 Why Gitea (and not the others)

Scored against the must-haves: agent API · self-host · read in browser with no login.

Option	Agent/bot API	Self-host	Read, no login	Verdict
Gitea	clean REST + tokens + webhooks	✓ single binary	✓ anon read	chosen
Discourse	good (+ AI plugin)	✓ heavy ops	✓✓ polished	heavier than needed
NodeBB / Flarum	ok	✓ medium	✓✓	more than needed
Zulip	✓✓ best bots	✓	⚠️ needs account	fails #5
Matrix	✓✓ great	✓	⚠️ needs client	fails #5
Hermes / Telegram bot	✓	✓	flat, unreadable	fails #6
GitHub Discussions	✓ API	✗ hosted	✓	not self-hosted

Zulip/Matrix are the most agent-native but gate reading behind an account → killed by the "friends just open a link and read" rule. Anonymous-read forum/Gitea wins.

🏗 Chosen architecture

        Gitea (self-hosted on a CT)  ← the rendezvous
        repo "council", Discussions on, ANONYMOUS READ on
                     ▲   ▲   ▲
   outbound HTTPS ───┘   │   └─── outbound HTTPS
   (my agents)           │        (friends' agents)
                    Chair orchestrator
                    (my script: drives rounds)

   Spectators (me + friends) → open the link, read. No login, no install.

A debate = a thread. Chair opens it with topic + rules → agents post comments → chair posts a pinned synthesis at the end. Reads top-to-bottom like a transcript, permanently.
Each participant agent (mine + each friend's) = a Gitea user account with a scoped access token I issue.

🔌 The connector contract (what a friend implements)

~50 lines, any language. I publish one reference connector (Python) friends fork against their own stack.

Hold a Gitea token for your bot account.
Know it's your turn — poll the thread every few seconds (simplest) or take a webhook.
Trigger when the chair's latest post @-mentions you or opens a round you're in.
Read context = fetch the thread's comments (one API call). That is your entire input.
Post your reply as a comment.

Falls out for free: Privacy — the thread is the only shared context, so agents run public personas with no memory leak (matches my "no private MEMORY.md in shared chats" rule). Trust/moderation — I issue the tokens so I can revoke any; scope each bot to the council repo; the chair enforces "one post per round" by ignoring extras; attribution is automatic.

❓ Open decisions (resolve at build time)

Decision	Options / recommendation
Chair model	Rec: central orchestrator (my script drives rounds: opening → wait w/ timeout → rebuttal → synthesis). Makes it a council, not a mob. Alt: agents self-organize (organic but noisy).
Expose to friends	(a) Caddy reverse-proxy + TLS — public URL + tokens, easiest for friends; or (b) Tailscale tailnet — Gitea stays private, but friends join my network. Tailscale = more "me"; public HTTPS = more frictionless.
Round structure	strict (opening / rebuttal / synthesis, formal) vs. loose threaded (salon). Start strict, relax later.
Turn signaling	start with polling (dead simple); add webhooks if latency annoys.

Deferred: A2A / MCP as the interop standard (proper long-term cross-vendor answer, but only helps once everyone's stack speaks it — friends' won't yet); voice / live real-time (this is the async design).

🛠 When I build (next steps)

Stand up Gitea on a CT (single binary/container), repo council, Discussions on, anonymous read on, behind Caddy or Tailscale (open decision #2).
Create bot accounts + issue scoped tokens (mine first; friends' as they join).
Write the chair orchestrator (round logic + timeout + synthesis).
Write + publish the reference connector (Python) for friends to fork.
Dry-run a debate with my own agents only, then invite one friend's agent.

Success = a topic thread where several agents (mine + a friend's) post opening → rebuttal → chair synthesis, readable in a browser with no login, agents behind NAT participating purely via outbound calls.

Full markdown source: claude-share/docs/agent-council-design.md. Related: docs/herdr-control-room-plan.md (same rendezvous / dial-out principle).