# Project pack: Karakeep @ 5c72fa9

Facts about **Karakeep** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> Karakeep is a read-it-later and bookmark app for people who save everything. Save a web link, a quick note, a photo or a PDF from your browser or phone. It fetches the page title and picture, keeps a copy in case the page disappears, and can tag and summarise things for you with AI. Search everything you have saved, sort it into lists and share lists with others. It runs on your own computer or server.

## Setup path (checked 2026-11-03)
- **Needs Docker.** Tell the person before any setup work; no light non-Docker route is documented upstream. Docker Desktop on Windows may need a computer restart and an admin-only Windows feature (virtualisation); say so and let the person decide.
- Verdict source: https://docs.karakeep.app/installation/docker
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/karakeep-app/karakeep
- Pinned commit: `5c72fa95807df2d7dd96f0c9ac52a536b5bf3cfc`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/karakeep-app/karakeep/archive/5c72fa95807df2d7dd96f0c9ac52a536b5bf3cfc.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://docs.karakeep.app
- Live demo: https://try.karakeep.app (email: demo@karakeep.app / password: demodemo). Read-only demo seeded with sample content.
- Licence: **AGPL-3.0-only**. Free to use and change. If you run a changed version that other people use over the internet (not just you or your household), you must offer them your source code under the same licence. Private use has no extra obligations.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/karakeep-app/karakeep bespoke-karakeep
  cd bespoke-karakeep
  git checkout --detach 5c72fa95807df2d7dd96f0c9ac52a536b5bf3cfc
  # Prepare development requirements and local configuration first.
  # Setup notes: starts Meilisearch and Chrome in Docker, then web (:3000) and workers
  pnpm install && ./start-dev.sh
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  mkdir karakeep-app && cd karakeep-app
  wget https://raw.githubusercontent.com/karakeep-app/karakeep/main/docker/docker-compose.yml
  # create a .env with KARAKEEP_VERSION=release, NEXTAUTH_SECRET, MEILI_MASTER_KEY and NEXTAUTH_URL=http://localhost:3000
  docker compose up -d
  # then open http://localhost:3000
  ```
- Tools these commands use: Docker with Docker Compose, For development, Node.js, pnpm and Docker (for Meilisearch and Chrome)
- Develop: `pnpm install && ./start-dev.sh   # starts Meilisearch and Chrome in Docker, then web (:3000) and workers`
- Test: `pnpm test`
- Check/lint: `pnpm typecheck && pnpm lint && pnpm format`
- Stack: typescript (Next.js, React, Tailwind CSS, shadcn/ui, tRPC, Hono, Drizzle ORM, Puppeteer, Expo). Difficulty for a non-developer with an AI: **moderate**. Rules, webhooks, AI prompts, RSS feeds and the API cover a lot without code. Code changes mean a pnpm/Turborepo monorepo: a Next.js web app, background workers, and tRPC routers holding most of the logic. Running it needs Meilisearch and a headless Chrome alongside.
- The project's own AI instructions, in the repository: `AGENTS.md`, `CLAUDE.md`.
Personal data: **yes**. Stored in: SQLite database and saved files (images, PDFs, archives) in the data volume (/data); search index in the meilisearch volume. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/karakeep/5c72fa9/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/karakeep/5c72fa9/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/karakeep/5c72fa9/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/karakeep/5c72fa9/r3/SKILL.md)