Skip to content

agentic-thinking/hookbus

BranchesTags

Repository files navigation

HookBus™

HookBus™, the agent-to-agent event bus. Route governance-aware lifecycle events between any AI agent publisher and any subscriber, with priority-weighted deny-wins consolidation at the bus layer.

Apache 2.0. Production-ready. Zero runtime dependencies beyond Python stdlib + aiohttp + PyYAML.

licence python docker

Install (60 seconds)

One shell command clones the bus, pulls the two free subscribers (AgentProtect + AgentSpend) as public Docker images, bootstraps a bearer token, and starts the stack. Interactive menu lets you pick a publisher shim for your agent runtime.

curl -fsSL https://agenticthinking.uk/install.sh | bash

Non-interactive variants:

# Hermes-agent users
curl -fsSL https://agenticthinking.uk/install.sh | bash -s -- --runtime hermes

# OpenClaw users
curl -fsSL https://agenticthinking.uk/install.sh | bash -s -- --runtime openclaw

# Bus + subscribers only, skip publisher
curl -fsSL https://agenticthinking.uk/install.sh | bash -s -- --runtime skip --noninteractive

The script prints the dashboard URL + bearer token on completion. Re-run any time, it is idempotent.

Prefer not to pipe curl to bash? Inspect first: curl -fsSL https://agenticthinking.uk/install.sh > install.sh && less install.sh && bash install.sh

Prerequisites

  • Docker Engine 20+ with docker compose plugin, Docker Desktop on macOS / Windows (with WSL2), or curl -fsSL https://get.docker.com | sh on Linux
  • Python 3.10+ with pip, needed only if you're installing a publisher shim. Available on most Linux distros; on Debian/Ubuntu/Mint run sudo apt install python3-pip python3-venv.

Tested on Linux (Ubuntu, Debian, Mint) and macOS. Windows via Docker Desktop + WSL2 is expected to work but is not validated at launch, please open an issue if you hit something.

Manual install

If you prefer to see every step, or you are building an immutable / reproducible deployment, here is the full manual install.

Images ship as public containers on GitHub Container Registry. No build step, no registry login needed.

# 1. Clone the compose manifest
git clone https://github.com/agentic-thinking/hookbus.git
cd hookbus

# 2. Generate a stable bearer token (survives container restarts)
export HOOKBUS_TOKEN=$(openssl rand -base64 32 | tr -d '/+=')
docker compose up -d

# 3. Open the dashboard
echo "Dashboard: http://localhost:18800/?token=$HOOKBUS_TOKEN"

That pulls ghcr.io/agentic-thinking/hookbus:v0.1.0, cre-agentprotect:v0.1.0, and hookbus-agentspend:v0.1.0, starts the bus + two free subscribers, and wires bearer-token auth across the stack.

Want to build from source instead? Clone the three repos side-by-side (hookbus, cre-agentprotect, hookbus-agentspend) then docker build -t ghcr.io/agentic-thinking/<name>:latest . in each before docker compose up -d. Source stays private during preview, images are public.

Open the link printed above in your browser. The token sets an auth cookie; refresh + navigation in that tab stays authenticated without re-passing it.

That brings up HookBus™ + CRE-AgentProtect (policy) + HookBus-AgentSpend (cost tracking), all talking to each other via the Compose network. Auth is on by default, see the Security section below for pinning your own token, reverse-proxy recipes, and production hardening.

Install a publisher shim for your agent runtime

Publishers live in a separate package per agent. All shims read HOOKBUS_URL + HOOKBUS_TOKEN from the environment and send Authorization: Bearer <token> on every envelope they publish.

# Pick up the token from the container and export for your shell
export HOOKBUS_URL=http://localhost:18800/event
export HOOKBUS_TOKEN=$(docker exec hookbus cat /root/.hookbus/.token)

Then install the shim for your runtime:

Agent runtime Shim Licence
Nous Research Hermes pip install hookbus-publisher-hermes MIT
OpenAI Agents SDK pip install hookbus-publisher-openai MIT
Anthropic Claude Agent SDK pip install hookbus-publisher-anthropic MIT
Sourcegraph Amp pip install hookbus-publisher-amp MIT
OpenClaw npm install @agentic-thinking/hookbus-publisher-openclaw MIT

Point the shim at your bus:

export HOOKBUS_URL=http://localhost:18800/event

