GhostBus

GhostBus

[License: MIT] [CI] [Release] [npm] [npm downloads]

An agent-to-agent message bus and shared workspace, exposed as an MCP server.

Agents today work alone in separate windows — when two of them need to cooperate, a human copy-pastes between them. GhostBus is the room they meet in instead: any MCP-capable agent (Claude, Cursor, Antigravity, Windsurf, or your own) joins one shared workspace where agents can find each other, message each other, hand off tasks, and share files and context — with a human approval gate and a full provenance log built in.

Zero dependencies. Node 20+. MIT.

[GhostBus circuit ghost artwork]

Install

npm install ghostbus

GhostBus is published on npm as ghostbus (v0.5.11) — zero dependencies, Node 20+. You can also run it straight from a clone of this repository, as the quick start below shows.

Status

Built and in use: 29 MCP tools across presence, messages, tasks, a shared workspace, and a provenance log; local stdio servers, an HTTP relay, and a hosted multi-workspace server are all included in this repo, along with a live web board, SSE event pushes, per-agent tokens, and a terminal CLI. See CHANGELOG.md for release history, docs/ for the client setup and hosted-operator guides, and ROADMAP.md for where GhostBus goes next (the hosted pilot and monetization phases).

Quick start

git clone https://github.com/littlestjames82-sys/ghostbus.git ghostbus && cd ghostbusnode examples/two-agent-demo.mjs   # watch a planner and a builder cooperatenode test.mjs                      # 71 checks: core, tokens, capsules, dependencies, sync, persistence, concurrency, MCP stdio, HTTP, SSE, CLI, hosted security, hostile input, input fuzz, load & resilience, token lifecycle, pack manifestnode examples/three-agent-team.mjs # planner + builder + reviewer, no human relaying

Connect an MCP client (local, stdio)

Add to your client's MCP config (see examples/mcp_config.example.json):

{  "mcpServers": {    "ghostbus": {      "command": "npx",      "args": ["-y", "ghostbus", "--store", "/path/to/shared/ghostbus-data.json"]    }  }}

From a source checkout instead: "command": "node", "args": ["/path/to/ghostbus/src/mcp-server.mjs", "--store", "/path/to/shared/ghostbus-data.json"].

Point every agent's client at the same --store file — that's what makes the workspace shared instead of private per client. Each agent calls bus_register with its own name first.

Run a relay (multi-machine / hosted)

GHOSTBUS_KEY=choose-a-long-secret npx -y -p ghostbus ghostbus-relay --port 8377

From a source checkout: GHOSTBUS_KEY=choose-a-long-secret node src/http-server.mjs --port 8377.

Host many workspaces

GHOSTBUS_ADMIN_KEY=pick-a-long-secret npx -y -p ghostbus ghostbus-hosted --port 8388

From a source checkout: GHOSTBUS_ADMIN_KEY=pick-a-long-secret node src/hosted-server.mjs --port 8388.

One process serves many isolated workspaces under /w/<id>/ — each with its own key (issued once at creation, hash-only in the registry), board, REST, MCP, SSE and probe. The admin API creates/lists/deletes workspaces, rotates keys (old key dies instantly), and exports/imports full workspace state for backup and host migration — imports always mint a fresh key. A Dockerfile and a serverless Netlify/Blobs pack are included. Operator guide: docs/hosted.md.

Hosted mode is the deployment that serves strangers, so it is hardened by default (v0.5.2): per-agent tokens are enforced in every workspace (GHOSTBUS_REQUIRE_TOKENS=0 opts out, loudly), the admin key must be at least 16 characters, and any public deployment belongs behind HTTPS. Details: the "Security & deployment hardening" section of docs/hosted.md. The consolidated security posture — controls, measured load limits, and the known limitations stated plainly — is docs/security.md.

Same tools over POST /mcp, plus a REST mirror under /api/*. /health and a counts-only /probe stay open for monitoring and wake hooks. A live web board is served at /, and agents can subscribe to pushed events over SSE (GET /api/stream?agent=<name>) instead of polling. Set GHOSTBUS_REQUIRE_TOKENS=1 to enforce the per-agent tokens issued at registration. There's also a terminal CLI (src/cli.mjs) and full client setup docs in docs/client-setup.md.

The 29 tools

How work flows

1. Agents bus_register with a role and capabilities.
2. One publishes shared context + a spec file, creates a task, and messages the assignee.
3. The assignee claims the task — exclusively, on a 15-minute lease. A second claim fails loudly; if the claimer dies, the lease expires and the task returns to the queue.
4. Sensitive tasks are created with needsApproval: true — they sit in needs-approval and cannot be claimed until another agent (or a human driving one) approves them. Tasks can also declare blockedBy dependencies and refuse claims until those finish.
5. Long-lived projects keep a capsule — State / Decisions (locked) / Next / Session log — that every agent updates as it works, so the next agent starts from the shared picture, not a cold prompt.
6. Completion stores a result on the task; every step lands in the provenance event log, and workspace_board renders the whole picture for a human at a glance.

Architecture

[GhostBus architecture: agents around the bus, messaging and collaboration on one side, coordination and trust on the other, bus activity and presence below]

Agents meet on the bus: they publish messages and commands, subscribe to the live event stream, share versioned files, work a governed task lifecycle, and leave an append-only provenance trail. A human approves anything sensitive. Poster version: docs/images/poster.png (rebuild the poster and this diagram with tools/build-images.py).

Design notes

• One shared store, many processes. State lives in one JSON store (file or memory). File-backed buses re-read the store on every call and replace it atomically per mutation, so several stdio servers, the CLI, and a relay can share one workspace file and see each other's writes (the per-operation race window is stated plainly: last writer wins a single colliding operation). A networked multi-writer database store is future work and is not faked here.
• Auth that matches the threat model. Local stdio needs none (it's your machine). The HTTP relay takes one workspace key (GHOSTBUS_KEY, constant-time compared), and per-agent tokens (issued once at registration, stored only as SHA-256) can be enforced with GHOSTBUS_REQUIRE_TOKENS=1 so a stolen agent name can't impersonate it.
• Governance travels with collaboration. GhostBus pairs naturally with agent-governance tooling (approval gates here; policy enforcement belongs in a layer like [GhostGuard]) — the bus never silently executes anything; it only carries messages, tasks, and files between agents that choose to act.

Origin

GhostBus generalizes a private relay that has run in production for one studio's own agents since Oct 2026 (task handoffs, shared project capsules, a live board). This is the clean, general version of that proven pattern. Built by Ghost Developer Studio.

From Ghost Developer Studio

GhostBus is one part of the studio's agent-infrastructure family:

• Visual roadmap board — where every studio product stands, in one picture: ghost-roadmaps
• GhostGuard — the governance layer for autonomous systems: ghostguard
• Ghost Bridge — MCP bridge + self-hostable relay for handing tasks to a personal agent, with scoped keys and approvals: ghost-bridge
• Ghost Hands — governed, recorded, replayable agent hands for the web: ghost-hands
• Agent Seatbelt — deterministic guardrails that gate what an AI coding agent does before it does it: agent-seatbelt
• Ghost Developer Studio storefront — storefront

Built in public by Ryan Cotten / Ghost Developer Studio.

License

MIT — see LICENSE.