A friendTheir computer · their keysTheir own saved copy
The chosen article, its cached images and your share note travel to your friend. They keep a copy to read offline. Your personal highlights, notes, subscriptions and reading state stay private.
Shares wait locally while a friend is offline. Both apps exchange when they can connect, with relay connectivity where needed. There is no Carrel account or central service we operate.
Your own paired desktops sync private reading state separately. Following a friend never grants access to your private archive.
Library / An article to return toAa
The commonplace · A reading example
Some things are worth keeping.
A sentence underlined. A thought in the margin. The beginnings of a conversation.
Reading leaves traces. A phrase comes back to you on a walk. An argument changes the way you see something. You find a passage and know exactly who you want to send it to.
A commonplace book gives these encounters somewhere to live. What you keep becomes a record of what you noticed, and what you noticed becomes a way of thinking.
You don’t need to keep everything. Just enough to find your way back.
The reading roomAn illustrative view, with example text.
Read
The web, at your own pace.
Bring your RSS, Atom and JSON feeds. Save an article you found along the way. Read from your local archive, even offline, with typography you can make your own.
Underline a passage. Leave a note. Return to what you noticed, with the archived article for context. Your highlights and notes can leave with you as Markdown.
Choose a person and send an archived article directly to their computer, perhaps with a few words about why. A small act of curation between people who trust each other’s taste.
There was something good in Google Reader’s small circles: people who read carefully, shared what was worth sharing, and trusted each other’s taste. A recommendation arrived with a person behind it.
Carrel grows from that memory, and from an older habit: keeping a commonplace book. What you read, what you noticed, and who you wanted to tell belong to the same reading life.
The open web still gives us the raw material. Blogs still publish. Feeds still work. We want a tool that makes room for that life again, on our own computers, among people we choose.
Your archive lives locally, under your own keys. Reading doesn’t require a Carrel account. Your own paired desktops can exchange private state.
Small circles, chosen by you.
Sharing goes to a person you explicitly choose. The article and your vouch travel together; your personal highlights, notes and reading state stay private.
A place you can put down.
No engagement metrics, algorithmic recommendations or notifications outside the app. You decide when something is read, and when you’re done.
Open, all the way through.
Open source under AGPL-3.0-or-later. OPML for subscriptions, Markdown for your annotations. No telemetry or central Carrel service we operate.
A work in progress, made to be used
Pull up a chair.
Carrel is pre-alpha. The desktop reader, local archive, highlights, notes, private device sync and first one-person sharing flow are implemented. Physical two-desktop trials and broader platform checks are still in progress.
Keep a private backup of anything you can’t replace. Books and papers metadata, mobile, send-to-ereader and public sharing belong to the longer vision.
Apple Silicon & Intel Mac · Linux x86-64 Early Mac builds are ad-hoc signed, without notarization.
The reader’s guide
Find your way in.
A few things to help you settle in, and a reference to come back to.
Carrel is a desktop reader for the open web. You can read locally, save passages
and take notes without setting up sync or adding a person. These pages describe
the current pre-alpha; the vision
looks further ahead.
Use the search control above (or press /) to search this guide. The contents
control shows or hides the chapter list. Each page can be printed with the print
control; the appearance control at the top switches between Light and Dark.
Choose the package for your computer from
GitHub Releases. Current targets
are Apple Silicon Mac, Intel Mac and Linux x86-64. Draft releases are maintainer
review builds; published prereleases remain early software.
Open the .dmg, drag Carrel into Applications, eject the disk image and
open Carrel from Applications. Apple Silicon uses the macos-arm64 package;
Intel uses macos-x86_64. You do not need Rust, Node or a development server.
Trial packages are ad-hoc signed, without Developer ID signing or notarization.
If macOS blocks a trusted copy you downloaded from this repository, try opening
it first, then use System Settings → Privacy & Security → Open Anyway.
See Apple’s instructions.
The initial x86-64 packages are built on Ubuntu 24.04. A .deb can be installed
with the system package manager, which also resolves its runtime dependencies:
Replace VERSION with the version in the downloaded filename. Other
distributions may need additional WebKitGTK/FUSE support; report the distribution
and exact error rather than assuming the Ubuntu build is universal.
Use Add source beside Sources, in Settings → Sources, or in the context bar’s
app menu. Paste a website address or RSS/Atom/JSON feed URL. Carrel discovers
feeds from websites; if several valid feeds exist, choose the intended one.
For a single page, use Save article in the context bar/app menu (Cmd+N on
Mac). It archives the article and its cached images without subscribing.
Today shows publications from the preceding 24 hours. Older posts belong in
Library, even if you just subscribed. Source and folder lists put the newest
publications first. Undated posts explicitly use their saved date.
Settings → Sources offers Import OPML and Export OPML using native file
dialogs. Import skips existing subscriptions and preserves their title/folder
settings. Optional source folders also round-trip through OPML.
The reading guide covers navigation, appearance and annotations.
You can read locally without setting up peer sync or adding a person.
Today collects recent publications. Reading holds work in progress.
Library contains your archive, including Unread, Starred and Shared with you
filters. Highlights brings your saved passages and notes together.
The sidebar holds these destinations and your sources. Assign an optional folder
in Settings → Sources; selecting its name opens a combined chronological list,
and its disclosure button collapses the source rows. Cmd+B shows/hides the
sidebar while preserving the visible passage or list row.
Opening an article remembers the list, search, loaded pages, selection and
scroll position you came from. Return uses that context. Load older extends
the current list; there is no automatic infinite scroll.
Reading completion is your action. Opening, scrolling, reaching the end and
ordinary previous/next navigation do not mark an item read. Use the read control
or Mark read & next at the article end when you want to complete it.
Aa in the reader’s context bar offers font, size, line width, spacing and
Paper/Sepia/Dark/Black themes. Settings → Reading contains the same controls plus
Editorial/Dense lists. Dense uses smaller dates/titles and omits excerpts.
Changes preserve your visible passage or row; the article/list stays mounted
behind Settings. Preferences belong to this installation.
Cmd+, opens Settings. Cmd+K opens the command palette; ? shows the effective
keyboard reference, including local overrides. Controls have action labels and
keyboard hints. On platforms using Control, follow the app’s displayed hints.
Each list can search titles and cached article text offline. Every word must
match, and words match the beginning of indexed words. Punctuation is literal;
there is no search query language to learn. Filters and source/folder selection
still apply. / focuses search and \ clears it. New text indexes may be
prepared after a migration or new cache arrives; titles remain searchable.
Select text to highlight or attach a note. Highlights opens the source passage,
shows complete notes and supports editing, deliberate removal and Markdown
export through a native save dialog.
If two of your devices edit the same note offline, Carrel retains both drafts.
Review the conflict explicitly and choose or combine them. It does not silently
discard an independently edited note. An archived passage remains available
when the publisher’s page changes or disappears, provided its cache is present.
Open original uses your system browser. Archived reading uses local cached
resources; an image that could not be cached is shown as unavailable rather
than fetched remotely by the reader.
Carrel has two different connections: Devices pairs your own installations;
People connects distinct readers. A friend should create their own identity.
Each person keeps their own archive and identity. You exchange contact codes,
compare public keys and explicitly follow each other. Carrel then exchanges
chosen articles peer to peer, with relay connectivity where needed. There is no
Carrel account or central service we operate.
A share carries the chosen article, its cached images and your share note. Your
friend receives a copy they can read offline and annotate independently. Your
personal highlights, notes, subscriptions and reading state stay private. Pairing
your own desktops is a separate connection that can sync that private state;
following a friend does not grant the same access.
Shares wait locally while a desktop is offline. Exchange retries while both
apps are open; a locally saved share is not a delivery receipt.
Open Settings → Devices → Set up sync, and choose your own recovery
passphrase. Your master key stays encrypted on its originating desktop. Ordinary
reading uses that desktop’s operational key. There is no account service or
password-reset service.
If you already have your identity on another computer, use the one-time
invitation flow in Devices to pair that installation. An invitation is for your
own desktop and is cancelled when dismissed. Do not use it as a friend contact.
Open Settings → People. Copy public key and Copy contact code let you
exchange details directly. If clipboard access is unavailable, select the
complete text and use ordinary Copy.
Paste the other person’s contact code, give them a local name, compare the full
public key with the key they sent, and Follow. Each person follows the other.
A bare key can be saved before the connection code arrives.
In the reader, choose Share article. Select a person explicitly and add an
optional note. Saving records the share locally; background exchange retries
while both apps are open. A saved contact code or locally saved share does not
by itself prove delivery. Receipt in Library → Shared with you does.
The chosen article, its cached images and the vouch note are shared. Your
personal highlights, notes, reading state and subscriptions remain private.
The recipient gets an archived article they can read offline and annotate
independently.
People shows quiet connection errors and Try connection again. If an address
changes, obtain a fresh contact code and review its public key before updating.
The first flow uses one certified desktop per followed person; automatic
friend-device rotation is future work.
People → Sent articles retains history, with Load older for earlier shares.
Withdraw share retracts your vouch after exchange; it cannot erase a copy
already received. Removing a person stops new exchange and preserves earlier
archives. Assume a recipient can keep anything you deliberately send them.
For a practical trial, follow the
two-desktop checklist,
including offline reading, restart, withdrawal and private-note separation.
Carrel keeps the database, content blobs and identity files on your computer.
The database is authoritative; peer transport maintains a verified mirror.
Platform
Default archive directory
macOS
~/Library/Application Support/Carrel
Linux
~/.local/share/carrel, or under XDG_DATA_HOME
Windows development
%APPDATA%/Carrel
CARREL_DATA_DIR selects a different archive. A development build and installed
app use the same default directory, so close one before opening the other.
The keymap lives in ~/.config/carrel/keymap.toml on macOS/Linux, respecting
XDG_CONFIG_HOME; CARREL_CONFIG_DIR overrides its directory. Theme/reading
preferences are kept in the installation’s webview storage.
Close Carrel normally and let pending saves finish. Copy the whole archive
directory, including store, blobs, keys and any sync storage, into your
private backup. Keeping the directory together avoids losing content referenced
by the database. The archive and operational keys are not encrypted at rest;
protect the backup accordingly.
Before restoring, keep a separate copy of the existing directory. Restore with
Carrel closed and retain filesystem ownership and permissions. This is a manual
same-installation recovery procedure, not an in-app recovery wizard. Webview
appearance preferences may need to be set again.
Sending the application does not send your archive or identity. A friend starts
their own identity; your second desktop uses Devices pairing. Do not copy your
key files to a friend or use a copied archive as a substitute for device pairing.
The master key is passphrase-encrypted. Its passphrase is needed for identity
authorization operations; Carrel cannot recover it through a central service.
Master-key backup/recovery UI is deferred. Keep the originating desktop and a
private backup safe while testing.
Export subscriptions as OPML from Settings → Sources. Export highlights and
notes as Markdown from Highlights. These are useful portable copies, but they
do not contain the complete identity, archived article cache or sync history.
Use the whole-directory backup when you need that state.
Saved articles remain available. Open the status strip’s Details, Settings →
Sources, or Source activity through the command palette. Retry the affected
source; a failure on one source should not interrupt your current reader/list.
Technical details are available deliberately, separate from the quiet message.
Fetched documents are limited to 16 MiB of decoded bytes; robots policies to
512 KiB. An oversized or unavailable robots policy stops the fetch safely.
An article’s extraction or image failure can leave feed metadata or saved text
available while the full cache needs another attempt.
Today means published within the preceding 24 hours. Fetching an old post does
not change its publication date. Look in Library or the source’s list, newest
publication first. Load older extends that list. Search and filters remain
active until cleared.
Keep both desktops open. In People, check the person’s key/code and choose
Try connection again. Both people must follow each other. Contact-code
availability is not evidence of delivery; the received article is. If connection
information changed, review a new code against the expected public key.
The archive remains useful offline. A failed exchange should not discard your
saved vouch or private notes. Record which step of the friend trial failed,
along with versions, OS/architecture and the quiet People error.
Confirm the package matches your CPU architecture. For macOS pre-alpha builds,
follow first-launch approval. On Linux, include your
distribution, WebKitGTK version if known, and the terminal error in a report.
The current release matrix is not evidence of live GUI testing on every desktop.
Use GitHub Issues with version,
platform, reproduction steps, expected behavior and observed behavior. Share a
minimal public example rather than your archive. Leave article bodies, private
notes, passphrases, keys, invitation text and contact codes out of reports.
For a security issue, use
private reporting.
Use Rust 1.95 or newer and a C/C++ compiler. On macOS, install Xcode Command Line
Tools. Packaging and release scripts use Python 3.11 or newer. On Ubuntu 24.04,
the CI/release environment installs:
Installer builds also need cargo install cargo-about --version 0.9.2 --locked --features cli. The production hook generates dependency license notices before
building the webview. Unresolved licenses fail packaging; the generated HTML is
ignored locally and included in the native license resources.
These versions are recorded build tools, not a claim about the latest upstream
release. There is no Node/npm build step. The Tauri hooks invoke Trunk with the
CSR feature explicitly; a default native frontend build uses SSR for tests.
With just installed, run these from the repository root:
just dev # native app and frontend hot reload
just check # format, native + WASM lint, workspace tests
just fmt # cargo fmt --all
just build # production frontend, app and platform packages
just cli --help # development/diagnostic CLI
Without just, cargo tauri dev and cargo tauri build run from
crates/carrel-app. Workspace tests and checks run from the repository root:
Use CARREL_DATA_DIR and CARREL_CONFIG_DIR to isolate a development profile.
Normal development/test profiles keep line tables for Carrel, omit dependency
debug symbols and disable incremental caches. The optional debugging profile
retains full dependency debugging when you need it.
Install mdbook 0.5.4 with cargo install mdbook --version 0.5.4 --locked.
just docs builds this guide into ignored site/book; just docs-serve
previews it. Sources live under site/src: the introduction uses semantic HTML
inside Markdown, and the guide uses ordinary Markdown. site/theme contains
the shared header, stylesheet, favicons and a small optional appearance-control
script. The default mdBook template still owns search, contents, themes and
chapter navigation. Bundled Inter and Source Serif 4 assets (and their OFL
licenses) are copied from the desktop app into site/src/assets; keep those
copies in step when updating the app’s fonts. No remote assets or additional
build tools are needed. GitHub Pages deploys that output; there is no separate
website repository or application service.
After a site edit, build with just docs and run python3 scripts/check_docs.py
to check local links and anchors. Preview both the introduction and a guide
chapter at desktop and narrow widths, in Light and Dark. Check local search,
contents, keyboard focus, no-JavaScript reading and print layout before opening
a pull request. Generated site/book output stays untracked.
The engineering documents under docs/ remain the source of truth for product,
architecture, schema and interaction decisions. Keep implemented guarantees
distinct from future plans, and update docs in the same change as the code.
Carrel’s release workflow builds a draft prerelease from a version tag.
Draft status gives the maintainer a concrete set of artifacts to inspect before
publishing. It does not describe a stable or fully validated release.
Mac packages are ad-hoc signed, without Developer ID credentials or notarization.
Platform installation guidance is in Getting started.
Windows and Linux arm64 are not in the initial release matrix.
Choose a reviewed commit, run local checks and review the release limitations.
Check the app’s Cargo version and tauri.conf.json version agree.
Create and push an annotated version tag, for example v0.1.0-alpha.2, on
the reviewed commit. Tagging starts native builds; the tag must match the
app version. Do not move an existing published tag.
Inspect the workflow’s draft prerelease and its packages, source archive,
release notes and SHA256SUMS. Require branch CI to pass on the release commit
before publishing; artifact preparation can run alongside those checks.
Test installation/launch with the development server stopped. Complete the
applicable native/file-picker and physical peer checks, recording actual
evidence and remaining limitations. Publish the draft when ready.
The workflow can also be dispatched for an existing tag. Reruns keep the release
draft and replace its artifacts; they refuse to overwrite a published release.
The source commit is fixed before matrix builds start. Each build uses
Cargo.lock and pinned desktop tooling. This is repeatable release automation,
not a claim of byte-for-byte reproducible binaries.
Production builds generate Rust dependency notices using Cargo About 0.9.2 and
the checked-in about.toml policy/template. The native package includes those
notices, Carrel’s license/grant, and the separate font/icon notices. Generated
notices and build output are not committed.
Download SHA256SUMS and the packages you intend to install from the same
release. On macOS:
shasum -a 256 -c SHA256SUMS
On Linux:
sha256sum -c SHA256SUMS
The manifest covers every packaged artifact and the source archive. Checking
the full manifest requires all listed files in the same directory; missing
files are reported as missing. Checksums establish that bytes match the release
manifest, not an independent publisher signature.
The GitHub Pages guide deploys separately from main. The repository is canonical;
generated website output, local archives and signing credentials are not committed.