Envelope spec is CC0 public domain, see Zenodo DOI 10.5281/zenodo.19642020.

What it does

  1. Publisher emits a lifecycle event (PreToolUse, PostLLMCall, etc.) as a JSON envelope
  2. Bus fans out the event to all registered subscribers in parallel
  3. Subscribers return allow / deny / ask verdicts (sync subscribers) or record silently (async)
  4. Bus consolidates verdicts, deny wins, and returns a single decision
  5. The publisher acts on the consolidated verdict (tool proceeds, is blocked, or prompts user)

Example in one turn: a Hermes agent is about to run rm -rf /important-dir. The Hermes shim emits a PreToolUse event. A policy subscriber sees the destructive pattern and returns deny. The bus consolidates and returns deny to Hermes. The tool call never executes. The async audit subscriber records every step regardless of the verdict.

Optimised for sub-10ms P99 in local deployments.

Six canonical event types

Event When it fires Typical subscribers
UserPromptSubmit User enters a prompt KB injector, session memory, prompt shield
PreToolUse Agent about to call a tool Policy engines, DLP filter
PostToolUse Tool call returned Audit log, cost tracker
PreLLMCall LLM call about to happen Prompt shield, budget check
PostLLMCall LLM returned Cost tracker (tokens, model, provider)
Stop Agent run terminating Session snapshot, cleanup

Full envelope contract: see HOOKBUS_SPEC.md.

Example subscribers (shipped separately)

Repo Purpose Licence
cre-agentprotect Policy enforcement via Microsoft Agent Governance Toolkit MIT
hookbus-agentspend Token + cost tracking with built-in dashboard MIT

Build your own subscriber in ~30 lines of Python, see HOOKBUS_SPEC.md for the envelope contract.

Architecture

┌───────────────┐     envelope      ┌──────────────────┐
│   Publisher   │ ────────────────▶ │       Bus        │
│   (Hermes,    │                   │  (port 18800)    │
│   Claude,     │ ◀──────────────── │                  │
│   OpenClaw,   │  consolidated     │  ┌────────────┐  │
│   OpenAI …)   │  verdict          │  │ Dashboard  │  │
└───────────────┘                   │  │ (18801)    │  │
                                    │  └────────────┘  │
                                    └────┬────────┬────┘
                                         │        │
                       ┌─────────────────┘        └─────────────────┐
                       ▼                                            ▼
              ┌─────────────────┐                          ┌─────────────────┐
              │ cre-agentprotect│                          │   agentspend    │
              │  (sync policy)  │                          │ (async cost)    │
              └─────────────────┘                          └─────────────────┘

Configuration

Register subscribers via ~/.hookbus/subscribers.yaml:

subscribers:
  - name: cre-agentprotect
    type: sync
    transport: http
    address: http://127.0.0.1:8898
    timeout: 5.0
    events: [PreToolUse, PostToolUse, PostLLMCall]
    metadata:
      vendor: Agentic Thinking Limited
      licence: MIT

  - name: agentspend
    type: async
    transport: http
    address: http://127.0.0.1:8883/event
    events: [PreToolUse, PostToolUse, PostLLMCall]
    metadata:
      vendor: Agentic Thinking Limited
      licence: MIT
      ui_port: 8883

See hookbus.yaml for the complete configuration reference.

Patents

HookBus™ is the subject of UK Patent Application GB2608069.7 (bus architecture, filed 8 April 2026). See NOTICE for full patent attribution.

Apache License 2.0 Section 3 grants you a patent licence for your use of this software. See LICENSE and NOTICE for full terms.

What HookBus™ is not

HookBus is not a security perimeter against malicious AI agents. It assumes the agent is cooperating with its own hook surface, a hostile agent that actively tries to evade observation needs isolation at the runtime layer (sandbox, container, VM, seccomp), not the bus layer.

HookBus is not a replacement for network firewalls, secret scanners, code signing, or OS-level access control. It is a governance-aware event bus that makes the agent's own lifecycle decisions observable, consolidatable, and enforceable by external subscribers.

See the architecture paper Section 15 for the full trust-model discussion.

Troubleshooting

I regenerated the bus token and now my Hermes (or other shim) keeps getting 401

The shim reads HOOKBUS_TOKEN from its environment. If you or the wrapper wrote an old token into a .env file (for example ~/.hermes/.env), that file wins over the shell-exported value. After docker compose down -v && up -d the bus writes a fresh token, but the shim still sends the old one.

