---

What is mosaic?

mosaic is a dashboard you actually own. Instead of a wall of unrelated apps and tabs, you arrange widgets — tasks, a calendar, notes, trackers, a reader, a spreadsheet, and more — onto boards that look and behave exactly the way you want. Everything lives in your browser's IndexedDB; there is no mosaic server and no account, so there's nothing to sign up for and nothing that can lock you out of your own data.

• 17 widget types — task/habit tracking, notes with custom fonts/color/shadow/outline, calendar, spreadsheet with formulas, drawboard, a PDF/EPUB reader with its own bookshelf and per-book highlights, charts, weather, map, clock, timer, water and sleep tracking, agenda, quicklinks, images, and a sandboxed HTML widget for your own pasted pages.
• 20 built-in themes (plus your own custom ones) — from Deep Space to Soft Light, each with its own accent colors and background pattern; every widget can additionally be styled individually.
• Optional AI assistant (bring your own key) — connect your own Anthropic/OpenAI/Gemini (or any OpenAI-compatible) API key and let it build and manage boards with you, or open a mini chat scoped to a single widget. Your key and your prompts go straight from your browser to your chosen provider — never through a mosaic server, because none exists.
• Works everywhere — responsive desktop and mobile layouts, plus native desktop apps for Windows, macOS, and Linux with automatic updates.
• Local-first by design — boards, widgets, and settings never leave your device. See Privacy & data for the handful of widgets that talk to external services (maps, weather, the optional AI) and exactly what they send.
• Bilingual — full English/German UI, switchable anytime.

Download

Each link opens the release page; download the asset for your platform from the list of files attached to it. The desktop app checks for updates automatically and installs them in the background — you'll always be on the latest version.

[!WARNING] Windows and macOS will warn about an "unknown publisher" on first launch. The builds aren't code-signed — a Windows certificate costs $70–400/year and a macOS one requires a paid Apple Developer account, both from a registered business/identity (see GITHUB_SETUP.md for exactly what that involves) — so this isn't something a single-developer project can just turn off. The warning means "this publisher isn't verified," not "this file is malware." Nothing in mosaic phones home or reads files outside your own boards (see Privacy & data); the source is fully in this repo and the build pipeline is the public release.yml workflow, so the .exe/.dmg you download is exactly what that workflow produced from this code, nothing more. To proceed anyway:

• Windows: click "More info", then "Run anyway" in the SmartScreen dialog.
• macOS: current macOS versions usually skip the old "unidentified developer" dialog entirely and instead say "'mosaic' is damaged and can't be opened. You should move it to the Trash." — despite the wording, the download isn't actually corrupted; that's just Gatekeeper's generic message for any app without a paid Developer ID signature. Right-click → "Open" alone no longer clears it on current macOS. Move mosaic.app to /Applications, then in Terminal run:

  xattr -cr /Applications/mosaic.app
  

  and launch it normally.

If you'd rather not click through a warning at all, the Linux install below and running from source don't trigger this, since neither goes through Gatekeeper/SmartScreen.

Linux install

Only .deb and .AppImage are published — no native .rpm or Arch package — so Debian-based distros get a real package install, everyone else runs the portable .AppImage. Each command below looks up the current release's exact asset URL itself (via the GitHub API) and pipes it into a plain sh -c, so there's no version number to edit and nothing that depends on which shell you're pasting into — it works the same in bash, zsh, and fish.

Debian-based (Debian, Ubuntu, Linux Mint, Pop!_OS, elementary OS, ...):

curl -s https://api.github.com/repos/Aetherion7/mosaic/releases/latest | grep browser_download_url | grep '\.deb"' | cut -d '"' -f4 \
  | xargs -I{} sh -c 'wget "$1" && sudo apt install "./$(basename "$1")"' _ {}

apt install ./file.deb (not dpkg -i) resolves and pulls in missing dependencies automatically.

Arch-based (Arch, Manjaro, EndeavourOS, CachyOS, ...) — no AUR package (yet), run the .AppImage:

sudo pacman -S --needed fuse2
curl -s https://api.github.com/repos/Aetherion7/mosaic/releases/latest | grep browser_download_url | grep '\.AppImage"' | cut -d '"' -f4 \
  | xargs -I{} sh -c 'wget "$1" && chmod +x "$(basename "$1")" && "./$(basename "$1")"' _ {}

Fedora-based (Fedora, Nobara, RHEL, ...) — no .rpm (yet), same .AppImage:

sudo dnf install -y fuse
curl -s https://api.github.com/repos/Aetherion7/mosaic/releases/latest | grep browser_download_url | grep '\.AppImage"' | cut -d '"' -f4 \
  | xargs -I{} sh -c 'wget "$1" && chmod +x "$(basename "$1")" && "./$(basename "$1")"' _ {}

AppImages need the FUSE2 runtime (libfuse.so.2), which many current distros — including Arch and Fedora — no longer install by default (only FUSE3). Without it you'll get dlopen(): error loading libfuse.so.2; the pacman/dnf line above installs the missing compat library. Debian- based systems don't need this at all since they use the .deb package, not the AppImage.

Any other distro (openSUSE, NixOS, ...) — same idea: install a fuse2/libfuse2 compat package if it's missing, then run the same .AppImage command as above.

The commands above run the AppImage directly from your Downloads folder — that first run is also all it takes to install it properly: mosaic adds itself to your applications menu with a proper icon (writes a .desktop entry + icon under ~/.local/share, picked up automatically by GNOME, KDE, XFCE, ...), so after that you can launch it like any other installed app instead of digging the file back out of a terminal every time. The .deb install gets this the normal way, via apt.

Features

Beyond the basics

