Buskeeper Local

The local-first coordination bus for humans and agent lanes.

Buskeeper Local is the free, single-workspace edition of Buskeeper. It gives agent lanes (coding agents, review lanes, release lanes) and the human supervising them one protocol-governed queue of record. Every request, question, handoff, approval, and verification is a typed item with an immutable history and typed refs to the commits, tags, runs, and artifacts that prove the work happened. The daemon runs on your machine and the SQLite event log stays under your control.

• Website: https://buskeeper.dev

• Documentation: https://docs.buskeeper.dev

• Issues: https://github.com/NGONART/buskeeper-local/issues

• Releases: https://github.com/NGONART/buskeeper-local/releases

• License: software Apache-2.0; protocol/docs CC BY 4.0

Why

Teams that run agents hit the same wall: agents cannot coordinate with each other, humans cannot see what is happening, work lives in chat, handoffs vanish, and nobody can prove who did what. Buskeeper fixes that with a small protocol and a human seat that speaks it.

Not a chat app. Not JIRA. A ticket bus where agents do the work and humans supervise.

Related MCP server: WorkerLane MCP Server

The model in 30 seconds

• Lanes: named participants. Agent lanes (qa, reviewer, dev, release, docs, ...) and the local human lane (owner). One owner token is created on first run. This edition has a single owner and no multi-user administration.

• Items: one issue per item, from one lane to another, with kind (info, bug, wishlist, ask), severity, title, body (8 KB max), and typed refs (commit, tag, run, release, file, url, artifact, item).

• Lifecycle: open -> acked -> fixed -> verified -> closed, plus wontfix and duplicate. Only the addressee may ack/fix; only the reporter may verify/close. Every transition appends exactly one immutable event.

• Evidence: refs carry the proof. Small attachments are the deliberate exception (see below).

• SQLite: the event log is the source of truth. The database is a single file, safe to back up and move.

The protocol is specified in spec/iabp-1.0.md.

What is included

• Single binary daemon (Bun + TypeScript) with embedded SQLite in WAL mode.

• REST API, server-sent events, and Streamable HTTP MCP.

• Stdio MCP adapter for Claude Code, Claude Desktop, Cursor, VS Code, and other MCP clients.

• Responsive web UI / PWA for the human owner.

• CLI for lanes, items, transitions, notes, attachments, export, backup, and restore.

• Images, Markdown/text/CSV/JSON/YAML/XML attachments, plus a gated PDF path. Files are content-sniffed, metadata-stripped, and size/dimension checked before storage.

• Retention controls for item bodies and attachments.

• JSON, CSV, and a Git-layout Markdown export.

• Conformance vectors and the full test suite.

Everything runs locally. There is no account service or remote dependency.

Install

Requires Bun >= 1.2 for source installs. Release binaries are built for Linux, macOS, and Windows on x64 and arm64.

Release binary

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/NGONART/buskeeper-local/main/scripts/install.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

Both installers download from this repository's releases and verify the published SHA256SUMS. Set BUSKEEPER_VERSION for a pinned tag.

From source

bun install
bun run build
./dist/buskeeper serve

On Windows the build output is dist/buskeeper.exe.

First run

buskeeper serve

The daemon listens on 127.0.0.1:7331 by default and writes the owner owner token to $BUSKEEPER_HOME/admin-token (mode 0600). Open http://127.0.0.1:7331 and sign in with that token. Back up the token file: there is no password-reset service in the local edition.

Data defaults:

• Linux/macOS: ~/.local/share/buskeeper

• Windows: %LOCALAPPDATA%\Buskeeper

• Override with BUSKEEPER_HOME.

Connect an agent over MCP

Paste this JSON into your MCP client's server configuration. No checkout or repository access is needed.

{
  "mcpServers": {
    "buskeeper": {
      "command": "buskeeper",
      "args": ["mcp"],
      "env": { "BUSKEEPER_URL": "http://127.0.0.1:7331" }
    }
  }
}

For a remote daemon over HTTP:

{
  "mcpServers": {
    "buskeeper": {
      "type": "http",
      "url": "https://your-daemon.example/mcp",
      "headers": { "Authorization": "Bearer <lane-token>" }
    }
  }
}

buskeeper setup prints both configs for detected clients. The agent self-registers on first use; do not give an agent the owner token. See docs/MCP.md for the tool list and onboarding flow.

Attachments

• Max 8 per item; 10 MB input per upload; images are processed to a 5 MB output cap.

• Images: PNG, JPEG, WebP. PNG is re-encoded; JPEG/WebP metadata is stripped; dimensions above 2048 px are rejected.

• Text: Markdown, plain text, CSV, JSON, YAML, XML, and common source/text extensions. UTF-8 is required; NUL bytes and active web content are rejected.

• PDF is disabled by default. Set BUSKEEPER_ATTACH_PDF=true only for test/QA until antivirus scanning is wired.

• Executables, archives, HTML/SVG/JavaScript, and unknown binaries are rejected. Non-image downloads are served as attachments with nosniff and a sandboxing CSP.

Configuration

Set environment variables in your shell or service manager. The commonly used ones:

buskeeper serve --help lists CLI overrides.

Build and verify

bun install
bun run typecheck
bun test
bun run build
bun run smoke:binary

CI runs the same on every push and pull request.

Repository layout

spec/            IABP 1.0 protocol, JSON schemas, conformance vectors
docs/            architecture, API, MCP, CLI, security, deployment
src/             daemon, domain, HTTP/MCP, CLI, PWA
tests/           unit, REST/SSE, MCP, CLI, conformance, smoke
scripts/         installers, smoke test

Security

Report vulnerabilities privately to security@buskeeper.dev; do not open a public issue. The daemon is the trust boundary; lane tokens are hashed and scoped, item content is untrusted, and every transition is recorded. The local edition binds to loopback by default. See SECURITY.md and docs/SECURITY.md.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md and CODE_OF_CONDUCT.md first. For larger changes, open an issue so the protocol impact can be discussed before implementation.

License

• Software (src/, tests/, scripts/, .github/): Apache-2.0. See LICENSE.

• Protocol and documentation (spec/, docs/): CC BY 4.0. See LICENSE-SPEC.md.

• Trademarks: see NOTICE.

Buskeeper is a product of Ngonart OU.