AFFiNE

What it is

AFFiNE is an open-source workspace that puts docs, a whiteboard and databases in one app. They are all built from the same blocks: a line of text is a block, and so is a shape on a canvas. Every doc has two modes. Page mode is a linear page that fits your screen, and Edgeless mode is an endless canvas for mind maps, slides and diagrams. The app is local-first, so a local workspace lives on your own disk and works offline. AFFiNE Cloud or your own server adds sync across devices and real-time collaboration.

1. You open AFFiNE on the web, the desktop or your own server
2. You type / in a doc and pick blocks from the slash menu
3. You switch the same doc to Edgeless mode to draw around it
4. Selected blocks turn into a Table or Kanban database
5. Cloud or self-hosted sync lets others edit with you live

Who it suits

People who keep notes in one app and sketch on a whiteboard in another, and would rather have both in one doc. Small teams who want their docs on their own server and can run Docker, backups and upgrades themselves. The docs also say who should look elsewhere. AFFiNE is not a typesetting system, so if you like the rulers and layout buttons of Word, Google Docs or Pages, it is the wrong tool.

Where to use it

In a browser at https://app.affine.pro, in the desktop apps for Windows, macOS and Linux, and in the iOS and Android apps. The mobile apps focus on capturing and reviewing notes and sync through AFFiNE Cloud. The desktop app is the most complete, with the full Edgeless whiteboard. Beyond the apps, the maker’s pages name these connections.

• The workspace MCP endpoint, which lets Claude Code, Cursor, Cline and other MCP clients that accept a Bearer header, or can launch the local mcp-remote bridge, search and read one workspace. OAuth-only clients cannot use it
• AI inside the app, through AFFiNE AI or, on a self-hosted server, your own OpenAI, Anthropic, Gemini or FAL keys
• A desktop app pointed at your own server, added from the workspace list panel
• Export of docs to Markdown or HTML, to move them to another machine

How to set it up

Get it saves a zip of Mindket’s setup notes in your downloads folder, with a page for each route from the maker’s README and docs. The web app needs only a browser, and the desktop apps need only a download. The steps below run your own server, the route the Docker Compose page recommends.

1. Install Docker with Compose v2. The command docker compose version should answer.
2. Make a deployment folder. Create affine with a config folder inside, as below.
3. Download the two files. The Compose file and the example config come from the latest release.
4. Set the external URL. In config/config.json, server.externalUrl is the address users open.
5. Start the stack. Run docker compose up -d and check it with docker compose ps.
6. Create the first administrator. Open http://localhost:3010 and follow the prompts.

mkdir affine
cd affine
mkdir -p config
curl -L -o docker-compose.yml \
  https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml
curl -L -o config/config.json \
  https://github.com/toeverything/AFFiNE/releases/latest/download/config.json.example
docker compose up -d
docker compose ps

The one-time migration container should finish, while AFFiNE, PostgreSQL and Redis keep running. If something fails to start, the page gives this line.

docker compose logs --tail=200 affine affine_migration

How to use it

Type / on a blank line to open the slash menu and pick a block. Basic blocks also take Markdown shortcuts, as the Blocks page lists them.

#    at the start of a line makes a heading
>    at the start of a line makes a quote
---  followed by a space makes a divider

Any block can be dragged by its handle. Select several blocks and use convert into database, and they become a database with Table or Kanban views. The Blocks page says this works well for turning a to-do list into a kanban. In Edgeless mode, text blocks, images and shapes can be laid out as a slide, and frames and groups gather them into sets. Collections work as smart folders. Add filters in All docs and click Save as New Collection, and every doc that matches the rules joins it. To reuse a layout, tick Template in a doc’s Property and set it for the Journal or for every new doc.

A local workspace stays on your device. To share it, enable AFFiNE Cloud in the workspace settings after you sign in, then invite people by email from the members area. They join once they accept the email.

Example

You keep project notes in an AFFiNE Cloud workspace and want Claude Code to answer from them. In AFFiNE you open Settings, then Integrations, then MCP Server, and create a credential labelled Claude Code. You leave the access mode on Read only and copy the endpoint and token, since the token shows once. Then you run the command from AFFiNE’s MCP page.

