Hyperfector

Free, self-hosted real-time collaboration for Obsidian.

Hyperfector is an open-source Obsidian plugin that gives you real-time multi-user collaborative editing — without subscriptions, without sending your data to a third party. Designed for individuals and small teams, but built to scale to larger teams too.

Don't want to self-host? A managed hosted service is coming soon at hyperfector.com.

Features

• Real-time collaborative editing — multiple users edit the same Markdown file simultaneously with live cursor positions
• CRDT-based sync — conflict-free merging via Yjs, works offline and reconciles on reconnect
• Folder sharing — share any vault folder; file creates, renames, and deletes propagate to all users
• Fully self-hosted — your notes never leave your infrastructure
• Presence & cursors — see who's online and where they're editing with colored remote cursors
• Admin controls — invite-only registration, user management, shared folder management
• Single Docker command — up and running in under a minute

Hosted Service

If you'd rather not manage a server, a hosted version of Hyperfector is coming soon. Sign up for early access at hyperfector.com — same features, zero setup.

Quick Start (Docker)

docker run -d \
  --name hyperfector \
  -p 1234:1234 \
  -v hyperfector-data:/app/data \
  -e JWT_SECRET="your-secret-key-here" \
  -e ADMIN_USERNAME="admin" \
  -e ADMIN_PASSWORD="your-admin-password" \
  hyperfector/hyperfector

See docs/self-hosting.md for detailed deployment instructions including reverse proxy setup.

Plugin Installation

1. Build the plugin: pnpm install && pnpm -r build
2. Copy packages/plugin/main.js, packages/plugin/manifest.json, and packages/plugin/styles.css to your vault's .obsidian/plugins/hyperfector/ directory
3. Enable "Hyperfector" in Obsidian Settings → Community Plugins
4. Configure your server URL and log in

Development

Prerequisites

• Node.js 22+
• pnpm 10+

Setup

git clone <repo-url>
cd hyperfector
pnpm install

Dev Server

# Set required env vars
export JWT_SECRET="dev-secret"
export ADMIN_USERNAME="admin"
export ADMIN_PASSWORD="admin"
export SQLITE_PATH="$(pwd)/data/docs.db"
mkdir -p data

# Start the server (with hot reload)
pnpm dev:server

Dev Plugin

# Build plugin and watch for changes
pnpm dev:plugin

The plugin builds to packages/plugin/main.js. Symlink or copy it to your test vault's plugin directory.

Project Structure

packages/
  shared/    — Types, constants, helpers shared between server and plugin
  server/    — Hocuspocus sync server + REST API + SQLite
  plugin/    — Obsidian plugin (CM6 extensions, sync, file operations)

Architecture

• Server: Hocuspocus WebSocket sync server with SQLite persistence
• Plugin: Obsidian plugin using CodeMirror 6 extensions for collaborative editing
• Sync: Yjs CRDTs for document content + Y.Map meta documents for file operations
• Auth: JWT tokens, bcrypt password hashing, invite-token registration

Environment Variables

Variable	Required	Default	Description
JWT_SECRET	Yes (prod)	insecure default	Secret key for JWT signing
ADMIN_USERNAME	No	—	Auto-create admin user on first run
ADMIN_PASSWORD	No	—	Password for auto-created admin
PORT	No	1234	Server listen port
SQLITE_PATH	No	./data/docs.db	Path to SQLite database
LOG_LEVEL	No	info	Minimum log level: debug, info, warn, error

FAQ

Why choose Hyperfector over Obsidian Sync? Obsidian Sync ($4-5/month) is excellent for syncing your vault across devices, but it doesn't offer real-time collaborative editing with live cursors — it syncs files, not keystrokes. It also runs on Obsidian's infrastructure (end-to-end encrypted, but not self-hosted). Hyperfector is 100% free, fully self-hosted, open source, and built specifically for real-time collaboration with live cursors and presence. That said, Obsidian Sync is well worth considering — paying for it directly supports the team behind Obsidian, the tool we all love and build on top of.

Why is Hyperfector open source and free? We believe in giving back to the community. Open source means you can inspect the code, trust what it does with your data, and contribute improvements. It also means the community helps steer the product in the right direction — the people who use Hyperfector shape what it becomes. A paid hosted service at hyperfector.com is coming soon for those who prefer not to self-host, which is how we sustain development while keeping the core product free.

Does it work offline? Yes. Hyperfector uses CRDTs (Yjs) with local IndexedDB caching. You can keep editing while offline — changes merge automatically when you reconnect.

How many users can it handle? Hyperfector is designed for individuals and small teams but there's no hard limit. The server is lightweight (Node.js + SQLite) and scales well for typical collaborative editing workloads.

Do I need technical skills to self-host? Basic familiarity with Docker is all you need. A single docker run command gets the server running. See the self-hosting guide for details.

License

AGPL-3.0