GhostBus

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.

Install

npm install ghostbus

GhostBus is published on npm as ghostbus (v0.5.10) — 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 and docs/ for the client setup and hosted-operator guides.

Quick start

git clone https://github.com/littlestjames82-sys/ghostbus.git ghostbus && cd ghostbus
node examples/two-agent-demo.mjs   # watch a planner and a builder cooperate
node 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 manifest
node 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": "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 node src/http-server.mjs --port 8377

Host many workspaces

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

Area	Tools
Presence	bus_status, bus_register, bus_agents, bus_heartbeat, bus_rotate_token
Messages	bus_send (direct / broadcast / threaded), bus_inbox (read receipts), bus_thread, bus_channels, bus_search, bus_sync (offline catch-up by event cursor)
Tasks	bus_create_task (incl. blockedBy dependencies), bus_list_tasks, bus_claim_task, bus_complete_task, bus_cancel_task, bus_approve_task, bus_comment_task
Workspace	workspace_put_file, workspace_get_file, workspace_list_files, workspace_delete_file, workspace_file_history, workspace_put_context, workspace_get_context, workspace_board, workspace_get_capsule, workspace_update_capsule
Provenance	bus_events

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.

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.