UltraBridge

UltraBridge is a self-hosted bridge for e-ink notes, tasks, search, and AI tools. It can receive notes from Supernote, Boox, ForestNote, and reMarkable devices; render and OCR handwritten pages; expose tasks through CalDAV and MCP; and search or chat across indexed notebook content.

This software was developed using Claude Code, which was trained on open source software, and will therefore always be open-source software.

What It Does

• Device sources: Supernote via UltraBridge's built-in SPC server, Boox via WebDAV, ForestNote via /sync/v1, and reMarkable via a hosted protocol-compatible source.
• Tasks: Web UI task management, CalDAV sync, MCP task tools, ForestNote task provenance, and signed task attachments.
• Notes: Per-source Files tabs, rendered page previews, OCR/reprocess controls, trash/recovery flows, and digest/detail views.
• Search and AI: FTS5 keyword search, optional Ollama embeddings, RAG retrieval, local chat through an OpenAI-compatible endpoint, and MCP note tools.
• Operations: SQLite-backed storage, Docker-first deployment, grouped Settings pages, live logs, bearer tokens, and source-specific sync/device management.

Quick Start

Installer

./install.sh

The installer builds UltraBridge, writes a Docker Compose configuration, starts the service, and seeds your first username/password. Open the displayed URL, usually http://localhost:8443, then finish setup in the web UI.

Docker Compose

docker compose up -d --build

The checked-in compose file publishes the main app on 8443 and the Supernote SPC listener on 8089. MCP is served by the main app at /mcp.

Local Development

go build -o /tmp/ultrabridge ./cmd/ultrabridge/

UB_DB_PATH=/tmp/ub-notes.db \
UB_TASK_DB_PATH=/tmp/ub-tasks.db \
UB_LISTEN_ADDR=:8443 \
/tmp/ultrabridge

On a fresh database, UltraBridge opens the setup page without auth. After the first user is created, web, API, CalDAV, and MCP access require credentials or a bearer token.

User Documentation

• Installation and upgrade
• Sources and sync models
• Supernote setup
• Boox setup
• ForestNote sync
• reMarkable setup
• Tasks, CalDAV, and attachments
• Search, RAG, OCR, and chat
• MCP and JSON API
• Operations and troubleshooting

Additional references:

• Architecture
• API reference
• Troubleshooting
• Standalone Supernote OCR injection

Main Endpoints

Surface	Default URL	Notes
Web UI	http://<host>:8443/	Tasks, Files, Search, Chat, Logs, and grouped Settings pages.
Health check	http://<host>:8443/health	Returns service status and config-dirty state.
CalDAV	http://<host>:8443/.well-known/caldav	Task collection for DAVx5, Evolution, 2Do, and similar clients.
Boox WebDAV	http://<host>:8443/webdav/	Boox upload target.
MCP SSE	https://<public-host>/mcp	Built into the main service for Claude.ai and other SSE clients.
JSON API	http://<host>:8443/api/v1/*	Tasks, files, search, chat, status, config, sync, and reMarkable admin routes.
Supernote SPC	https://<supernote-host>/ -> :8089	Device-facing listener. Use a dedicated hostname behind your reverse proxy.
ForestNote sync	http://<host>:8443/sync/v1	Device sync endpoint, enabled by a ForestNote source.

Configuration

Most configuration lives in the SQLite settings database and is edited from the web UI:

• Settings -> Devices: source rows, Supernote SPC server settings, ForestNote device registry, Boox maintenance, and reMarkable source/device data.
• Settings -> AI & Processing: OCR provider/model, source OCR prompts, embeddings, and chat.
• Settings -> Integrations: CalDAV and MCP tokens.
• Settings -> System: auth, logging, verbose API logging, and restart-sensitive runtime settings.

Bootstrap environment variables are still supported for automation and overrides. The most common are:

Variable	Default	Purpose
UB_DB_PATH	/data/ultrabridge.db	Notes, settings, source state, and search data.
UB_TASK_DB_PATH	/data/ultrabridge-tasks.db	CalDAV/task database.
UB_LISTEN_ADDR	:8443	Main app listener.
UB_SPC_MODE	client	Set to server, or use Settings, to enable the Supernote SPC listener.
UB_SPC_LISTEN_ADDR	:8089	Supernote SPC listener address.
UB_SYNC_ENABLED	false	Legacy bootstrap gate for ForestNote sync; current installs should use a ForestNote source.

Secrets such as API keys, MCP bearer tokens, task attachment signing keys, and SPC credentials should be set through Settings or an untracked .env.

Build And Test

go build ./cmd/ultrabridge/
go test ./...

For Docker:

./rebuild.sh

or:

docker compose up -d --build

Known Limitations

• CalDAV maps the task fields UltraBridge understands: title, description, URL, priority, categories, status, due date, and signed attachments. Recurrence and reminders are not fully modeled.
• Boox is receive-only. Deletes and renames on the device do not propagate back to UltraBridge.
• reMarkable device handwriting recognition proxying and UltraBridge server-side OCR/search are separate paths. The native device HWR proxy returns MyScript JIIX to the tablet; search/RAG text comes from UltraBridge's render-to-OCR pipeline.
• Some legacy design and test documents describe earlier MariaDB-backed SPC integration. User-facing setup should follow the docs linked from this README.

Release Notes

The current release train is documented in CHANGELOG.md. This documentation set is prepared for v1.2.0.

License

Apache 2.0 (C) 2026 jdkruzr. See LICENSE and NOTICE.

Credits

This project owes a bunch to two self-hosted Supernote Private Cloud reimplementation projects: Supernote Knowledge Hub and OpenNoteCloud, both of which helped shape how UltraBridge evolved.