AFFiNE User Guide

1. Quick Start

AFFiNE is an open-source, privacy-focused workspace that combines documents, whiteboards, and databases into a single unified application. It provides local-first data ownership with optional cloud sync, real-time collaboration, and an AI-powered copilot — all in one platform.

Key features:

• Page mode — rich-text documents with blocks for paragraphs, lists, code, tables, images, bookmarks, LaTeX, callouts, and embedded documents
• Edgeless mode — infinite canvas whiteboard with shapes, connectors, freehand drawing, text, mind maps, and frames
• Database views — structured data with table, kanban, and custom property types
• Collections — smart document groups with filter rules and manual pinning
• AI Copilot — built-in AI assistant for writing, summarization, translation, and image generation
• Real-time collaboration — CRDT-based sync for simultaneous multi-user editing
• Cross-platform — web, desktop (Windows, macOS, Linux), and mobile (Android, iOS)
• Self-hostable — run your own AFFiNE Cloud server with Docker

Prerequisites: A modern web browser, or the desktop/mobile app installed.

Get started in 30 seconds:

1. Visit affine.pro and click Get Started Free
2. Create a workspace
3. Click New Page to start writing, or switch to Edgeless mode for whiteboarding

Tip

For the fastest experience, download the desktop app — it works offline and syncs when connected.

What to try next:

• Create your first edgeless whiteboard (see Core Usage)
• Set up a database to track tasks (see Common Tasks)
• Explore the AI Copilot (see Core Usage)

2. Installation

System Requirements

Installation Methods

Desktop (Recommended)

Download the desktop app for your platform from affine.pro/download:

• Windows — .exe installer or Microsoft Store
• macOS — .dmg disk image
• Linux — .AppImage or .deb package

# Linux AppImage
chmod +x AFFiNE-*.AppImage
./AFFiNE-*.AppImage

Web App

Access AFFiNE directly at app.affine.pro — no installation required.

Mobile

• Android — Google Play Store
• iOS — Apple App Store

Self-Hosted

See the Admin Guide for full deployment instructions. Quick start:

docker pull ghcr.io/toeverything/affine-graphql:stable

Post-Install Verification

Launch the application. You should see the AFFiNE welcome screen with options to create a new workspace or sign in.

Important

The desktop app works fully offline. Cloud sync requires creating an AFFiNE Cloud account or connecting to a self-hosted server.

Install Troubleshooting

3. Configuration

AFFiNE's user-facing configuration is managed through the in-app settings panel. Access it via the gear icon in the sidebar.

General Settings

Editor Settings

Cloud & Sync

Tip

For full server configuration options (environment variables, authentication providers, storage backends), see the Admin Guide Configuration Reference.

4. Core Usage

Working with Pages

Pages are rich-text documents built from composable blocks. Every page starts in Page mode — a vertical document layout optimized for writing.

Creating a page:

1. Click New Page in the sidebar (or press Ctrl/Cmd + N)
2. Type a title and press Enter to begin writing
3. Use the slash menu (/) to insert any block type

Block types available via slash menu:

Note

Block types are managed by the BlockSuite editor framework. Each block type supports drag-and-drop reordering, copy/paste, and conversion between types.

Inline formatting:

Inline elements: Beyond basic formatting, AFFiNE supports inline LaTeX ($formula$), inline mentions (@), footnotes, and linked document references.

Working with Edgeless (Whiteboard)

Switch any page to Edgeless mode using the toggle at the top of the page. Edgeless provides an infinite canvas for visual thinking.

Edgeless tools:

Tip

Hold Space and drag to pan the canvas. Use Ctrl/Cmd + scroll to zoom in and out. Double-click empty canvas to create a text element.

Frames and presentations: Group elements into frames for slide-like presentations. Navigate between frames sequentially using the frame panel.

Databases

AFFiNE includes a built-in database system for structured data. Insert a database from the slash menu (/database).

