# Buskeeper Local

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

Buskeeper Local is the free, single-workspace edition of
[Buskeeper](https://buskeeper.dev). 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.

## 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`](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](https://bun.sh) >= 1.2 for source installs. Release binaries
are built for Linux, macOS, and Windows on x64 and arm64.

### Release binary

Linux/macOS:

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

Windows PowerShell:

```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

```sh
bun install
bun run build
./dist/buskeeper serve
```

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

### First run

```sh
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.

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

For a remote daemon over HTTP:

```json
{
  "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`](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:

| Variable | Default | Purpose |
| --- | --- | --- |
| `BUSKEEPER_HOME` | platform data dir | Database, token, attachments |
| `BUSKEEPER_BIND` | `127.0.0.1` | Bind address |
| `BUSKEEPER_PORT` | `7331` | Port |
| `BUSKEEPER_BODY_MAX` | `8192` | Item body bytes |
| `BUSKEEPER_ATTACH_MAX` | `10485760` | Upload bytes |
| `BUSKEEPER_ATTACH_IMAGE_MAX_BYTES` | `5242880` | Processed image cap |
| `BUSKEEPER_ATTACH_IMAGE_MAX_DIM` | `2048` | Image long edge |
| `BUSKEEPER_ATTACH_PDF` | `false` | Gated PDF path |
| `BUSKEEPER_BODY_RETENTION_DAYS` | unset | Redact bodies after N days |
| `BUSKEEPER_ATTACH_RETENTION_DAYS` | unset | Redact attachments after N days |
| `BUSKEEPER_RATE_LIMIT_PER_MINUTE` | `240` | Mutations per actor+IP |

`buskeeper serve --help` lists CLI overrides.

## Build and verify

```sh
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

```text
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`](SECURITY.md)
and [`docs/SECURITY.md`](docs/SECURITY.md).

## Contributing

Issues and pull requests are welcome. Read
[`CONTRIBUTING.md`](CONTRIBUTING.md) and
[`CODE_OF_CONDUCT.md`](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`](LICENSE).
- Protocol and documentation (`spec/`, `docs/`): CC BY 4.0. See
  [`LICENSE-SPEC.md`](LICENSE-SPEC.md).
- Trademarks: see [`NOTICE`](NOTICE).

Buskeeper is a product of Ngonart OU.