# Project pack: Karakeep @ 5c72fa9

Facts about **Karakeep** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and 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.

## Version and source
- Repository: https://github.com/karakeep-app/karakeep
- Pinned commit: `5c72fa95807df2d7dd96f0c9ac52a536b5bf3cfc`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/karakeep-app/karakeep/archive/5c72fa95807df2d7dd96f0c9ac52a536b5bf3cfc.zip
- 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.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```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
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```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
  ```

- Needs: 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
Read these in the repository before changing code: `AGENTS.md`, `CLAUDE.md`.

## Customisation points (settings → extend → code)
- **ai-tagging-and-prompts** [settings]: Turn AI tagging and summaries on or off, choose a local or cloud model, and add your own instructions. → `Settings → AI (apps/web/app/settings/ai/page.tsx); INFERENCE_* and OLLAMA_BASE_URL variables`
- **rules** [settings]: Automatic actions, e.g. any link from a recipe site goes into the Recipes list. → `Settings → Rules (docs/docs/04-using-karakeep/advanced-workflows.md)`
- **lists-and-sharing** [settings]: Organise saved things and share a list with a partner or publicly. → `Lists, smart lists and shared/public lists (docs/docs/04-using-karakeep/lists.md)`
- **feeds-and-import** [settings]: Save new posts from favourite sites automatically, or import from Pocket, Chrome and others. → `Settings → Feeds / Import (docs/docs/05-integrations/06-rss-feeds.md, docs/docs/04-using-karakeep/import.md)`
- **webhooks** [extend]: Tell another app (n8n, Home Assistant, a chat bot) whenever something is saved. → `Settings → Webhooks (apps/web/app/settings/webhooks/page.tsx)`
- **api-cli-mcp** [extend]: Save from scripts or phone shortcuts, or let an AI assistant search your bookmarks. → `REST API with API keys (Settings → API Keys), CLI and MCP server (docs/docs/05-integrations/)`
- **web-ui** [code]: New pages or views in the web app. → `apps/web/app/dashboard/**, apps/web/components/** (shadcn components in apps/web/components/ui), text in apps/web/lib/i18n/locales/en/translation.json`
- **logic-and-data** [code]: New behaviour or data. Database changes need a generated migration. → `packages/trpc/routers/ (logic), packages/db/schema.ts + pnpm db:generate, apps/workers/workers/ (background jobs)`

## Must keep working
- Saved bookmarks, archives and uploaded files in the data volume. Back up before upgrades or code changes.
- Privacy between users. One person's bookmarks must not appear in another's account unless a list is shared.
- The REST API, which the browser extensions and phone apps rely on. Don't change existing fields.
- Database changes need a Drizzle migration (pnpm db:generate).

## Staying updatable
Rules, webhooks, AI settings, feeds, the API, the CLI and the MCP server cover most needs without a fork. For code, follow upstream AGENTS.md and run pnpm preflight before proposing changes.

## Data, costs and safety
- Personal data: **yes**. Stored in: SQLite database and saved files (images, PDFs, archives) in the data volume (/data); search index in the meilisearch volume. Back up the data volume. Karakeep also has backups in Settings → Backups. The search index can be rebuilt, so the data volume matters most.
- Service: Meilisearch (search engine) (required, free (included in the compose file)): Full-text search across everything you save.
- Service: Headless Chrome (required, free (included in the compose file)): Visits saved links to fetch titles, pictures, text and archived copies.
- Service: AI provider (OpenAI, an OpenAI-compatible API or local Ollama) (optional, pay-per-use for OpenAI, free with local Ollama): Automatic tags and summaries, and reading text from images.
- Setting `NEXTAUTH_SECRET` (**secret**: the person enters it themselves, never in chat): Random secret for logins. Generate with openssl rand -base64 36. Never paste it into an AI chat.
- Setting `MEILI_MASTER_KEY` (**secret**: the person enters it themselves, never in chat): Random key protecting the search engine. Never paste it into an AI chat.
- Setting `NEXTAUTH_URL`: The address you open Karakeep at, e.g. http://localhost:3000.
- Setting `KARAKEEP_VERSION`: Which release to run (release, or a pinned version number).
- Setting `DISABLE_SIGNUPS`: Set to true after creating your accounts so strangers can't sign up.
- Setting `OPENAI_API_KEY` (**secret**: the person enters it themselves, never in chat): Only if you use OpenAI for tagging. Never paste it into an AI chat.
- Setting `OLLAMA_BASE_URL`: Address of a local Ollama server, for AI tagging that stays at home.
- Setting `INFERENCE_LANG`: Language for AI-generated tags (default english).
- Setting `CRAWLER_FULL_PAGE_ARCHIVE`: Keep a full copy of every saved page, so it survives if the site disappears.
- Set DISABLE_SIGNUPS=true once your accounts exist if the server is reachable from the internet.
- AI features send page text to the chosen provider. Use Ollama to keep everything at home.
- Headless Chrome visits every saved link from your server. Read upstream's security considerations before exposing it publicly.

---

# Customising Karakeep

Karakeep is a TypeScript monorepo (Next.js web app, background workers, tRPC). **Most personal adaptations are settings**: AI, rules, lists, feeds and webhooks. Exhaust levels 1 and 2 before touching code.

## Level 1: Settings (no code)
- **AI tagging and summaries:** Settings → AI. Choose what gets tagged and add your own instructions (prompts). Pick the provider with environment variables: `OPENAI_API_KEY`, or `OLLAMA_BASE_URL` plus `INFERENCE_TEXT_MODEL`/`INFERENCE_IMAGE_MODEL` for a local model. See `docs/docs/03-configuration/02-different-ai-providers.md`.
- **Tag language:** `INFERENCE_LANG` (e.g. `english`, `german`).
- **Rules:** Settings → Rules. If-this-then-that rules that tag, favourite, archive or move bookmarks into lists, e.g. everything from one website goes into a list. See `docs/docs/04-using-karakeep/advanced-workflows.md`.
- **Lists:** manual lists, *smart lists* (saved searches) and shared lists (public read-only link or collaborators by email). See `docs/docs/04-using-karakeep/lists.md`.
- **Search:** a query language such as `#recipes is:fav after:2025-01-01`. See `docs/docs/04-using-karakeep/search-query-language.md`.
- **Feeds and imports:** Settings → Feeds (RSS) and Settings → Import (Chrome, Pocket, Omnivore, Netscape HTML).
- **Archiving:** `CRAWLER_FULL_PAGE_ARCHIVE=true` keeps a full copy of every page; `CRAWLER_VIDEO_DOWNLOAD=true` saves videos.
- **Accounts:** `DISABLE_SIGNUPS=true` once your family's accounts exist.

All environment variables: `docs/docs/03-configuration/01-environment-variables.md`.

## Level 2: Extend (no fork)
- **Webhooks:** Settings → Webhooks. Karakeep calls your URL when bookmarks are created or crawled (n8n, Home Assistant, a chat bot).
- **REST API** with a key from Settings → API Keys. Endpoints are documented under `docs/docs/api/`.
- **CLI:** `docs/docs/05-integrations/02-command-line.md`. Good for scripts and scheduled jobs.
- **MCP server:** let an AI assistant search and add bookmarks (`docs/docs/05-integrations/03-mcp.md`).
- **Browser extensions and phone apps:** save from anywhere (`docs/docs/04-using-karakeep/quick-sharing.md`).

## Level 3: Code
Read upstream `AGENTS.md` first.

| Change | Where |
|---|---|
| New page or view | `apps/web/app/dashboard/**` (e.g. `lists/`, `tags/`, `search/`) |
| Components | `apps/web/components/**` (shadcn/ui pieces in `apps/web/components/ui/`) |
| Interface text | `apps/web/lib/i18n/locales/en/translation.json` |
| Business logic and API | `packages/trpc/routers/` (e.g. `bookmarks.ts`, `lists.ts`, `rules.ts`) |
| New data | `packages/db/schema.ts`, then `pnpm db:generate --name describe_change` |
| Background jobs | `apps/workers/workers/` (crawler, AI, feeds, webhooks, rule engine) |
| AI prompts (defaults) | `packages/shared/prompts.ts` |

## Running locally
- **Just use it:**
  1. `mkdir karakeep-app && cd karakeep-app`
  2. Download `docker/docker-compose.yml` into it.
  3. Create `.env` with `KARAKEEP_VERSION=release`, `NEXTAUTH_SECRET` and `MEILI_MASTER_KEY` (random values from `openssl rand -base64 36`) and `NEXTAUTH_URL=http://localhost:3000`.
  4. `docker compose up -d`, then open http://localhost:3000 and sign up.
- **Develop:**
  1. Install Node.js, pnpm and Docker.
  2. Run `pnpm install`.
  3. Run `./start-dev.sh` (starts Meilisearch and Chrome in Docker, then the web app and workers).
  4. Open http://localhost:3000.
  - Manual alternative: `pnpm run db:migrate`, then `pnpm web` and `pnpm workers` in two terminals.
- **Check:** `pnpm preflight` (typecheck, lint and format) and `pnpm test`.

## Pitfalls
- Back up the data volume before upgrades or code changes.
- Every `.env` change needs `docker compose up -d` again.
- Without the Chrome container, links are saved but titles, pictures and archives are missing.
- AI tagging with small local models can be slow or odd. Try a bigger model or adjust the prompt before changing code.
- Keep API changes backwards compatible; the browser extensions and phone apps depend on them.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/karakeep/5c72fa9/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/karakeep/5c72fa9/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/karakeep/5c72fa9/r2/SKILL.md)