Postmarks is a single-user bookmarking website that you host yourself and connect to the Fediverse, built for one person who wants to own their bookmarks while still sharing them with Mastodon, FireFish, and any other text-based ActivityPub platform.
What it is
Postmarks is a JavaScript bookmarking site with a federation layer on top. It runs as an ActivityPub server in its own right, so the account it publishes is a real actor on the Fediverse rather than a profile on someone else's service. The owner adds, edits, and deletes bookmarks through a web interface, and those actions require a valid login. The same site is readable by followers elsewhere: other Postmarks instances, Mastodon, FireFish, or any text-based ActivityPub platform, as listed in its topics alongside activitypub, bookmark-manager, bookmarking-server, and mastodon-compatible. It is released under the MIT licence and carries 546 stars, 42 forks, and 78 open issues.
The concrete problem it solves is ownership of the collection. A bookmark is a durable personal record, and on a hosted platform it lives inside an account someone else controls, under someone else's rules, reachable only through someone else's client. Postmarks moves the record onto hardware the owner operates and gives it an address that other people can follow. The README frames this directly as "a bookmarking site that you own yourself." It does not name a specific product it replaces; the ownership claim, plus the ActivityPub actor, is the substitute. The design is deliberately single-user, so there is no shared tenancy, no signup flow, and no per-seat model to reason about.
Key capabilities
- Federates as an ActivityPub actor, interacting with other Postmarks sites, Mastodon, FireFish, and any text-based ActivityPub platform, per the
activitypub-server and mastodon-compatible topics.
- Publishes an identity from
account.json, copied from account.json.example, where the owner sets @username, display name, bio, and avatar.
- Falls back to the actor name
bookmarks when no username is set, so the account resolves as @bookmarks@your-host on the Fediverse.
- Gates all writes behind login using an
ADMIN_KEY password and a SESSION_SECRET string used to hash the session for a secure cookie.
- Offers a bookmarklet in the Admin section, plus "Add" links in the site header and footer, for capturing bookmarks while browsing.
- Supports importing bookmarks and adjusting settings from the Admin area after login via the footer Admin link.
- Adds a home page link for Mastodon profile verification when
MASTODON_ACCOUNT is set in .env, following the Mastodon verification documentation.
Who uses it and how
- A single individual who wants one owned, federated bookmark feed, since the
ADMIN_KEY login model assumes one operator rather than a team.
- Self-hosters running the app behind a reverse proxy, configured to forward traffic from the Postmarks hostname to port 3000, or to the port set through
PORT= in .env.
- Operators who prefer container deployment, using
docker compose up or docker-compose up, or who drop npm run start into any app or container management tool or SaaS provider that accepts a defined entrypoint.
- Fediverse participants who want their saved links visible to followers on Mastodon and FireFish without maintaining a separate presence there.
- Contributors working on the frontend, which is largely lifted from Glitch starter projects, with the process documented in
CONTRIBUTING.md.
Getting started
Deployment is either docker compose up (or docker-compose up, depending on the Docker version) or npm run start, after creating a .env file with PUBLIC_BASE_URL, ADMIN_KEY, and SESSION_SECRET, and an account.json file for the actor profile. A hosted instance is available at https://postmarks.glitch.me, and the app listens on port 3000 by default.
How it compares
No list of paid products that Postmarks replaces is provided in the facts, and no competing bookmark manager is named there either. Where it fits is by protocol: it federates with Mastodon and FireFish rather than competing with them, and in this registry it stands alone as a self-hosted, single-user, ActivityPub-native bookmarking server.
When to use it — and when not to
Pick Postmarks if one person should own the bookmark collection, wants it reachable over ActivityPub, and is comfortable operating a Node process on port 3000 with a reverse proxy, a .env file, and a hand-edited account.json. Do not pick it for multi-user or team bookmarking, because the login model is a single ADMIN_KEY and the project describes itself as single-user. Anyone needing documented database, object-storage, or SMTP configuration will not find it here, since the setup steps cover environment variables and account.json only, and the 78 open issues against 42 forks is worth weighing before committing.
project readme (upstream, from github) — read inline
Postmarks
About this project
Postmarks is a bookmarking site that you own yourself and can connect the Fediverse, interacting with other Postmarks sites as well as Mastodon/FireFish/any text-based ActivityPub platform. You can read more about it here:
The site allows the owner to add, edit and delete bookmarks, but only if a valid login is provided.
Check the setup below to understand how to do that!
Setting up your site
To set your app up:
- Create a
.env file in the root of the project.
- Add the line
PUBLIC_BASE_URL= to your .env where \ is the hostname of your instance.
- Add the line
ADMIN_KEY= to your .env where \ is the password you'll enter when the browser prompts you, and another line for SESSION_SECRET= where \ is a random string used when hashing your session for use in a secure cookie.
- Make a file called
account.json in the project root. Copy the contents of account.json.example into it and edit the values to set your @username, display name, bio, and avatar.
- If you don't set a username, your default actor name will be 'bookmarks', so people will find you on the fediverse
@bookmarks@.
- You should update the avatar field in order to not hotlink to another server-- the value must be an absolute URL. If you change out the hostname and leave the existing filename, you will link to a statically hosted image on your server that was downloaded along with the rest of the Postmarks repo.
If you are using Docker compose you can run docker compose up or docker-compose up (depending on the version of Docker you are using) and Postmarks should be running. Otherwise, run npm run start on the command line. You can also use npm run start in any kind of app/container-management tool or SaaS provider that lets you define an entrypoint.
By default, Postmarks runs on port 3000. You can change this with a PORT= entry in your .env. If you're running Postmarks behind a reverse proxy, configure it to send traffic from your Postmarks hostname to this port.
At this point, you should be able to load Postmarks in your browser using the hostname you configured. If you don't have a proxy to direct from the hostname, you'll need to add the port to the URL. In basic local development mode it should be available at http://localhost:3000 .
Once you're looking at the web interface in your browser, click on the Admin link in the footer, and enter the password (whatever you set ADMIN_KEY to in the .env). You should be logged in, at which point you can configure various settings, import bookmarks, and use the "Add" links in the header and footer (as well as the bookmarklet, available in the Admin section) to save new bookmarks.
Mastodon Verification
Setting MASTODON_ACCOUNT in the .env file will cause a link to be added to the Postmarks home page that can be used for verification with your Mastodon account. See the Mastodon documentation for more details.
Development & Contributions
See CONTRIBUTING.md for more information on how to work with Postmarks' development environment as well
as how to submit your changes for review.
Acknowledgments
- The "Postmarks" name is compliments of Casey C (no relation to Casey K), who brainstormed dozens of ideas for the name when Casey was first trying to rename the project. Thank you!
- Postmarks (in its default configuration) uses an edited version of Eynav Raphael's "Postmark Stamp" icon from The Noun Project.
- It also makes use of free fonts including Averia Sans and Public Sans.
- Much of the original form of the site's frontend is lifted from the starter projects available on Glitch. Thank you to all the people who have contributed to those projects over the years!
- Much of the original backend of the site is based off of Darius Kazemi's express-activitypub repo. I made a point not to just clone his repo from the start, but then ended up retyping most of it as I learned how things work. While some pieces have been upgraded, much of Darius' work creates the foundation for Postmarks' ActivityPub functionality.