Karakeep is a self-hostable bookmark-everything app for saving links, notes, images, PDFs, and web pages, then finding them again with fast search, lists, highlights, and optional AI tagging/summarization.

This repository is not the upstream Karakeep repo. It is an opinionated personal fork of karakeep-app/karakeep focused on UX, QoL, and personal operator workflow changes while staying close to upstream.

What this repository is

This fork keeps the upstream Karakeep product intact in spirit, but documents and operates it as a real personal deployment:

• Origin: absolutepraya/karakeep
• Upstream: karakeep-app/karakeep
• Focus: UX polish, quality-of-life improvements, and personal deployment ergonomics
• Local dev: one-command workflow via pnpm dev:start
• Deploy model: pull-based Docker image delivery via GHCR + Watchtower

If you want the main project, releases, or community-first contribution flow, start with the upstream repo:

• Upstream repo: https://github.com/karakeep-app/karakeep
• Upstream docs: https://docs.karakeep.app

If you are here to work on this fork, the most important repo-specific guide is:

• docs/fork-setup.md

What Karakeep does

Karakeep can:

• save links, notes, images, and PDFs
• fetch link titles, descriptions, and preview images automatically
• organize bookmarks into lists and tags
• support collaborative lists
• provide full-text search across saved content
• run AI tagging and summarization (including local-model setups)
• archive pages to reduce link rot
• save and revisit highlights
• sync with browser workflows through extensions, RSS, CLI, API, and MCP tooling

Key features

• 🔗 Bookmark links, store notes, images, and PDFs
• 📋 Organize bookmarks into lists
• 👥 Collaborate with others on shared lists
• 🔎 Search across saved content
• ✨ Automatic AI tagging and summarization
• 🖍️ Save highlights from your reading
• 🗄️ Archive full pages to protect against link rot
• 📰 Auto-hoard from RSS feeds
• 🔌 REST API, SDKs, CLI, and MCP server
• 📱 Browser extension + mobile apps
• 💾 Self-hosting first

Quick start for this fork

Preferred local development

From the repository root:

pnpm install

ln -sf ../../.env apps/web/.env
ln -sf ../../.env apps/workers/.env
ln -sf ../../.env packages/db/.env

pnpm db:migrate
pnpm dev:start

That starts:

• the web app
• background workers
• Meilisearch in Docker
• headless Chrome in Docker

Then open:

• http://localhost:3000

Useful variants:

pnpm dev:start -d
pnpm dev:stop

Manual split-terminal development

pnpm web
pnpm workers

Meilisearch and headless Chrome are optional for booting the app, but required for full search/crawling behavior.

Pull production state into local dev

The helper below pulls the production /data state from the VPS into your local DATA_DIR.

pnpm prod:pull-state
pnpm prod:pull-state --dry-run

The command replaces local development state by default, first backing up the current DATA_DIR. It always pulls the full /data volume, including SQLite files and stored assets. Use --dry-run to inspect the plan without replacing local state.

Required root .env keys:

• DATA_DIR
• KARAKEEP_PROD_SSH_HOST
• KARAKEEP_PROD_COMPOSE_DIR

Optional root .env keys:

• KARAKEEP_PROD_SSH_USER
• KARAKEEP_PROD_COMPOSE_SERVICE
• KARAKEEP_PROD_EXPORT_IMAGE

Full fork/operator setup

For the complete local-dev and deploy workflow, read:

• docs/fork-setup.md

Documentation map

For this fork

• Fork/local dev/deploy guide: docs/fork-setup.md
• Docs-site development guide: docs/README.md
• Contribution guidance for this repo: CONTRIBUTING.md

For upstream Karakeep product usage

• Main docs: https://docs.karakeep.app
• Installation: https://docs.karakeep.app
• Configuration: https://docs.karakeep.app
• Development docs: https://docs.karakeep.app
• API docs: https://docs.karakeep.app/api

Demo

Upstream maintains the public demo at:

• https://try.karakeep.app

Demo credentials:

email: demo@karakeep.app
password: demodemo

The demo is read-only.

About the name

Karakeep is inspired by the Arabic word كراكيب (karakeeb), a colloquial term for miscellaneous clutter, odds and ends, or things that look messy but still feel worth keeping. It fits a personal library for links, notes, screenshots, and all the other things you are not ready to lose.

Tech stack

• Web: Next.js, React, TypeScript, Tailwind CSS
• API: Hono + tRPC
• Database: Drizzle ORM over SQLite (better-sqlite3)
• Search: Meilisearch
• Crawling: headless Chrome / browser worker flow
• Tooling: pnpm, Turborepo, oxfmt, oxlint, Vitest

Repo-specific development notes

This fork intentionally differs from upstream in a few practical ways:

• deploys are pull-based rather than SSH push-based
• the canonical production compose lives at deploy/docker-compose.prod.yml
• knip and react.doctor are present as additional quality tooling
• react-grab is loaded only in local development for component/source capture

Contributing

There are two contribution paths:

1. Upstream Karakeep contributions

   • Use https://github.com/karakeep-app/karakeep
   • Follow the upstream community process

2. Fork-specific contributions for this repo

   • Use this repository
   • Read CONTRIBUTING.md
   • Prefer changes that are explicitly valuable for this fork’s UX, operator flow, or maintenance model

Community and support

• Upstream Discord: https://discord.gg/NrgeYywsFh
• Upstream project site: https://karakeep.app
• Upstream cloud: https://cloud.karakeep.app

License

This fork remains licensed under AGPL-3.0.

Upstream Karakeep is developed by Localhost Labs Ltd. This repository is a personal fork, not the canonical upstream source.