Database views:

Property types: Text, number, date, select, multi-select, checkbox, link, progress, and more. Each row in a database is also a full AFFiNE page that can be opened and edited.

Warning

Database columns share property definitions across views. Renaming or deleting a property affects all views of that database.

Collections

Collections organize pages into logical groups. Access them from the sidebar.

• Manual collections — drag pages into a collection to organize them
• Smart collections — define filter rules (by tag, creation date, property values) to auto-populate
• Pinned collections — pin frequently-used collections to the sidebar

Search and Quick Search

Press Ctrl/Cmd + K to open Quick Search. Search across all pages by title and content. Results update as you type.

Search features:

• Full-text search across all workspace pages
• Recent pages list
• Quick actions (create new page, navigate to settings)
• Linked doc insertion from search results

Journal

The Journal feature provides a daily-entry interface. Each day gets its own page, accessible from the sidebar calendar. Journal pages are regular pages with date-based organization.

AI Copilot

AFFiNE integrates an AI assistant (Copilot) for content creation and editing. The AI button appears in the editor toolbar and sidebar.

AI capabilities:

Important

AI features require an AFFiNE Cloud Pro subscription or a self-hosted server with configured AI providers (OpenAI, Google Gemini, or Cloudflare Workers AI). See the Admin Guide for provider configuration.

Import and Export

Supported import formats:

• Markdown (.md)
• HTML
• Notion export (.zip)
• DOCX (via native parser)

Supported export formats:

• Markdown
• HTML
• PDF
• PNG (edgeless snapshots)

Access import/export from the page menu (three-dot menu at the top of a page).

Keyboard Shortcuts

5. Common Tasks

Create a Project Tracker Database

Goal: Set up a kanban-style project board with custom properties.

1. Create a new page and type a title (e.g., "Project Board")
2. Type /database and select Database — Full Page
3. Add properties: Status (select: To Do, In Progress, Done), Priority (select: High, Medium, Low), Due Date (date)
4. Add rows for each task
5. Switch to Kanban view and group by Status

Verify: Tasks appear as cards in their respective status columns.

Set Up a Team Workspace with Cloud Sync

Goal: Create a shared workspace for your team.

1. Sign in to AFFiNE Cloud (or your self-hosted server)
2. Create a new workspace
3. Open Settings → Members
4. Invite team members by email
5. Set permissions: Owner, Admin, Editor, or Viewer

Tip

Workspace members see all pages by default. Use doc-level permissions to restrict access to sensitive documents.

Verify: Invited members can see and edit workspace content after accepting the invitation.

Create a Presentation with Edgeless Frames

Goal: Build a slide deck using the whiteboard canvas.

1. Open a page and switch to Edgeless mode
2. Select the Frame tool from the toolbar
3. Draw a frame for each slide
4. Add content inside each frame: text, shapes, images, embedded docs
5. Use the Frame Panel (sidebar) to reorder slides
6. Present by clicking the play button in the frame panel

Verify: Frames navigate sequentially in presentation mode.

Import Notes from Notion

Goal: Migrate your Notion workspace to AFFiNE.

1. In Notion: Settings → Export → choose Markdown & CSV
2. In AFFiNE: open the page menu → Import → Notion
3. Select the exported .zip file
4. Pages, databases, and nested structure are preserved

Verify: Imported pages appear in the sidebar with their original hierarchy.

Organize Pages with Collections

Goal: Create a smart collection that auto-groups pages by tag.

1. In the sidebar, click Collections → New Collection
2. Choose Rules-based collection
3. Add a filter rule: Tag → contains → "meeting-notes"
4. Name the collection "Meeting Notes"

Verify: All pages tagged "meeting-notes" automatically appear in the collection.

Use AI Copilot for Writing

Goal: Draft a blog post outline with AI assistance.

1. Create a new page
2. Click the AI button in the toolbar (or type /ai)
3. Enter a prompt: "Write an outline for a blog post about remote work productivity"
4. Review the generated content
5. Select sections and use Make longer to expand them

