hivebus

A signed channel for agent-to-agent questions. The signature covers what the answerer observed — repo identity, working directory, and inode — not only who signed, so a correctly signed answer about the wrong checkout is rejected. Open source (MIT). The same bus also carries agent issue intake, investigation, and work-order drafting.

Hivebus is a machine-native bus for agents and services that need more than raw RPC or generic queues. It treats an issue as a typed thread with structured envelopes, evidence, provenance, state transitions, and a hard gate before a work order can be created.

The product shape behind this repo is:

• nullbot runs close to the problem, gathers safe evidence, and opens a thread.
• specialist agents investigate asynchronously inside the same thread.
• Hivebus preserves receipts, context, and auditability as JSON-first protocol objects.
• once the diagnosis is verified, Hivebus drafts a work order for workledger, with optional execution integration to hiveram.com.
• this repo is the whole open core; live-session integration layers stay out of tree under the boundary charter.

A few names above refer to the wider stack this composes with — all optional, none required to run hivebus:

• nullbot — an intake collector that opens a thread with evidence; the open-core intake surface lives here.
• workledger — the command-line client for Hiveram, our commercial execution ledger. Hivebus drafts work orders for it; Hiveram records and routes the work. Hivebus itself never needs it to run — the bridge is optional and the protocol is open.
• NeuroRouter Pro — the commercial live-session bridge: it lets a running agent session answer from its own warm context, the out-of-tree layer the boundary charter draws the line at.

That is the honest shape: hivebus is the free, MIT, self-hostable channel; the paid products (Hiveram, NeuroRouter Pro, Bulwark) sit above the bus and compose with it through the open protocol. They cannot make the channel non-open.

This repository is the MIT open core for Hivebus. It is not a teaser for a separate paid Hivebus edition.

• this repo keeps the indispensable protocol core public and self-hostable
• protocol contracts, deterministic validation, signing, and CLI surfaces stay open here
• live-session integration layers stay out of tree under the boundary charter
• new product capability does not land here by default unless a tracked work order explicitly expands the public boundary

Out-of-tree integrations may be commercial, but they do not own the protocol:

• the open-source runtime works without a license verifier
• paid or managed integrations must sit above the bus, not inside it
• no commercial layer can make envelope shapes, trust-class semantics, key pinning, or the asker/answerer CLI non-open

Hivebus only becomes essential if it carries the whole path from issue intake to tracked execution. So the open core includes the protocol core and the canonical workledger bridge, not only a subset. Out-of-tree integrations can add hosted, commercial, org, and compliance layers on top.

Deployment location is not the split. Core stays self-hostable; integration-specific policy can run wherever its operator needs it. Local, Fly, VPS, and private infrastructure are all valid deployment targets.

Core owns the structured conversation substrate plus canonical execution tracking; out-of-tree integrations own the live-session, hosted, org, and compliance layers that sit on top.

• Not a human chat app with a GUI.
• Not a generic message queue replacement.
• Not an agent marketplace.
• Not autonomous remediation by default.
• Not a prompt soup relay where untyped blobs bounce between models.

Scope is governed by the boundary charter: Hivebus core is a dumb signed channel, and anything that makes the bus decide, generate, judge, or bridge a live session stays out of tree.

Hivebus follows RootOps principles:

• Prevent unsafe work structurally instead of apologizing afterward.
• Keep the protocol explicit, typed, and replayable.
• Separate intake, investigation, and execution instead of hiding them inside one opaque model call.
• Refuse to create a work order until the diagnosis is verified and missing information is resolved.
• Make pricing tiers policy boundaries, not protocol forks.

Get a second agent talking to a first one. No human relaying messages between terminals -- one agent asks, another answers, over a signed channel.

Install with Go when you already have a Go toolchain:

go install github.com/obstalabs/hivebus/cmd/hivebus@latest

Or install from a release archive. Tagged releases publish standalone binaries for macOS, Linux, and Windows on amd64 and arm64, plus checksums.txt. Windows archives are .zip; macOS and Linux archives are .tar.gz. Homebrew is optional and not required for installation.

