How Heaper Works
You don't need to read this page to use Heaper. It explains what happens behind the scenes, and helps you decide between Heaper Cloud, your own server or no server at all.
Your device comes first
Heaper is local-first. Everything you write is saved on your device first:
- A change is saved instantly, with or without internet.
- When a connection is available, Heaper syncs it in the background.
- If two devices changed the same note while offline, Heaper merges both changes automatically.
That's why Heaper never shows a "conflicted copy" or asks which version to keep. The technique behind it is a CRDT, see What is a CRDT?
Three ways to keep your data
| On this device only | Heaper Cloud | Your own server | |
|---|---|---|---|
| Account needed | No | Seed phrase | |
| Sync between devices | No | Yes | Yes |
| Share with others | No | Yes | Yes |
| Who stores your data | You | Heaper, in Europe | You |
| Setup | None | None | Self-Hosting |
You can start on one device and add sync later. You can also use several heaps on different servers side by side.
Servers and devices
With a server, your data has a home base:
- The server keeps the full copy of everything. Your files stay normal files in normal folders, so you can open them without Heaper. Notes, tags and other details are stored in a PostgreSQL database that you can also access on your own server.
- Your devices keep what you need. Phones and laptops store previews and details for everything, and download full files when you open them. You can choose files to always keep on a device. See Storage on Your Device.
This way a phone with little storage can still browse a heap of hundreds of gigabytes.
Bringing in existing files
On your own server, Heaper can scan folders you already have and add every file and folder to a heap, with previews. The files stay where they are. This is the fastest way to bring in large photo or document archives. See Files & Importing.
Technology used
- Yjs: the CRDT that merges edits
- SQLite: the local database on each device
- PostgreSQL: the database on the server
- Rust: fast sync and file transfer on every platform
- Go: the server
- Vue and TipTap: the app and its editor
For developers
- Self-Hosting: run your own server with Docker
- API & Agents: server API, local API, CLI and MCP for AI agents