Verify: AI-generated content appears in the editor and can be edited like any other content.

Set Up Daily Journaling

Goal: Use the journal feature for daily reflections.

1. Click Journal in the sidebar
2. Today's journal page opens (or is created)
3. Write your daily entry
4. Use the calendar widget to navigate to past entries
5. Link journal entries to relevant project pages using @ mentions

Verify: Each day has its own dedicated page accessible via the calendar.

Connect to a Self-Hosted Server

Goal: Use the desktop app with your organization's AFFiNE server.

1. Open Settings → Account
2. Click Custom Server
3. Enter the server URL (e.g., https://affine.yourcompany.com)
4. Sign in with your credentials (email/password or SSO)

Warning

Switching servers may require creating a new local workspace. Existing local data is not automatically migrated to the new server.

Verify: The server name appears in the app header, confirming the connection.

6. Troubleshooting

Diagnostic Decision Tree

Problem?
├─ Can't sign in → Check credentials, server URL, network
├─ Sync not working → Check cloud connection, server status
├─ Editor performance → Check document size, browser resources
├─ Desktop app issues → Check app version, clear cache
└─ Mobile issues → Update app, check OS compatibility

Error: Native binding package version mismatch

Cause: The native Rust modules are out of sync with the JavaScript packages after a partial update.

Solution:

1. Delete node_modules across the monorepo
2. Run yarn install to reinstall all dependencies
3. Rebuild native modules

Prevention: Always run yarn install after pulling updates. The app expects native binding version 0.26.3.

Sync fails silently with no user prompt

Cause: Network interruption or server-side error during CRDT sync. (Community issue #14846)

Solution:

1. Check your network connection
2. Open Settings → Sync to verify cloud status
3. If status shows error, try signing out and back in
4. As a last resort, export your pages and reimport

Prevention: Monitor the sync status indicator in the bottom bar. Enable notifications for sync failures when available.

Desktop app: Link preview and image proxy broken on self-hosted server

Cause: The Electron app's link preview and image proxy rely on the server's external URL configuration. (Community issue #14865)

Solution:

1. Verify AFFINE_SERVER_EXTERNAL_URL is set correctly on the server
2. Ensure the server is accessible from the desktop app's network
3. Check that HTTPS certificates are valid if using SSL

Prevention: Configure AFFINE_SERVER_EXTERNAL_URL to the publicly accessible URL during initial server setup.

Self-hosting: Unable to connect

Cause: Server configuration or network misconfiguration. (Community issue #14872)

Solution:

1. Verify the server is running: check container logs
2. Confirm the port (default 3010) is accessible
3. Check AFFINE_SERVER_HOST and AFFINE_SERVER_PORT environment variables
4. Verify Redis and PostgreSQL connectivity

Prevention: Use the /info health endpoint to verify the server is responding correctly.

Keyboard shortcuts conflict with Polish (and other) language input

Cause: AFFiNE's keyboard shortcuts can interfere with input methods for certain languages. (Community issue #14519)

Solution:

1. Switch to an English keyboard layout temporarily for shortcut use
2. Use the slash menu (/) instead of keyboard shortcuts where possible

OIDC sign-in fails with "email required"

Cause: The OIDC provider is not returning an email address in the token claims. (Community issue #14683)

Solution:

1. Configure your OIDC provider to include email in the token scope
2. Ensure the user account has a verified email address
3. Check the OIDC provider's claim mapping configuration

Prevention: Verify OIDC configuration includes email scope before deploying.

Mobile: Text entered twice on Samsung keyboard

Cause: Composing-event handling issue with Samsung keyboard input method. (Community issues #12806, #14021)

Solution:

1. Switch to Gboard or another keyboard app
2. Disable predictive text temporarily
3. Update the AFFiNE app to the latest version

Markdown export: Inconsistent table format

Cause: Table column alignment metadata may not round-trip correctly during markdown export. (Community issue #14860)

Solution:

1. After export, manually adjust table alignment markers (|---|:---:|---:|)
2. Use the HTML export format as an alternative for complex tables

Error 500 on Mac Desktop and iOS

Cause: Server-side error during client communication. (Community issue #14868)

Solution:

1. Check server logs for the specific error
2. Verify the server version matches the client version
3. Clear the app cache and retry

Comment feature unavailable in Firefox/Safari

Cause: Browser-specific rendering differences in the comment overlay. (Community issue #14852)

Solution:

1. Use Chrome or Edge for full feature support
2. Check for browser updates
3. Disable browser extensions that may interfere

Audio transcription ignores OpenAI config on self-hosted

Cause: The copilot audio transcription feature may attempt to use Gemini models instead of configured OpenAI provider. (Community issue #14859)

Solution:

1. Verify the copilot provider configuration in server settings
2. Ensure the OpenAI API key is correctly set
3. Update to the latest server version with the fix

7. FAQ

Q: Is AFFiNE free?

AFFiNE is open-source (MIT licensed) and free to use. The desktop, web, and mobile apps are free. AFFiNE Cloud offers a free tier with limited storage, and Pro/Team plans for additional features like unlimited cloud storage, AI copilot, and team collaboration.

Q: Can I use AFFiNE completely offline?

Yes. The desktop app works fully offline with local data storage. Pages, whiteboards, and databases are all stored locally. Cloud sync is optional and only activates when configured.

Q: How does AFFiNE sync data between devices?

AFFiNE uses CRDT (Conflict-free Replicated Data Type) technology via the y-octo library (a Rust implementation of the Yjs protocol). Changes merge automatically without conflicts, even when multiple users edit simultaneously.

Q: Can I self-host AFFiNE?

Yes. AFFiNE provides Docker images for self-hosting. You need PostgreSQL, Redis, and Node.js. See the Admin Guide for detailed deployment instructions.

Q: What data formats does AFFiNE support for import?

Markdown, HTML, Notion exports (.zip), and DOCX files. The import system preserves document structure, formatting, and embedded content where possible.

Q: How do I back up my data?

• Local data: Back up the AFFiNE data directory (~/.config/AFFiNE on Linux, ~/Library/Application Support/AFFiNE on macOS, %APPDATA%/AFFiNE on Windows)
• Cloud data: Export workspaces from Settings → Workspace → Export
• Self-hosted: Back up the PostgreSQL database and blob storage

Q: Can I use my own AI models with AFFiNE?

Yes, on a self-hosted server. Configure custom OpenAI-compatible API endpoints in the server's copilot provider settings. Supported providers include OpenAI, Google Gemini, Anthropic, and Cloudflare Workers AI. See the Admin Guide for provider configuration.

Q: What is BlockSuite?

BlockSuite is AFFiNE's open-source editor framework. It provides the block-based editing engine that powers both Page mode and Edgeless mode. BlockSuite is developed by the same team and is designed to be reusable in other applications.

Q: How do I recover deleted pages?

Deleted pages go to Trash in the sidebar. You can restore them from there within 30 days. After that, they are permanently deleted.

Q: Can I embed external content?

Yes. Use the /embed slash command to embed content from supported services (YouTube, Figma, Google Maps, etc.) via iframe. You can also embed other AFFiNE pages using the /linked command.

Q: Does AFFiNE support MCP (Model Context Protocol)?

Yes. AFFiNE supports MCP for AI integration, allowing AI tools to create and interact with workspace documents via WebSocket API. Note: documents created via MCP may not appear in the workspace doc list until synced. (Community issue #14582)

Q: How do workspace permissions work?

Workspace roles: Owner (full control), Admin (manage members, settings), Editor (create and edit), Viewer (read only). Document-level permissions can further restrict or grant access to specific pages.