Bee

English | 简体中文

Open-source, self-hostable collaborative documents (Quip-style): real-time editing, Markdown, version history, inline comments, folder tree, whiteboards, and private / member / public-link sharing. Bee is also a remote MCP server, so Claude and other MCP clients can read and edit your documents.

A hosted instance runs at bee.zippyzoo.dev.

Bee is built with Claude Code: most of the code was written by Claude, with a human directing, reviewing and testing it. Commits that Claude wrote carry a Co-Authored-By: Claude trailer.

Self-hosting

You need Docker with Compose v2 (Docker Desktop, OrbStack, or Docker Engine on Linux). The whole stack (PostgreSQL, API, collaboration server, web client and a Caddy proxy) runs from docker-compose.yml, and only the proxy port is exposed.

git clone https://github.com/liyjie00/bee.git && cd bee
cp .env.example .env
# Set SESSION_SECRET and COLLAB_SECRET to long random strings, e.g.:
#   openssl rand -hex 32
# Set BEE_PUBLIC_URL to the origin people will open, e.g. https://docs.example.com
docker compose up -d --build

Then open BEE_PUBLIC_URL (default http://localhost:7070) and create the first account. Database migrations run automatically when the API starts.

Putting it on the internet

The proxy speaks plain HTTP on BEE_PORT (default 7070). Put TLS in front of it with whatever you already use: a reverse proxy (Caddy, nginx, Traefik), a load balancer, or a tunnel such as Cloudflare Tunnel pointing your hostname at http://localhost:7070. The proxy must pass WebSocket upgrades for /collab.

Set BEE_PUBLIC_URL to the public https:// origin. It is used for share links, secure cookies, the CSRF origin check, and as the OAuth issuer of the MCP server, so it must match what the browser sees. Once your own account exists you can close sign-ups with ALLOW_REGISTRATION=false.

Updating

git pull
docker compose up -d --build

Backups

Data lives in two Docker volumes: bee_pgdata (PostgreSQL) and bee_uploads (uploaded files). Keep a copy of .env too: without the same SESSION_SECRET (or AI_KEYS_SECRET) users' saved AI keys cannot be decrypted.

docker compose exec postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' > bee.dump
docker compose exec api tar -C /data/uploads -czf - . > uploads.tgz

deploy/backup.sh is the daily backup script of the reference deployment (dump, uploads and .env, copied to a NAS) and can serve as a starting point.

Configuration

All settings are environment variables in .env; see .env.example for the full list with comments.

Ask AI needs no server configuration: each user connects their own AI account (OpenRouter sign-in or an API key) in Settings.

Related MCP server: Google Workspace MCP

Claude and other MCP clients

Bee is a remote MCP server at <BEE_PUBLIC_URL>/mcp (Streamable HTTP). Claude can list folders and documents, search, read documents as Markdown, create and edit them, rename and move them, draw diagrams on whiteboards (new, existing, or embedded in a document) and describe them, and read, add, reply to and resolve comments, always with the signed-in user's permissions. Edits go through the collab server as ordinary Yjs changes, so people who have the document open see them live; only the top-level blocks whose Markdown changed are replaced, so other paragraphs keep their comments and block links.

• Claude (claude.ai / desktop / mobile): Settings → Connectors → Add custom connector, URL <BEE_PUBLIC_URL>/mcp. Claude registers itself (OAuth dynamic client registration) and opens Bee's sign-in and consent page once. Connected apps can be revoked in Bee under Settings.

• Claude Code / scripts: create a personal API token in Bee under Settings, then claude mcp add --transport http bee <BEE_PUBLIC_URL>/mcp --header "Authorization: Bearer <token>". The same token works for the REST API (Authorization: Bearer).

Development

Requires Node.js 22+ and Docker (for PostgreSQL).

corepack enable
pnpm install
cp .env.example .env
docker compose up -d postgres
pnpm db:migrate
pnpm dev

pnpm test runs the test suites (the API tests use a bee_test database on the dev Postgres), pnpm typecheck and pnpm lint the checks. See CONTRIBUTING.md before opening a pull request.

Layout

Public port 7070 (Caddy, config inline in docker-compose.yml) routes /api/*, /mcp, /oauth/* and /.well-known/oauth-* to api:8421, /collab* to collab:1234, and everything else to web:8423. Dev Postgres listens on localhost:54329.

Reference deployment

bee.zippyzoo.dev runs this same docker-compose.yml on a Mac mini behind a Cloudflare Tunnel. deploy/sync.sh deploys committed main there over SSH: it runs typecheck and tests locally, ships git archive HEAD, creates .env with fresh secrets on first deploy, rebuilds the stack and waits for /api/health. To use it for your own server, copy deploy/deploy.env.example to deploy/deploy.env (not committed) and fill in your SSH host and public URL.

License

Bee is free software under the GNU Affero General Public License v3.0 (AGPL-3.0-only). If you run a modified version for others over a network, the AGPL requires you to offer them the source of your version.

Commercial licenses are available for organizations that want to use, modify or embed Bee without the AGPL's obligations. Contact contactus@bee.zippyzoo.dev.

Contributions are accepted under the Contributor License Agreement, which is what makes dual licensing possible; see CONTRIBUTING.md.