claude mcp add --transport http affine \
  "https://app.affine.pro/api/workspaces/<workspace-id>/mcp" \
  --header "Authorization: Bearer <your-credential>"

Claude Code then has two tools from AFFiNE, as the MCP page describes them. doc_search runs keyword and semantic search across the workspace, whiteboard text included, and returns short passages with page or canvas locators. read_document fetches a whole doc by its ID. Both stay inside that one workspace and your permissions, and revoking the credential cuts off only this client.

For newcomers and experts

If you are new. Local-first means your workspace is stored on your own machine and you can edit it without an internet connection. The download page says the desktop app syncs only when you choose to sign in to AFFiNE Cloud. A block is any piece of a doc you can move, from a paragraph to a to-do, a shape or a database. Start with the desktop app and a local workspace. No account is needed. Self-hosting is for people who already run servers. The self-host docs say a managed workspace is usually simpler if you do not want to look after Postgres, Redis, backups and upgrades.

For experts. The editor is BlockSuite, Toeverything’s open-source collaborative editor. The README names y-octo, a native, thread-safe Yjs CRDT implementation, as the core engine that gives the AFFiNE client and server their local-first functionality. It also names OctoBase, a data engine written in Rust. The desktop app is Electron wrapping the prebuilt web app, with native modules in Rust built through napi-rs.

A self-hosted server reads config/config.json from ./config. server.externalUrl must be the final address users open, and copilot.byok.enabled lets workspace owners add their own provider keys. Settings saved in the Admin Panel at /admin/settings take effect at once. Provider keys belong to workspaces, never to the server config. The AI page gives this block to allow OpenAI-compatible endpoints.

{
  "copilot": {
    "enabled": true,
    "byok": {
      "enabled": true,
      "allowCustomEndpoint": true,
      "allowPrivateEndpoint": false
    }
  }
}

Keep allowPrivateEndpoint off unless every workspace administrator is trusted to send provider requests into the private network. Transcription and workspace indexing need a Gemini key stored on the server, or an AFFiNE AI plan fallback where available, and indexing also needs the indexer turned on. The official Compose file already ships PostgreSQL with pgvector. The MCP endpoint is POST /api/workspaces/{workspace-id}/mcp over stateless Streamable HTTP. After a credential is rotated, the old token keeps working for up to 24 hours, or until its expiry if sooner.

Good to know

These come from the README, the LICENSE and the maker’s pages.

• License: GitHub labels it Other. The LICENSE file puts code outside packages/backend and packages/common/native under MIT. The README says Community Edition is free to self-host under MIT. But the license file in packages/backend/server puts the parts of those two folders shipped in Community Edition under MPL 2.0. The rest is the AFFiNE Enterprise Edition license, which the self-host page calls source-available. It allows production use only with a subscription for the right number of seats
• Seats: the docs give each workspace on a self-hosted instance at most 10 seats for free. More need the paid Team Plan, at $10 a seat a month billed yearly or $12 monthly, or an Installable License from sales for a network that cannot reach AFFiNE’s license service
• Data sent out: the self-host page says a disconnected network needs separate plans for fonts from cdn.affine.pro, default client telemetry and images from ghcr.io. The Team Plan checks its license against app.affine.pro
• Upgrades: read the release notes, back up and compare the old and new Compose files first. The Upgrade page says not to use latest as a blind production upgrade path. Version 0.27.4 moved the data folders, so an older Compose file needs care
• Backups: a full backup is the Postgres dump, ./data/storage for uploads and the config files. A database-only restore leaves the uploaded files out. The docs say to test a restore
• Identity: the self-host page names OIDC for single sign-on, with MFA at your identity provider. It says not to choose AFFiNE today if you need SAML or SCIM provisioning, built-in audit logs or an official Kubernetes deployment
• MCP writes: read only is the default. The MCP page says the implementation it reviewed on October 26, 2026 limits write tools to development or canary deployments
• Builds: Stable is for daily work, Beta previews features with light testing, and Canary is published as soon as it is built
• Contributing: a pull request merges only after every committer signs the Contributor License Agreement