heaper
Docs

FAQ

Answers to common questions about Heaper.

General

What platforms does Heaper support?

  • Desktop — macOS, Windows, Linux
  • Mobile — iOS and Android
  • Web — Progressive Web App (in progress, not fully usable yet will work without being local first or downloading data first)

Is Heaper free?

Heaper offers both free and paid plans. See heaper.de/pricing for current pricing. Self-hosting is available for all plans.

Can I use Heaper offline?

Yes. Heaper is local-first — all your data is stored on your device and the app works fully offline. Changes sync when you're back online.

How does sync work?

Heaper uses CRDTs (Conflict-free Replicated Data Types) via Yjs. Changes are merged automatically without conflicts. See What is a CRDT? for details.

What are blocks?

Everything in Heaper is a block — notes, files, images, tags. Think of them as containers of relevant stuff that you can connect together. Each block can have a title, content, tags, and files.

How do tags and folders differ?

Tags act like folders but a block can belong to multiple tags at once. Tags are hierarchical (nested), and any tag can also have its own content (like a "Map of Content"). Files don't physically move when you change tags.

Are there merge conflicts?

No. Heaper uses CRDTs which resolve all changes automatically. Text, tags, and mentions never conflict. Files are versioned — concurrent edits create new versions rather than conflicting.

Can I use Heaper alongside other tools?

For the server, yes. As long as you point Heaper's scan directories to the same folders, it doesn't interfere with other services (Obsidian, Nextcloud, Plex, etc.). There's also a .heaperignore file to exclude metadata files from other tools.

Licensing & Pricing

Is Heaper a subscription?

No. There is a one-time perpetual license option. Subscriptions are also available as an alternative. Both are listed on the pricing page — scroll down for the perpetual license.

What does the perpetual license include?

Unlimited storage, one year of feature updates, security updates forever, multi-user support on one server. The license never expires — you keep all features you purchased.

What happens after the one year of feature updates?

Your server continues to work with all the features you had. You still receive security updates. You only need a new license if you want access to future major features (like advanced collaboration tools). You're never forced to upgrade.

Community Q&A

How would I continue to receive updates after the year is up? The intention with the one year of free updates was only about feature updates, not security updates. Those should be coming in still. You actually keep upgrading your server even if your license expired — you will still get all the features that you bought when your license was purchased.

Would I have to pay the full price for a new license each year or is there a lower cost renewal price? Cheaper renewal prices are an option, but right now we're still at the "seeing how payment actually works" phase.

Do I need to pay for security updates?

No. Security updates are included forever, for both the free and paid versions. It's important that people can run the newest version and stay compatible with the apps. You get the most recent version even if you have an old license — features you already bought are not locked down.

What is the free version?

The same as Pro but with a 50 GB storage cap. No time limit, no feature restrictions, no online requirement. It's a permanent trial to see if Heaper works for your setup.

What's the launch phase?

Until August 2026, everything is free with unlimited storage so you can try Heaper, give feedback, and test on your hardware. After August 2026, the free version keeps working with the 50 GB cap.

Community Q&A

Will unlimited storage for the Free License be capped after launch ends or will it remain unlimited for early adopters? Right now it would return to be the normal free version after the launch phase ends. There will likely be a campaign with discounts for early adopters.

Can I use one license on multiple servers?

Licenses are intended for a single server. Multiple users can use that server with one license. Right now there is nothing blocking you from installing it on multiple, but as soon as federation and inter-server communication are available, they would identify as the same one.

Community Q&A

Do these licenses allow for commercial use, for example reseller hosting to clients? The licenses are not intended for redistributing to other clients and selling these as a service. This is what the Heaper cloud version should be doing, though the pricing will hopefully get cheaper with better cloud deals.

Are subscriptions worth it?

Subscriptions include cloud storage plus full self-hosting access while active. They support ongoing development with recurring revenue. You can choose whichever model works for you.

Files & Storage

Does Heaper replace my file system?

No. It layers on top. Your files stay as normal files on disk. You can open them with any app ("Show in Finder"), use them in video editors, etc. Heaper adds organization through tags without moving the actual files.

How are files stored?

Files are stored using their SHA-256 content hash as the folder name. This means renaming or retagging never breaks file links. Your video editor references will keep working.

Can I browse my files without Heaper?

Yes. On the server, files are stored in normal folders. The database is standard PostgreSQL you can query directly. On clients, files are stored with their thumbnails in organized folders.

What file systems does Heaper support?

Heaper doesn't care about the underlying file system. It works on ZFS, Btrfs, APFS, ext4, NTFS — whatever your server or NAS uses.

How does Heaper handle large libraries (100k+ files)?

The server generates thumbnails at multiple sizes. Clients only download previews, not full files. You can browse terabytes of photos on your phone using just the thumbnails, even offline.