# macOS/Linux example: pick darwin or linux, amd64 or arm64
version=0.4.0 # replace with the latest release version, without the leading "v"
os=darwin
arch=arm64
curl -L -o hivebus.tar.gz \
  "https://github.com/obstalabs/hivebus/releases/download/v${version}/hivebus_${version}_${os}_${arch}.tar.gz"
tar -xzf hivebus.tar.gz
install -m 0755 hivebus /usr/local/bin/hivebus

# Windows example: pick amd64 or arm64
$Version = "0.4.0" # replace with the latest release version, without the leading "v"
$Arch = "amd64"
Invoke-WebRequest `
  -OutFile hivebus.zip `
  -Uri "https://github.com/obstalabs/hivebus/releases/download/v$Version/hivebus_${Version}_windows_$Arch.zip"
tar -xf hivebus.zip
.\hivebus.exe version

Homebrew users can also install from the optional tap when a formula has been published:

brew install obstalabs/tap/hivebus

Then run the loop in three terminals. The bus binds loopback; nothing leaves your machine.

# terminal 1 -- the bus
hivebus serve --auth-disabled --listen 127.0.0.1:7097 --db ~/.hivebus/bus.db

# terminal 2 -- a warm agent that answers repo_status for this repo
hivebus answer --server http://127.0.0.1:7097 --insecure \
  --agent me/agent --session-id a1 --repo . --project demo

# terminal 3 -- a second agent asks the first, instead of crawling the repo itself
echo "which checkout is canonical and what is HEAD?" | hivebus ask \
  --server http://127.0.0.1:7097 --insecure \
  --to me/agent --from me/asker --type repo_status --repo . \
  --session-id b1 --timeout 6s

You get a signed answer back:

delivered: true   answers: 1   response_status: answered

This removes the human relay. Instead of a person copy-pasting "what HEAD are you on?" between two agent sessions, the agents ask each other directly and the answer is signed, so the asker can trust it without re-deriving it. delivered: true / answers: 0 / no_answer is also a success for the channel: the question was delivered, nobody answered. Delivery is guaranteed; an answer is not.

The first keyless ask pins the answerer's key (SSH known_hosts model). For the fish/bash/sh variants, multiple repos, key pinning, and cross-machine asks over SSH, see the local and remote runbooks. Setting this up by hand is the open-core path; a live-session bridge (NeuroRouter Pro) wires the agents together for you.

hivebus can also act as the small boardroom binary for processes that do not run under an orchestrator such as NeuroRouter Pro. Start the runtime, have one participant listen, and let another participant say into that inbox:

# terminal 1 -- local bus
hivebus serve --auth-disabled --listen 127.0.0.1:7097 --db /tmp/hivebus-boardroom.db

# terminal 2 -- Codex or any non-orchestrated process registers and listens
hivebus listen --server http://127.0.0.1:7097 --insecure \
  --session-id codex-1 --participant codex/hivebus --ack

# terminal 3 -- another participant sends a plain boardroom message
echo "please read /tmp/handshake.md and ack" | hivebus say \
  --server http://127.0.0.1:7097 --insecure \
  --from architect/hivebus --session-id architect-1 --to codex/hivebus

Use hivebus ask when the message is a bounded signed question/answer exchange; use say/inbox/listen when you just need a generic local boardroom. The guide docs/guides/standalone-boardroom.md covers the command surface and the embedding/conformance boundary.

Build from a clone instead of go install:

make build      # produces bin/hivebus
make test

Print the protocol contract, or a concrete nullbot-to-workledger example:

hivebus spec
hivebus sample-case

The nr.run.* receipt protocol is documented in docs/protocols/nr-run-envelopes.md.

Embedding and conformance:

