The open, local-first agent observability + collaboration stack: record, replay, diff, and inspect agent behavior - then plan and ship with humans in the same workspace.
Shared workspace where AI agents and humans plan, write, and ship together. Record -> Inspect -> Diff -> Act. Autonomous collaboration. Versioned context. MCP-native.
Quick Start · Why VisBoard · Architecture · Features · MCP Server · Layout
VisBoard is a shared workspace where agents and humans plan, write, and ship together. It provides note versioning, checklist tracking, file storage, agent-scoped API keys, and an MCP server so AI coding agents directly interact with project context -- without switching tools.
Built for teams designing autonomous agent collaboration, not just chat. OSS-first, self-hostable with Docker Compose, MIT-licensed.
Phase 1: OSS self-hosted only. See SPEC.md for the full implementation spec.
- Agents as first-class collaborators - not just chat participants. Agents get scoped API keys, their own AGENTS.md protocol per project, and direct MCP access to board state.
- Versioned markdown notes - every note edit creates a version with ETag concurrency control. No silent overwrites, no lost context.
- Live event stream - SSE
/events/streampushes changes in real time. Agents subscribe to board events and react without polling. - MCP-native architecture - the
@visboard/mcppackage exposes the full board model through the Model Context Protocol. Cursor and Claude Desktop connect directly. - Portable workspaces - zip export/import with
visboard exportandvisboard import. Move workspaces between self-hosted instances or migrate to SaaS.
- Agent workspace, not project management - VisBoard is designed for how agents think: markdown notes, checklists, file attachments, and a compact context API. It is not a kanban board.
- AGENTS.md protocol - each project auto-generates an
AGENTS.mdfile defining the project's conventions, tool schema, and workspace rules. Agents read this on connect and behave accordingly. - Context API, not full-page dumps -
/contextreturns a compact project snapshot optimized for agent context windows. No token waste on sidebar state.
- Node.js 22+
- pnpm 9+
- PostgreSQL 16 (or Docker)
# 1. Install and build
pnpm install
pnpm build
# 2. Start Postgres (Docker)
docker compose up -d postgres
# 3. Configure environment
cp .env.example .env
# 4. Migrate database
pnpm --filter @visboard/db db:migrate
# 5. (Optional) Seed demo workspace
pnpm --filter @visboard/db db:seed
# Preferred for admin token:
pnpm --filter @visboard/cli exec visboard auth bootstrap --name "My Workspace"
# 6. Start API (terminal 1)
pnpm --filter @visboard/api dev
# 7. Start web UI (terminal 2)
pnpm --filter @visboard/web devOpen http://localhost:3000 -- paste your PAT in Settings.
docker compose up -d
pnpm --filter @visboard/db db:migrate # against localhost:5432chmod +x scripts/smoke.sh
./scripts/smoke.shflowchart LR
A[Agent / Cursor\nMCP Client] --> B[VisBoard API\n:8080]
B --> C[(Postgres)]
B --> D[Event Stream\nSSE :8080/events/stream]
E[Human Browser\nNext.js :3000] --> B
F[visboard CLI] --> B
G[MCP Server\n@visboard/mcp] --> B
H[Filesystem] --> B
| Feature | Description |
|---|---|
| Workspaces & projects | Multi-project boards with slug-based routing and isolated context. |
| Markdown notes | Full markdown with frontmatter, versioning, and ETag concurrency. |
| Checklists | Task lists with assignees and agent check/uncheck via API. |
| File storage | Local filesystem uploads per project. No S3 dependency. |
| Context API | Compact project snapshot for agent context windows (/context, /agents.md). |
| Event stream | SSE stream (/events/stream) for real-time agent subscriptions. |
| Feature | Description |
|---|---|
| AGENTS.md protocol | Auto-generated agent conventions file per project. |
| Scoped API keys | PAT for humans, agent keys with read/write scope restrictions. |
| MCP server | Full board model exposed via Model Context Protocol for Cursor, Claude Desktop. |
| Export / import | Zip workspace export and roundtrip import (visboard export, visboard import). |
| OpenAPI spec | Full REST specification at openapi/openapi.yaml. |
visboard auth bootstrap --name "Acme"
visboard project create --name "Pipeline" --slug pipeline
visboard note create --project pipeline --title "Spec" --file ./SPEC.md
visboard agent create --name "Reviewer" --scopes read,write:checklists --project pipeline
visboard context --project pipeline
visboard agents-md --project pipeline
visboard export --workspace acme --out ./export.zip
visboard import --file ./export.zip --slug acme-copy --name "Acme Copy"The @visboard/mcp package exposes VisBoard to MCP-compatible clients (Cursor, Claude Desktop).
# Build and run (stdio transport)
pnpm --filter @visboard/mcp build
VISBOARD_TOKEN=vb_pat_... VISBOARD_API_URL=http://localhost:8080/v1 \
pnpm --filter @visboard/mcp exec visboard-mcpConfigure in your MCP client with env vars VISBOARD_TOKEN, VISBOARD_API_URL (alias VISBOARD_BASE_URL), and optional VISBOARD_WORKSPACE. The package is packed with ./scripts/pack-sdks.sh; it is not published to npm in this cycle. Point Cursor at node packages/mcp/dist/index.js after pnpm --filter @visboard/mcp build.
| Package | Description |
|---|---|
@visboard/shared |
Zod schemas, IDs, scopes, event types |
@visboard/db |
Drizzle ORM schema, migrations, seed |
@visboard/agents-md |
AGENTS.md protocol generator |
@visboard/api |
Hono HTTP server |
@visboard/sdk |
TypeScript client |
@visboard/cli |
visboard command-line tool |
@visboard/web |
Next.js web UI |
@visboard/mcp |
MCP server for Cursor / Claude Desktop |
visboard/
├── apps/
│ ├── api/ Hono HTTP server (:8080)
│ └── web/ Next.js web UI (:3000)
├── packages/
│ ├── shared/ Zod schemas, IDs, scopes, event types
│ ├── db/ Drizzle ORM schema + migrations + seed
│ ├── agents-md/ AGENTS.md protocol generator
│ ├── agent-sdk/ Agent run / handoff transport
│ ├── sdk/ TypeScript client
│ ├── cli/ visboard command-line tool
│ └── mcp/ MCP server
├── docs/ Additional documentation
├── openapi/ OpenAPI 3.1 specification
├── scripts/ Smoke tests, pack-sdks
├── AGENT.md Contributor conventions
├── SECURITY.md Disclosure and threat notes
├── LICENSE MIT
└── README.md This file
- OpenAPI 3.1 spec:
openapi/openapi.yaml /v1: workspaces, projects, notes, checklists, files, agents, events, context/v2: boards, handoffs, templates, automations, integrations/health(liveness) and/readyz(Postgresselect 1) onhttp://localhost:8080- Errors: RFC 7807
application/problem+json - Token pepper:
VISBOARD_TOKEN_PEPPERmust be at least 32 characters
Security, contributor, and agent notes: SECURITY.md, CONTRIBUTING.md, AGENT.md.
Requirements: Node 22+, pnpm 9+, Docker (Postgres).
pnpm install
pnpm build
pnpm test
pnpm lint
pnpm typecheckCI runs on every push to main and on pull requests.
- PostgreSQL required - VisBoard does not support SQLite. Postgres-specific features (row-level locking, LISTEN/NOTIFY on
visboard_events) are used throughout. Use the Docker Compose setup for development. - File storage is local - File uploads write to the local filesystem. For multi-replica deployments, mount a shared volume or replace the storage backend.
- SSE across API processes - Event rows are durable.
LISTEN/NOTIFYon channelvisboard_eventsfans the latest project event to other API processes sharing the same database. Redis is not used. - First-time PAT generation - On fresh install, use
visboard auth bootstrapto generate the initial Personal Access Token. The web UI requires a PAT to authenticate. - Health version -
GET /healthreports package version0.1.0, not a git SHA.
Most agent-observability dashboards are read-only. VisBoard is a shared workspace where agents and humans plan, write, and ship together - the action surface at the end of the loop (Record -> Inspect -> Diff -> Act).
Everything the new YC agent-observability startups are building - open-sourced, self-hosted, MIT.
MIT -- see LICENSE. Copyright © 2026 LatticeAG.