Hyperclast

Collaborative workspace with real-time editing, bidirectional links, and AI-powered search.

Hyperclast workspace

• Real-time collaboration: Conflict-free sync via Yjs CRDT
• Fast editor: Built on CodeMirror 6
• Bidirectional links: Automatic backlinks between pages
• AI search: Query your workspace with RAG
• Self-hostable: ELv2 licensed

Quick Start (Docker)

Create backend/.env-docker:

SECRET_KEY=$(openssl rand -base64 32)
ENCRYPTION_KEY=$(python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")

cat << EOF > backend/.env-docker
WS_SECRET_KEY=${SECRET_KEY}
WS_ENCRYPTION_KEY=${ENCRYPTION_KEY}
WS_DB_USER=hyperclast
WS_DB_PASSWORD=hyperclast_pw
WS_DB_NAME=hyperclast
WS_ROOT_URL=http://localhost:9800
EOF

Run:

./run-stack.sh 9800           # Start stack with MinIO (webapp at localhost:9800)
./restart-stack.sh backend    # Restart Django after code changes
./restart-stack.sh ls         # List running stacks

See backend/.env-template for all configuration options.

Upgrading? If you previously ran the Docker stack, the frontend-node-modules volume may be owned by root. Remove it once so it gets recreated with correct permissions:

>

``sh # Find the volume name docker volume ls | grep frontend-node-modules # Remove it (stack must be stopped) docker volume rm <volume-name> ``

Development

See Local Development Guide for running without Docker.

File Storage (Cloudflare R2)

File uploads are disabled by default. To enable, add to your .env:

WS_FILEHUB_FEATURE_ENABLED=true
WS_FILEHUB_PRIMARY_UPLOAD_TARGET=r2
WS_FILEHUB_R2_ACCOUNT_ID=<your-account-id>
WS_FILEHUB_R2_ACCESS_KEY_ID=<access-key-id>
WS_FILEHUB_R2_SECRET_ACCESS_KEY=<secret-access-key>
WS_FILEHUB_R2_BUCKET=hyperclast-ws-uploads

See Cloudflare R2 Setup Guide for detailed instructions.

MinIO is included by default in the Docker stack, so file uploads work out of the box (S3 API on port 9000, console on port 9001). To disable MinIO, use ./run-stack.sh --no-minio 9800. See MinIO Local Setup for details.

Data Import (Notion)

Import pages from Notion using their Markdown & CSV export:

1. Export from Notion: Settings → Export → Markdown & CSV
2. In Hyperclast, click the project menu (⋮) → "Import from Notion"
3. Upload the zip file

Note: Importing requires editor permissions on the project. Viewers cannot import.

Features:

• Automatic deduplication (re-importing skips existing pages)
• Internal link remapping to Hyperclast format
• Nested page flattening with original path preserved
• Zip bomb protection and archive security validation

See Import System Documentation for architecture details.

License

The source code of this project is licensed under the Elastic License v2 (ELv2). See LICENSE for details.

What this means

• ✅ Free for individual use, learning, modification, and self-hosting
• ✅ Free for internal use within small teams
• ❌ You may NOT offer this software as a managed or hosted service
• ❌ You may NOT resell or repackage it as a competing service

If you are a business using this software beyond personal or evaluation use, you must obtain a commercial license. See COMMERCIAL_LICENSE for details.