Can I pin files for offline access?

Yes. Pinned files are downloaded to your device and kept offline. Unpinned files only store thumbnails locally and can be cleared to save space.

Can I run Heaper on a Raspberry Pi?

Yes, Heaper now supports ARM64 devices.

Do I need a static IP or domain name?

No. You can use Tailscale, WireGuard, or any VPN to access your home server. A future Heaper Cloud feature may help with connection discovery without exposing your server directly.

Can I use S3/object storage?

The self-hosted server currently uses normal disk storage, but an update to support S3 and object storage is planned.

Comparison & Migration

How does Heaper compare to Obsidian?

Heaper handles both files and notes with the same tagging system. Unlike Obsidian, Heaper supports rich text (not just Markdown), file management with thumbnails/previews, multi-device sync to your own server, and doesn't rely on iCloud/Dropbox for sync.

How does Heaper compare to Tag Studio?

Tag Studio focuses on local-only file management. Heaper adds note-taking, server-based sync across devices, and mobile access to your library via thumbnails without needing all files on every device.

How does Heaper compare to Notion/Anytype?

Unlike Notion, all your data stays on your server — nothing goes to third-party clouds. Unlike Anytype, files aren't end-to-end encrypted on disk, so you can access them directly with any file manager.

Can I export my data?

Yes. There's a built-in export function (JSON format for blocks). Files are always accessible as normal files on disk. The database is standard PostgreSQL you can query and export from directly.

Features & Roadmap

Will there be plugins?

Yes, planned. Similar to Obsidian's plugin system. However, the goal is to have all essential features built in so you don't depend on third-party plugins for basics.

Is there a graph view?

Built but not yet released. The current implementation works up to ~15,000 nodes but needs optimization for larger libraries before public release.

Will there be attributes/properties on blocks?

Yes, this is a major planned feature. Attributes will allow typed data on blocks (dates, numbers, etc.), enabling database-like views similar to Notion but with cross-collection reuse.

Are keyboard shortcuts available?

Yes. Cmd/Ctrl+K for search, Cmd/Ctrl+B to toggle the bottom sheet, Alt+Left Arrow to go back, and more. A shortcut reference panel is being reimplemented.

Will there be collaboration/sharing features?

Planned for the future. Sharing blocks between heaps, inbox receiving, and team permissions are on the roadmap.

Is a web clipper planned?

Yes. The goal is a browser extension that captures web pages, media, and article text into your heap.

Will there be AI features?

Planned support for Ollama with local embedding models for semantic search, image description, and text processing — all running on your own hardware.

Privacy & Security

Does Heaper track me?

No. There is no tracking in the apps or server, no analytics, no ads. No external services access your data.

How does authentication work?

Email login plus private key authentication (public/private key challenge). No internet required for self-hosted login — everything works offline.

Can I hide content on my device?

Yes. Global filters can hide tagged content from all views, searches, sidebar, and links. Useful for privacy when showing your screen or sharing your device.

What happens if Heaper shuts down?

Your files are normal files on disk. Your metadata is in a standard PostgreSQL database. The apps continue to work with whatever version you have installed. There's nothing that requires Heaper's cloud to keep functioning.

Is Heaper open source?

No. Audits are planned for trust, and a minimal core to use Heaper's data format in an open source way is being explored.

Self-Hosting

What are the system requirements?

  • Docker (or Podman)
  • At least 2 GB RAM recommended
  • The Docker image is built for x64 (amd64) — ARM devices use QEMU emulation

PostgreSQL won't start with Podman

When using Podman instead of Docker, PostgreSQL cannot use bind-mounted host directories due to permission restrictions. Use a named volume instead:

volumes:
  postgres_data:

services:
  heaper:
    volumes:
      - postgres_data:/var/lib/postgresql/data    # Named volume instead of bind mount
      - ./heaper-data/data:/usr/src/app/data
      # ... other volumes

This is a known Podman limitation with PostgreSQL's data directory permissions.

How do I access my instance remotely?

Several options:

  1. Tailscale — Recommended. See Remote Access with Tailscale
  2. Reverse proxy — Use Caddy or nginx with a domain and TLS certificate
  3. Port forwarding — Not recommended for security reasons

How do I connect the app to my self-hosted server?

In the Heaper app: Settings → Heaps → Pull Heap — enter your server's address (IP or domain).

How do I update my self-hosted instance?

docker-compose pull
docker-compose up -d

How do I back up my data?

Heaper supports automated daily backups when the /mnt/backups volume is mounted. See Self-Hosting — Backup & Restore for details.

How do I report a bug?

The fastest way currently is using the Discord server to report bugs and feature requests. Or chat with me in general. https://discord.gg/dNB4QsPBnu

Visit the Heaper roadmap for known issues, or contact support via the email listed on heaper.de.