• github.com/obstalabs/hivebus/embed serves the same runtime over a caller-owned listener for products that need in-process local IPC.
• github.com/obstalabs/hivebus/conformance exposes importable golden JSON fixtures so external consumers can prove their /v0/agents/* wire payloads still match Hivebus.

Show build metadata:

hivebus version --json

Run the v0 HTTP runtime with a SQLite append-only event log:

./bin/hivebus serve --listen 127.0.0.1:7081 --db /tmp/hivebus.db

Run the runtime with self-validating Ed25519 API keys:

HIVEBUS_API_VERIFY_KEY=<base64-ed25519-public-key> \
  ./bin/hivebus serve --listen 127.0.0.1:7081 --db /tmp/hivebus.db

Release builds can embed the same public verify key at build time:

HIVEBUS_API_VERIFY_KEY=<base64-ed25519-public-key> make build

Fetch the compact recovery handoff for a promoted thread:

curl -H "Authorization: Bearer <operator-token>" \
  http://127.0.0.1:7081/v0/threads/<thread-id>/recovery

The recovery capsule contains verified diagnosis, evidence refs, stale/rejected fact labels, and the local promotion receipt. It deliberately excludes raw transcript, model narration, artifact bodies, and unlabeled stale hypotheses.

In Hivebus, one agent asks another a read-only question -- "which checkout is canonical? what HEAD are you on? are you done?" -- and gets a signed answer back, instead of crawling the other repo, re-deriving state, or interrupting a human to relay. The bus carries the question and the answer and decides nothing itself; the asking CLI verifies the answer's provenance before trusting it (see Known Limitations for where runtime verification still lags the CLI).

Direct ask/answer:

asker agent
  -> signs a read-only query envelope (e.g. repo_status) and addresses it to another agent
  -> the bus delivers it; delivery is the whole job, a no-answer is still a success

answerer agent
  -> resolves the question from what it observes now (git read at answer time)
  -> binds the observed world into the signed payload: repo id, absolute git dir,
     device + inode, observed_at, trust class (tool_asserted vs model_inferred)

asker verification
  -> checks the signature, then the observation context: does the world this card
     describes match the repository it addressed? a wrong checkout is rejected,
     distinctly from a signature failure -- and the verification level is reported,
     never silently downgraded

In the open core, an answerer is a small sidecar that resolves deterministic questions (repo state, file provenance) from disk. The deeper move -- letting a live agent session answer from its own warm context ("what am I actually working on? which approach did I pick?"), and bridging the running sessions of vendor agents into the bus -- is live-session integration, which lives out of tree under the boundary charter. The open bus makes agents talk; connecting their live working sessions is the commercial layer (NeuroRouter Pro / Obsta Labs).

Cross-machine: a dispatched agent reports back. The most demanding case is the one where the agent cannot read local state and must ask over the channel -- a dispatcher on one machine sends an agent to a remote server, and that remote agent reports back over hivebus: its task acknowledgement, status, and a signed result attestation. There is no shared filesystem, so the answer is the only source of truth, and the binding-level matrix earns its keep:

dispatcher (operator machine)        remote agent (server)
  -> serve binds 127.0.0.1               -> runs under the dispatcher's gate
  -> ssh -R makes the bus reachable      -> answers/asks at localhost over the tunnel
     at the remote's localhost

remote agent
  -> signs its repo_status (or status/ack/result) over what it observes on the server

dispatcher verification
  -> checks the signature, then the observation context -- but it cannot stat the remote
     .git inode across the network, so it verifies at the REMOTE tier: the signed repo id
     and remote URL, reported as `binding_level: repo_id_only`, named not silently upgraded

SSH is the only wire (it already carries the dispatch); hivebus adds no transport security of its own -- SSH is the transport, the ed25519 signature is the authenticity. The remote-ask-over-ssh runbook documents this loop with a verified two-machine transcript, and Bulwark places the key material at dispatch so the first contact is pinnable rather than blind.

Open core covers the deterministic half -- signed status, task acknowledgement, and result attestation over the bus, verified at the honest remote tier. The richer form, where the remote agent answers from its live warm context rather than a disk read, is the live-session bridge funnel, out of tree under the boundary charter.

Issue intake to tracked work (the coordination surface):

nullbot collector
  -> creates a thread and evidence bundle
  -> sends signed task.request envelopes into Hivebus

Hivebus core
  -> validates envelope structure and tier policy
  -> preserves thread state in an append-only SQLite event log
  -> routes investigation work across specialist agents

investigator agents
  -> ask clarification.request when evidence is incomplete
  -> emit diagnosis.proposed only when evidence is sufficient

workledger bridge
  -> accepts only verified diagnoses
  -> creates the canonical work order that can fully resolve the user story
  -> leaves a compact recovery capsule for post-compaction handoff

optional execution integration
  -> mirrors or extends the same work order outside the core runtime when needed

Current code layout:

• cmd/hivebus: minimal CLI entrypoint
• internal/cli: the serve, ask, answer, and watch commands; the ask/answer resolvers, answer-key pinning, and observation-context verification
• internal/model: envelopes, threads, artifacts, diagnoses, recovery capsules, signing
• internal/runtime: v0 HTTP handlers for intake, promotion, dispatch, agent sessions, inbox/delivery, thread creation, append, and replay
• internal/policy: free, pro, teams, enterprise limits
• internal/spec: exported v0 contract and sample case bundle
• internal/store: SQLite append-only event log, deterministic replay, and verified recovery projections
• internal/work: deterministic workledger drafting rules with optional Hiveram execution targets

Hivebus keeps one protocol across policy tiers. The labels in code are local limits and coordination profiles, not a promise of separate paid Hivebus repos or protocol forks:

• free: self-hostable protocol core, smallest retention window, and artifact limits for solo experiments, implemented in this hivebus repo.
• pro: single-tenant production coordination profile with longer retention and higher local limits when an out-of-tree integration enables it.
• teams: shared coordination profile with multi-operator policy and larger routing/evidence limits when an out-of-tree integration enables it.
• enterprise: corporate controls, compliance posture, and governance profile when an out-of-tree integration enables it.

This keeps the protocol shared while making the repo boundary explicit: core stays open here, integration-specific behavior stays out of the OSS tree, and no policy tier requires a specific hosting location.

workledger is the execution source of truth for Hivebus. A verified diagnosis is not enough on its own; it must be promotable into a canonical work order with an explicit target project.

After promotion, GET /v0/threads/{threadID}/recovery exposes a verified-provenance capsule for compaction recovery and handoff. It is generated from local Hivebus events, so it does not require Hiveram, NeuroRouter, or a live Workledger call to read. External IDs are additive references, not hidden dependencies.

The free/community contract includes these workledger operations:

• search before create to avoid duplicate work orders
• create and update the canonical work order
• add notes with agent findings, evidence, and commit SHAs
• claim and release work so agents do not execute the same fix twice
• sync context blobs across machines and operator sessions
• update project metadata when the bridge needs repo or projection state

Out-of-tree execution integrations may mirror or present the same work order, but they do not replace workledger as the ledger of record.

Background analysis and live-session orchestration are out of tree. They can consume the same protocol, but they do not belong inside core.

• The v0 runtime is HTTP-only and intentionally small: nullbot intake, thread promotion, dispatch, append, and replay.
• Runtime HTTP intake (internal/runtime) authenticates signed API-key tokens but does not yet cryptographically verify posted envelope signatures. The ask/answer CLI path does verify them (see docs/specs/observation-context-v0.md).
• The workledger bridge requires explicit WORKLEDGER_URL or WORKLEDGER_HOST plus WORKLEDGER_API_KEY configuration on the runtime host.
• Optional execution sync is exposed as a hook surface, not a bundled core-runtime integration.
• Capability routing is still declarative rather than runtime-driven.
• Runtime auth validates Ed25519-signed API keys locally, with hashed token files retained only as an explicit local fallback.

• Add signed envelope verification and nonce replay protection.
• Add additional nullbot intake adapters beyond the v0 HTTP path.
• Extend the workledger bridge with richer search/update/note flows while keeping optional execution integrations out of tree.
• Keep smart-bus and live-session runtime surfaces out of this repo.
• Add queue-backed and realtime transports without changing protocol shape.

MIT. See LICENSE.