A few things that aren't obvious from a feature list:

• Reader ↔ Note highlight linking. Highlight text in any book in the reader's library, then link that highlight into any Note widget on the board as a colored inline reference. Clicking it in the note jumps the reader straight back to that book, and to the exact page (PDF) or location (EPUB) — works both ways, a highlight can be linked into more than one note, and reading progress and highlights all save automatically per book.
• Move or copy a widget to a different board. Every widget's toolbar has a "Move/copy to board" action: pick a target board from a searchable list (each tinted with that board's own accent color) and it's transferred instantly, size and style intact — no dragging across two open windows required.
• Map markers and hand-drawn routes. Drop colored, labeled pins anywhere on the map, or draw a route by clicking a sequence of points — mosaic shows the running distance live as you place them. Routes are plain waypoints you control directly, not an auto-routed driving path.
• Per-widget AI chat with hard-enforced scope. Beyond the board-wide assistant, any widget can get its own pinned mini-chat. That chat is restricted in code, not just by prompt — it physically cannot call a tool against a different widget's ID or touch the board theme, regardless of what it's asked to do.
• Focus mode is a true 1:1 mirror, not a preview. Double-clicking a widget renders the exact same component at its real size, scaled up with one CSS transform — so a task list, calendar, or map stays fully interactive (check off a task, drag an event) at full-screen size, pixel-faithful to the board version.
• A minimap that zooms with you. Unlike a typical fit-to-bounds overview, mosaic's live minimap scales in lockstep with your actual board zoom — zoom out on the board and the minimap's tiles shrink too, like radar rather than a static thumbnail.
• Real spreadsheet formulas, safely evaluated. =SUM(A1:A5), IF, COUNTIF, TEXTJOIN, and 40+ other functions, backed by a hand-written parser (no eval, no arbitrary code execution) — safe to open boards you didn't build yourself.
• Themes as editable JSON, with smart migration. Write or paste your own theme as JSON with live validation, or tweak a built-in one. Switching a board's theme only replaces the widget styles that still matched the old theme's defaults — anything you customized by hand is left alone.
• Custom fonts, not just a font list. Pick from 8 built-in typefaces app-wide or per-board, or upload your own .ttf/.otf/.woff2 — it becomes selectable everywhere a font picker shows up, including per-note overrides.
• Reminders that actually check your progress. Water reminders stop once you've hit today's goal; the sleep reminder only fires if you haven't logged a bedtime yet; calendar reminders account for recurrence. All run in the background via a single scheduler, independent of which board is open.
• Nothing is really deleted right away. Deleted boards go to Trash (restorable, auto-expiring) instead of vanishing, and you can save any board's layout as a reusable template.
• Calendars round-trip with the outside world. Import an .ics file into a Calendar widget, or export your events back out as one — recurrence rules, colors, and all.
• An HTML widget that needs no hosting. Paste or upload a self-contained .html file and it renders live in a sandboxed iframe — no external URL, no server, no install step. Flip to a built-in code view anytime to see or edit the exact source, or hit reload to restart it. Scripts run, but with no access to cookies/storage from any real origin and no way to reach the rest of the page.

Getting started

Run mosaic locally in about a minute:

git clone https://github.com/Aetherion7/mosaic.git
cd mosaic
npm install
npm run dev

Open http://localhost:3001. That's it — no database, no .env file, no account.

Prefer the packaged desktop app? Grab it from Download, or build it yourself:

npm run electron:dev     # dev mode — hot reload, same as `npm run dev` in an Electron window
npm run electron:pack    # unpacked build for your current OS (for testing)
npm run electron:dist    # installer for your current OS

Cross-platform installers (Windows/macOS/Linux, code-signed if you've set up certificates) are built automatically by .github/workflows/release.yml whenever a v* tag is pushed — see GITHUB_SETUP.md for the full release process.

Requirements

• Node.js 20+
• npm (the repo is developed against npm ci/package-lock.json)

Scripts

Privacy & data

Everything you create — boards, widgets, settings — lives exclusively in your browser's IndexedDB and localStorage. There is no mosaic backend to send it to.

The exceptions, all optional and all documented in-app under Settings → Privacy:

• The map and weather widgets fetch data from OpenStreetMap/Nominatim and Open-Meteo when used.
• The quicklinks widget fetches favicons from DuckDuckGo.
• The AI assistant, if you enable and configure it, sends your messages directly to the provider you chose (your API key never touches anything but that provider).
• The HTML widget renders whatever page you paste into it — if that page itself makes network requests, that's the page's own doing, not mosaic's. It runs sandboxed (no access to your cookies, storage, or any other origin).

No tracking, no analytics, no ads.

Tech stack

Next.js 16 (App Router) · React 19 · TypeScript · Zustand · IndexedDB · Framer Motion · Tiptap · dnd-kit · react-pdf · epub.js · Leaflet · Electron (desktop) · Vitest

Contributing

Bug reports, feature ideas, and pull requests are welcome — see CONTRIBUTING.md for how the project is organized and what to know before opening a PR. mosaic is source-available under a noncommercial license (see below); by contributing you agree your changes are licensed under the same terms.

New to GitHub or not sure how forking/PRs work? GITHUB_SETUP.md also covers the basics.

Support the project

mosaic is free and always will be for personal use. If it's useful to you, a donation helps cover the time that goes into it:

No pressure at all — using it, starring the repo, or reporting a bug is just as appreciated.

License

mosaic is source-available under the PolyForm Noncommercial License 1.0.0: free to use, modify, and self-host for personal, educational, research, or nonprofit purposes — not for resale or commercial hosting. See LICENSE.md for the full text and a plain-English summary, or open an issue if you're interested in commercial use.