Reading the repo

Opening the box…

How to set up karakeep (karakeep-app/karakeep) · gitmanual

Assembly instructions

karakeep-app/karakeep

A self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search

Node.js#bookmark-manager#bookmarks#bookmarks-manager#nextjs

Difficulty: Moderate
Time: about 15 min
Stars: ★ 30,295
Activity: Updated this month
License: AGPL-3.0
Open issues: 728
Got it running: Be the first
Looked up: 2 h ago

Saved setup from 2 h ago

Start here

Website ↗karakeep.comThe project's own site.

Launch script in the repo

The maintainers included start-dev.sh. Run it from the cloned folder after reading it.

bash start-dev.sh

Will it work on my device?

Yes, it runs on macOS

You'll build it yourself with Node.js.

Checking for

6 steps on macOS

Clone the repository

Needs Git: xcode-select --install

git clone https://github.com/karakeep-app/karakeep.git
cd karakeep

Install the required runtimes

Node.js 24

# needs nvm: brew install nvm (or https://github.com/nvm-sh/nvm)
nvm install
nvm use

3
Configure environment variables
Fill in secrets: KARAKEEP_API_KEY, OPENAI_API_KEY, INFERENCE_MAX_OUTPUT_TOKENS, INFERENCE_USE_MAX_COMPLETION_TOKENS, MEILI_MASTER_KEY, NEXTAUTH_SECRET
```
cp .env.sample .env
```
4
Install dependencies
```
corepack enable
pnpm install
```
5
Run it
```
pnpm dev
```
6
Run the tests
```
pnpm test
```

Did you get it running?

No reports for macOS yet.

Still stuck? Get a written guide

Claude reads the 14 key files and writes a step-by-step guide for macOS. Once written, it's saved for everyone.

Parts list

1×Node.js 24runtime
1×pnpm pnpm@11.28.9package manager

16× settings in .env

KARAKEEP_API_KEYsecret
KARAKEEP_SERVER_ADDR
COMPARISON_MODE
MODEL1_NAME
MODEL2_NAME
OPENAI_API_KEYsecret
OPENAI_BASE_URL
COMPARE_LIMIT
INFERENCE_CONTEXT_LENGTH
INFERENCE_MAX_OUTPUT_TOKENSsecret
INFERENCE_USE_MAX_COMPLETION_TOKENSsecret
DATA_DIR
MEILI_ADDR
MEILI_MASTER_KEYsecret
NEXTAUTH_URL
NEXTAUTH_SECRETsecret

Share this manual

Good to know

Monorepo (workspaces) — install from the repo root.
Has AGENTS.md — instructions for coding agents. You can open Claude Code (or another agent) in the cloned folder and ask it to do the setup for you.
Nested projects: apps/browser-extension/package.json, apps/cli/package.json, apps/landing/package.json, apps/mcp/package.json and 11 more

package.json scripts (25)

buildturbo build
devturbo dev --parallel
cleangit clean -xdf node_modules
clean:workspacesturbo clean
db:generatepnpm --filter @karakeep/db run generate
db:migratepnpm --filter @karakeep/db run migrate
db:migrate:queuepnpm --filter @karakeep/workers run migrate:queue
db:studiopnpm --filter @karakeep/db studio
seed:applypnpm --filter @karakeep/seed-snapshot run apply
seed:snapshotpnpm --filter @karakeep/seed-snapshot run snapshot
workerspnpm --filter @karakeep/workers run start
webpnpm --filter @karakeep/web run dev
web:portlesspnpm --filter @karakeep/web run dev:portless
dev:worktreebash scripts/dev-worktree.sh
androidpnpm --filter @karakeep/mobile android
iospnpm --filter @karakeep/mobile ios
preparehusky
formatturbo format --continue
format:fixturbo format:fix --continue
lintturbo lint --continue
lint:fixturbo lint:fix --continue
testturbo test
typecheckturbo typecheck
preflightturbo run typecheck lint format
preflight:fixturbo run typecheck lint:fix format:fix

Files we read (14)

.env.sample

.github/workflows/android.yml

.github/workflows/chrome.yml

.github/workflows/ci.yml

.github/workflows/cli.yml

.github/workflows/docker.yml

.github/workflows/extension.yml

.nvmrc

CONTRIBUTING.md

README.md

docker/.env.sample

package.json

pnpm-workspace.yaml

tools/compare-models/.env.example

Branch main · 2,332 files in the repo

Opening the box…

Start here

Yes, it runs on macOS

6 steps on macOS

Clone the repository

Install the required runtimes

Configure environment variables

Install dependencies

Run it

Run the tests

Did you get it running?

Still stuck? Get a written guide