Fix:

# Remove any stale HOOKBUS_TOKEN line from the shim's .env
sed -i '/^HOOKBUS_TOKEN=/d' ~/.hermes/.env 2>/dev/null || true
sed -i '/^HOOKBUS_TOKEN=/d' ~/hermes-agent/.env 2>/dev/null || true

# Re-read the current token and export fresh
export HOOKBUS_TOKEN=$(docker exec hookbus cat /root/.hookbus/.token)

Run the shim again. Events should land.

AgentSpend container restarts repeatedly on first boot

AgentSpend waits up to 30 seconds for the bus to write its token file to the shared volume. If it still can't find a token after that, it exits. Check that the hookbus-auth named volume is mounted on both the bus and the subscribers (see docker-compose.yml).

docker compose up fails with 'pull access denied'

You are running the quickstart before the images reached Docker Hub, or your Docker daemon cannot reach Docker Hub. Build locally from the repo source:

docker compose up -d --build

Security

HookBus generates a random authentication token on first start and requires it on every request to the bus and subscriber dashboards/APIs. All data, events, token costs, AGT categories, session IDs, subscriber names, is protected. Unauthorised requests get 401 Unauthorized.

Read your token (one-time after install)

docker exec hookbus cat /root/.hookbus/.token

Copy the value. Examples below use $TOKEN to mean that string.

Open a dashboard

Paste the full URL with the token once per dashboard:

http://localhost:18800/?token=<your-token>     # HookBus bus + Light dashboard
http://localhost:8883/?token=<your-token>      # HookBus-AgentSpend dashboard

The first load sets an HTTP-only cookie scoped to that host:port. Subsequent navigation in the same tab keeps you authenticated without the query param.

Publishers authenticate via header

export HOOKBUS_TOKEN=$(docker exec hookbus cat /root/.hookbus/.token)
# now any shim reads HOOKBUS_TOKEN and sends Authorization: Bearer <token>

Pin your own token (production)

For production, provide your own stable token in docker-compose.yml so it survives rebuilds:

services:
  hookbus:
    environment:
      HOOKBUS_TOKEN: ${HOOKBUS_TOKEN:?set a long random token}

Then HOOKBUS_TOKEN=$(openssl rand -base64 32) docker compose up -d.

Network binding

By default, ports bind to 0.0.0.0 so LAN hosts can reach the dashboards, auth still enforces per-request. For stricter deployments, bind to 127.0.0.1 in docker-compose.yml and front with a reverse proxy (Caddy, nginx, Traefik) that handles TLS + auth at the edge.

Disable auth (local dev only)

Mount an empty token file or set HOOKBUS_TOKEN= to empty, and the bus skips auth checks. Never do this on any machine with an internet-facing port.

Commercial support

Production support, custom subscribers, compliance-grade audit evidence, and SLA-backed deployments are available from Agentic Thinking Limited. Contact contact@agenticthinking.uk.

Contributing

PRs welcome under Apache 2.0. By submitting a pull request you agree to licence your contribution under the same terms (inbound = outbound). A lightweight CLA will be added ahead of the first external merge. See CONTRIBUTING.md for guidelines.

We especially welcome contributions for:

  • New publisher shims (any agent runtime, Windsurf, Cursor, Continue, Cline, Amp extensions, etc.)
  • Example subscribers (rate limiter, tool validator, prompt firewall, custom OPA adapter)
  • Transport support beyond HTTP + Unix socket (NATS, Redis pubsub, gRPC)
  • Language bindings for the envelope spec

Trademarks

HookBus™ is a trademark of Agentic Thinking Limited. Nominative use (describing compatibility or integration) is always permitted. See NOTICE for details.

Specifications & citation

If you are publishing research or building on the HookBus architecture, the canonical reference is:

Ruocco, P. (2026). HookBus: A Governance-Aware Lifecycle Event Bus for Heterogeneous AI Agents. Zenodo. https://doi.org/10.5281/zenodo.19642020

The envelope schema is released under CC0 (public domain). See HOOKBUS_SPEC.md in this repository for the in-tree specification.

Built by Agentic Thinking Limited, UK Company 17152930. Contact: contact@agenticthinking.uk

About

HookBus - the agentic infrastructure. Open-source event bus for AI agent lifecycle governance.

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

No contributors

Languages